agentic-workflow-guide

name	agentic-workflow-guide
description	Design, review, and debug agent workflows, and decide when a request should use a prompt, instruction, skill, agent, or hook before escalating to multi-agent design. Use for .agent.md / .instructions.md / .prompt.md / AGENTS.md work, workflow architecture, orchestration planning, or when agent workflows may be overkill. Triggers on 'agent workflow', 'create agent', 'ワークフロー設計', 'orchestrator'.
argument-hint	作りたい .agent.md / .instructions.md / .prompt.md / AGENTS.md、設計したい workflow、または困っている症状
user-invocable	true
license	CC BY-NC-SA 4.0
metadata	{"author":"yamapan (https://github.com/aktsmm)"}

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.

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

1. Extract from conversation Repeated behavior, tool preferences, workflow shape, and obvious specialization を先に拾う。
2. Choose primitive + scope Prompt / instruction / skill / agent / hook と workspace / profile を決める。
3. Clarify only the gaps 挙動を変える曖昧さだけ聞く。
4. Check escalation agent や multi-agent が本当に必要か確認する。
5. Choose pattern complexity が上がるなら pattern を明示して設計する。
6. Review before expanding split / compact / reference 化で済まないかを見る。
7. 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 し、不要になったら片付ける。

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
• Repo-local design instructions keep workspace-specific delta only; generic guidance lives in this skill or its references
• Frontmatter review validates file-type-specific supported and unsupported properties, not just missing fields
• copilot-instructions.md and AGENTS.md keep distinct always-on roles and do not duplicate intake / routing / catalog content
• always-loaded entries do not combine strong directive wording with catalogs or reference inventories
• findings distinguish runtime-affected entry issues from review-only asset issues
• Single responsibility per agent is preserved
• Errors can be detected and stopped early
• Results are verifiable at each step
• lightweight conversational inputs are not unnecessarily forced into task intake
• Context can be compacted or split before adding more orchestration
• catalogs and workflow maps are separated from always-loaded entry files
• Deterministic parts are offloaded to scripts / IR / hooks (not LLM loops)
• File-based IR is introduced only when deterministic handoff requires it, and cleanup is defined

Full checklist: references/review-checklist.md

Reference Map

Topic	Reference
Primitive decision	references/customization-decision.md
Design principles	references/design-principles.md
Workflow patterns	references/workflow-patterns/overview.md
Splitting criteria	references/splitting-criteria.md
Review checklist	references/review-checklist.md
Prompt template	references/prompt-template.md
Context management	references/context-engineering.md
Agent guide / template	references/agent-guide.md, references/agent-template.md
Handoffs / placement	references/handoffs-guide.md, references/vscode-agent-placement.md
Hooks	references/hooks-guide.md
Evaluation	references/agent-evaluation.md
External links	references/external-resources.md

External References

Keep a small curated set here for first-hop reading. The longer link list stays in references/external-resources.md.

• GitHub Docs: Chat in IDE
• VS Code Docs: Custom Agents
• GitHub Docs: Create custom agents
• Anthropic: Building Effective Agents
• Anthropic: Effective Context Engineering
• Anthropic: Writing Tools for Agents

agent Quick Fix

Problem: Orchestrator says "I'll delegate" but does work directly.

Solution: Use MUST/MANDATORY language. See agent-guide.md.

## MANDATORY: Sub-agent Delegation
You MUST use agent for each file. Do NOT read files directly.

Tools Reference

→ references/agent-template.md

Purpose	VS Code Copilot	Claude Code
Shell	execute/runInTerminal	Bash
Read	read/readFile	Read
Edit	edit/editFiles	Write
Subagent	agent	Task
Web fetch	web/fetch	(MCP)

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