Agent Skills: Agentic Workflow Guide

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 (Local harness only; prompt files are deprecated for Agent Host sessions, so prefer a Skill for new slash workflows)
• Always-on or file-scoped guidance -> Instruction
• Reusable workflow with bundled assets -> Skill
• Persona, tool restrictions, delegation, or handoffs -> Agent
• Deterministic enforcement -> Hook (Preview; events and config differ by harness)

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

Name the pattern explicitly when complexity rises, using the selector in references/workflow-patterns/overview.md. Every loop needs explicit stop conditions.

Design Workflow

1. Extract repeated behavior, tool preferences, and workflow shape from the conversation.
2. Choose primitive + scope (workspace / profile); ask only about ambiguities that change behavior.
3. Escalate only when split / compact / reference-ization cannot solve it, then pick a pattern.
4. Implement the smallest version and tighten the weakest parts.

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 と整合対象の判断に限定する。
• For model allocation reviews, use scheduled runtime bindings.

Escalation Rules

Prefer the lowest level (L0 prompt → L1 + instructions → L2 single agent → L3 multi-agent) that solves the problem cleanly. Quick signals to split:

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

Threshold details: references/splitting-criteria.md

Review Gates

• [ ] Primitive choice is simpler than agent if possible
• [ ] Placement is appropriate and always-loaded entry files stay thin (entry boundary smells: review-checklist.md)
• [ ] 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
• [ ] Verify actual producer-to-consumer dataflow, not only fixtures injected into a validator; cover empty results and meaningful state transitions. Repeating unchanged input proves idempotency, not the full lifecycle.
• [ ] 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.

When an orchestrator promises delegation but works directly, make the delegation requirement explicit and verifiable (agent-guide.md). Tool mapping and agent scaffold: agent-template.md.

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
• [ ] Review Gates 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
• [ ] Distinguish configuration saved, code tested, live read verified, action authorized, and recurring cycle completed. Verify authoritative state before claiming completion or unattended readiness; pending safeguards and unobserved cycles retain their blockers and next check conditions.