Agentic Workflow Guide Skill

Agentic Workflow Guide

Design, review, and improve agent workflows based on proven principles.

この SKILL の基本姿勢は、agent を増やすことではなく、必要最小の primitive で解くこと。 context が膨らんだときも、まずは split / compact / reference 化を考え、いきなり multi-agent にしない。

Primitive First

Do not start with multi-agent by default.

Single focused slash task -> Prompt
Always-on or file-scoped guidance -> Instruction
Reusable workflow with bundled assets -> Skill
Persona, tool restrictions, delegation, or handoffs -> Agent
Deterministic enforcement -> Hook

If the ask does not require an Agent, stop and use the simpler primitive.

この primitive 選択表が SSOT。skill-creator-plus / skill-finder などの判定表は「そのスキルを使うべきか」の即時ゲートとして扱い、基準がずれたらここに合わせる。

Selection details: references/customization-decision.md

When to Use

| Action | Triggers | | ---------- | ----------------------------------------------------------------------------- | | Create | New .agent.md, .instructions.md, .prompt.md, AGENTS.md, or workflow architecture | | Review | Orchestrator not delegating, design principle check, context overflow | | Update | Adding Handoffs, improving delegation, tool configuration | | Debug | Agent not found, subagent not working, picker visibility, access control | | Decide | Determining whether multi-agent is justified or a simpler primitive is enough |

Core Principles

Simplicity First: より単純な primitive で解けるなら agent 化しない
SSOT / SRP: 情報源と責務の分割を守る
Fail Fast: エラーは早く止める
Feedback Loop: 各段で検証できるようにする
Context Discipline: context が膨らんだら compact / split / retrieve を検討する

Principle details: references/design-principles.md

Pattern Selection

Prompt Chaining: 順序のある段階処理
Routing: 入力タイプで分岐する処理
Parallelization: 独立タスクを並列で進める処理
Orchestrator-Workers: 動的に subtasks を分解する処理
Evaluator-Optimizer: 品質基準を満たすまで反復する処理

Every loop needs explicit stop conditions.

Pattern details: references/workflow-patterns/overview.md

Design Workflow

Extract from conversation Repeated behavior, tool preferences, workflow shape, and obvious specialization を先に拾う。
Choose primitive + scope Prompt / instruction / skill / agent / hook と workspace / profile を決める。
Clarify only the gaps 挙動を変える曖昧さだけ聞く。
Check escalation agent や multi-agent が本当に必要か確認する。
Choose pattern complexity が上がるなら pattern を明示して設計する。
Review before expanding split / compact / reference 化で済まないかを見る。
Implement and iterate 最初から完成形を狙わず、弱い箇所を見つけて詰める。

Rule Placement

汎用的な workflow 設計原則は、この SKILL と references/ を SSOT にする。
repo local の .instructions.md には workspace 固有の差分だけを残す。差分が無い generic instruction は merge back して削除候補にする。
IR は原則 in-memory で扱う。validator、script、deterministic handoff が必要な場合だけ中間 file を materialize し、不要になったら片付ける。
scheduler / service / config など決定論的な state mutation は、AI/UI loop ではなく direct script / API で現状確認 -> 最小変更 -> live read-back まで行う。LLM は scope と整合対象の判断に限定する。

Escalation Rules

L0: Single Prompt
L1: Prompt + Instructions
L2: Single Agent
L3: Multi-Agent

Prefer the lowest level that solves the problem cleanly.

Quick signals:

Prompt > 50 lines
Steps > 5
"missed" / "overlooked" errorsが続く
Multiple responsibilities in one agent
Context > 70%

Threshold details: references/splitting-criteria.md

Entry Boundary Smells

Instruction Elevation Smell

always-loaded entry において、強い命令語が直下の catalog、reference list、workflow map、rule inventory を会話の優先レイヤーへ昇格させる状態。

Always-Loaded Entry Budget

always-loaded entry は会話境界と最小 guardrail のみを持つ。catalog、詳細手順、広い参照一覧は docs、README、task-specific assets へ退避する。

Runtime Boundary Rule

Review assets improve design quality and detect structural problems. Default conversational behavior is controlled by always-loaded entries.

Casual Input Safety Check

Lightweight inputs such as greetings, short Q&A, and numeric-only replies should not be force-routed into task intake unless the task context is explicit.

Review Gates

[ ] Primitive choice is simpler than agent if possible
[ ] Placement is appropriate and always-loaded entry files stay thin
[ ] New additions are proposed only after delete / merge / split / move options are checked
[ ] Single responsibility per agent is preserved
[ ] Errors can be detected and stopped early
[ ] Results are verifiable at each step
[ ] Deterministic parts are offloaded to scripts / IR / hooks, and state changes are confirmed by reading authoritative live state back (not LLM/UI loops)

Full checklist: references/review-checklist.md

Reference Map

Core references: primitive decision, design principles, workflow patterns, splitting criteria, review checklist, and context management.

For scheduled workflows, use scheduled runtime bindings. For delegated evidence and append-only current-state extraction, see orchestrator-workers and IR architecture.

agent Quick Fix

When an orchestrator promises delegation but works directly, make the delegation requirement explicit and verifiable. See agent-guide.md.

Tools Reference

Use references/agent-template.md for tool mapping and stable agent scaffold details.

Done Criteria

[ ] Primitive and scope selected intentionally
[ ] Workflow pattern selected and confirmed with user
[ ] New or updated assets have clear Role/Workflow/Done Criteria where applicable
[ ] Design principles checklist passed
[ ] Recommendations are classified as delete / merge / split / move / add / keep where applicable
[ ] Always-on instruction boundaries and DRY / SSOT risks are explicitly reviewed when copilot-instructions.md or AGENTS.md are in scope
[ ] New agent / workflow assets are registered in the appropriate catalog or docs when needed
[ ] AGENTS.md is updated only when shared guardrails or entry behavior need to change
[ ] Long-running or ad-hoc terminals/tasks started during the workflow are closed, or remaining terminals are explicitly reported with a reason
[ ] Async operations are verified by live state before being called complete; if blocked by retention/locks/background platform work, the blocker and next check condition are explicit

Agent Skills: Agentic Workflow Guide

Install this agent skill to your local

Skill Files