Agent-Skills.md

Agent Skills: Agentic Workflow Guide

Create, review, and update Prompt and agents and workflows. Covers 5 workflow patterns, agent delegation, Handoffs, Context Engineering. Use for any .agent.md file work or multi-agent system design. Triggers on 'agent workflow', 'create agent', 'ワークフロー設計'.

UncategorizedID: aktsmm/agent-skills/agentic-workflow-guide

Repository

aktsmm/agent-skills
aktsmmLicense: NOASSERTION
5

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aktsmm/Agent-Skills/tree/HEAD/agentic-workflow-guide

Skill Files

Browse the full folder contents for agentic-workflow-guide.

Download Skill

Loading file tree…

agentic-workflow-guide/SKILL.md

Skill Metadata

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'."

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.

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