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
• 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

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
• [ ] 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 (not LLM loops)

Full checklist: references/review-checklist.md

Reference Map

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

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 Evaluation

A framework for measuring agent workflow effectiveness based on vscode-ai-toolkit best practices.

Table of Contents

• Overview - Why evaluation matters
• Three Core Metrics - Intent Resolution, Tool Call Accuracy, Task Adherence
• Evaluation Methodology - How to evaluate
• Evaluation Best Practices - Guidelines for effective evaluation
• Common Evaluation Pitfalls - Anti-patterns to avoid
• Evaluation Checklist - Quick check template

---

Overview

Effective agent evaluation goes beyond simple success/fail metrics. It requires assessing the quality of reasoning, tool usage, and task adherence across diverse scenarios.

Three Core Metrics

1. Intent Resolution

Does the agent correctly understand and fulfill user intent?

Evaluation Questions

• [ ] Did the agent clarify ambiguous requests?
• [ ] Did it address the underlying goal or just the explicit ask?
• [ ] Were edge cases and constraints considered?
• [ ] Did the output match user expectations?

Example Scenarios

2. Tool Call Accuracy

Does the agent use tools correctly and efficiently?

Evaluation Questions

• [ ] Did the agent use available tools (not reimplementing)?
• [ ] Were tool parameters correct and complete?
• [ ] Was the tool sequence logical and efficient?
• [ ] Were errors handled gracefully?

Common Tool Usage Mistakes

Tool Call Metrics

**Accuracy:** (Correct Tool Calls) / (Total Tool Calls)
**Efficiency:** (Optimal Tool Count) / (Actual Tool Count)
**Coverage:** (Tools Used) / (Relevant Tools Available)

3. Task Adherence

Does the agent follow instructions and constraints?

Evaluation Questions

• [ ] Did the agent respect scope boundaries?
• [ ] Were constraints (time, resources, safety) followed?
• [ ] Did it avoid making unauthorized changes?
• [ ] Were deliverables complete per specification?

Adherence Violations

---

Evaluation Methodology

1. Test Data Generation

Create diverse, realistic test scenarios

Scenario Categories

Test Data Generation Process

Step 1: Identify Agent's Domain
  - What tasks does it handle?
  - What tools does it use?

Step 2: Create Baseline Scenarios
  - 10-20 typical use cases
  - Cover main functionality

Step 3: Add Variation
  - Ambiguous phrasing
  - Missing information
  - Conflicting requirements

Step 4: Include Edge Cases
  - Boundary values (empty, max size)
  - Unusual file types or formats
  - Concurrent requests

Step 5: Simulate Failures
  - Tool unavailability
  - Partial results
  - Timeout scenarios

Example Test Set (Code Review Agent)

test_cases:
  - id: "happy-001"
    input: "Review src/auth.py for security issues"
    expected_tools: ["read", "grep"]
    expected_output_type: "security_report"
    success_criteria:
      - Uses #tool:read to access file
      - Identifies security patterns (SQL injection, XSS, etc.)
      - Provides severity ratings

  - id: "ambiguous-001"
    input: "Check this"
    expected_behavior: "Request clarification"
    success_criteria:
      - Asks what to check
      - Offers options (code, tests, docs)
      - Doesn't make assumptions

  - id: "edge-001"
    input: "Review all Python files"
    context: "Repository has 1000+ .py files"
    expected_behavior: "Plan-First approach"
    success_criteria:
      - Creates plan before execution
      - Proposes batching or sampling
      - Estimates time required

  - id: "error-001"
    input: "Review src/nonexistent.py"
    expected_behavior: "Graceful error handling"
    success_criteria:
      - Detects file doesn't exist
      - Informs user clearly
      - Suggests alternatives (similar files, search)

2. Evaluation Rubric

Score each dimension on a scale

Intent Resolution Rubric

Tool Call Accuracy Rubric

Task Adherence Rubric

3. Automated Testing

Implement programmatic evaluation where possible

What Can Be Automated

Prefer Stable Assertions

Programmatic evaluation is strongest when assertions survive renames, workspace changes, and normal output variation.

Prefer:

• schema or heading checks over long exact-string matches
• tool-usage checks over replaying one transcript verbatim
• stable identifiers (file basenames, declared section names, output schema keys)

Avoid:

• temporary workspace paths
• machine-specific absolute paths
• exact output assertions copied from a single recorded run

What Requires Human Review

Automation Example (Python)

def evaluate_tool_calls(log_file, expected_tools):
    """
    Evaluate tool call accuracy from execution logs.
    """
    with open(log_file) as f:
        logs = json.load(f)

    tool_calls = [entry for entry in logs if entry["type"] == "tool_call"]

    metrics = {
        "total_calls": len(tool_calls),
        "unique_tools": len(set(call["tool_name"] for call in tool_calls)),
        "hallucinated": sum(1 for call in tool_calls
                           if call["tool_name"] not in expected_tools),
        "failed": sum(1 for call in tool_calls
                     if call["status"] == "error"),
    }

    metrics["accuracy"] = 1 - (metrics["hallucinated"] / metrics["total_calls"])

    return metrics

---

Evaluation Best Practices

1. Establish Baselines

Before making changes, measure current performance:

Baseline Evaluation (v1.0)

- Intent Resolution: 3.8/5.0
- Tool Call Accuracy: 4.2/5.0
- Task Adherence: 4.5/5.0

After Optimization (v1.1)

- Intent Resolution: 4.3/5.0 ✅ +13%
- Tool Call Accuracy: 4.6/5.0 ✅ +9.5%
- Task Adherence: 4.4/5.0 ⚠️ -2.2%

2. Diverse Test Set

3. Iterative Improvement

graph LR
    A[Baseline] --> B[Identify Weaknesses]
    B --> C[Implement Fix]
    C --> D[Re-evaluate]
    D --> E{Improved?}
    E -->|Yes| F[Deploy]
    E -->|No| G[Different Approach]
    G --> C

4. Log Everything

Comprehensive logging enables debugging and improvement

{
  "test_id": "happy-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "user_input": "Review src/auth.py",
  "agent_plan": "1. Read file 2. Scan for patterns 3. Report",
  "tool_calls": [
    {
      "tool": "read",
      "params": { "file": "src/auth.py" },
      "status": "success"
    },
    { "tool": "grep", "params": { "pattern": "eval\\(" }, "status": "success" }
  ],
  "output": "Found 2 security issues...",
  "scores": {
    "intent_resolution": 5,
    "tool_accuracy": 5,
    "task_adherence": 5
  },
  "evaluator_notes": "Excellent handling, proactive security scan"
}

Logs are valuable inputs for designing evals, but they should not become the assertion wholesale. Use logs to discover robust checks, then reduce them to stable criteria.

5. Continuous Monitoring

Evaluation isn't one-time; monitor in production

---

Common Evaluation Pitfalls

1. Overfitting to Test Set

Problem: Agent performs well on tests but poorly on real tasks.

Solution:

• Use held-out test set
• Regularly refresh test scenarios
• Include user-reported issues

2. Ignoring User Feedback

Problem: Metrics look good, users are unhappy.

Solution:

• Collect qualitative feedback
• Review actual usage logs
• User interviews/surveys

3. Binary Pass/Fail

Problem: Doesn't capture nuance or areas for improvement.

Solution:

• Use rubrics with gradations
• Track multiple dimensions
• Identify specific failure modes

4. Testing Only Happy Paths

Problem: Agent fails when things go wrong.

Solution:

• Systematically test error conditions
• Simulate timeouts, missing resources
• Test with malformed inputs

5. Lack of Regression Testing

Problem: New features break existing functionality.

Solution:

• Maintain test suite
• Run before each release
• Automate where possible

6. Brittle Recorded Evaluations

Problem: A recorded test only passes for the original session because it encodes one temporary path or one exact output.

Solution:

• Rewrite assertions around structure, tool behavior, or schema
• Replace workspace-specific paths with stable identifiers
• Re-run evaluation after renames to confirm the checks still hold

---

Evaluation Checklist

Before deploying an agent workflow:

- [ ] Created diverse test set (happy, ambiguous, edge, error)
- [ ] Defined success criteria for each test
- [ ] Established baseline metrics
- [ ] Tested all major workflows
- [ ] Verified tool call accuracy
- [ ] Confirmed constraint adherence
- [ ] Assertions rely on stable structure or tool behavior, not one recorded run
- [ ] Logged evaluation results
- [ ] Identified improvement areas
- [ ] Documented known limitations
- [ ] Set up monitoring for production

---

References

• vscode-ai-toolkit Agent Evaluation
• Building Effective Agents - Anthropic
• Prompt Engineering Guide - OpenAI

Agent (Sub-agent) Guide

Practical guide for using subagent tools in VS Code Copilot and Claude Code.

Table of Contents

• What is agent? - Key characteristics and purpose
• When to Use - Effective scenarios and anti-patterns
• How to Invoke - Enabling and invocation methods
• Prompt Engineering - Sub-agent prompt requirements
• Orchestrator-Workers Pattern - Architecture examples
• Common Pitfalls - Avoiding delegation failures
• Token Efficiency - Trade-offs and recommendations
• Handoffs vs agent - Comparison
• Checklist - Implementation checklist

Platform Note (2026/02 Updated):

>

- VS Code Copilot: Use agent in tools: and #tool:agent in prompts (runSubagent is a legacy alias)

- Claude Code: Use Task in tools:

Legacy call patterns (avoid in new docs)

The following legacy forms may still work but should not be used in new documentation:

• tools: ["runSubagent"] → use tools: ["agent"]
• #tool:runSubagent → use #tool:agent
• runSubagent({ ... }) → use agent({ ... })
• agent/runSubagent (old tool path) → use agent

What is agent?

The agent tool launches an independent agent with a clean context window to handle complex, multi-step tasks autonomously.

Key Characteristics

Primary Purpose

"agent is for context management, NOT for speed optimization."

Use when you want to:

• Keep main session context clean (avoid context rot)
• Isolate detailed exploration from synthesis
• Process large data without polluting main context

---

When to Use

→ See also [splitting-criteria.md](splitting-criteria.md) for the complete escalation ladder and quantitative thresholds.

✅ Effective Scenarios

When a workflow matches these scenarios or the thresholds in splitting-criteria.md, write delegation as a requirement, not permission. Prefer "MUST use agent for these files/logs/URLs" over "may use sub-agents if needed". If the orchestrator intentionally does not delegate, record the reason: small scope, enough context already loaded, tool unavailable, or overhead greater than benefit.

❌ When NOT to Use Sub-agents

→ [splitting-criteria.md#part-4-when-not-to-split](splitting-criteria.md#part-4-when-not-to-split) for detailed decision matrix and complexity scaling guidelines.

Quick reference: Avoid sub-agents for single file/< 5 min tasks, simple Q&A, or when follow-up conversation is needed.

---

How to Invoke

Enabling agent

Option 1: Tool Picker

• Open VS Code chat → Tool picker → Enable agent

Option 2: Agent YAML (Recommended)

# VS Code Copilot
---
name: Orchestrator
tools: ["agent", "web/fetch", "readFile"]
---
# Claude Code
---
name: Orchestrator
tools: ["Task", "WebSearch", "Read"]
---

Invocation Methods

Method 1: Direct Tool Reference (Most Reliable)

Use #tool:agent for each URL to fetch and summarize the content.

Method 2: Natural Language

For each file, launch a sub-agent to analyze and return findings.

Method 3: Explicit Tool Call (In Agent Definition)

## Workflow

1. Analyze requirements
2. For each identified file:

- Call #tool:agent with prompt:
  "Read [filename], identify issues, suggest fixes"

3. Synthesize all sub-agent results

---

Prompt Engineering for agent

Sub-agent Prompt Requirements

When calling agent, your prompt parameter must include:

Zenn-compliant minimal template

# MyOrchestrator.agent.md

---

name: MyOrchestrator
tools: ['agent']

---

#tool:agent を使用して、Researcher エージェントを呼び出してください。

- prompt: ${調査したい内容}
- agentName: Researcher

Good Prompt Examples

# Research Sub-agent

Fetch https://example.com/docs and analyze:

1. Core features (max 3)
2. Pricing tiers
3. Limitations

Return as structured Markdown with:

- Feature list
- Price comparison table
- Recommendation

# Code Review Sub-agent

Read the file at {filepath} and:

1. Identify potential bugs
2. Check for security issues
3. Suggest performance improvements

Return: JSON with {bugs: [], security: [], performance: []}

Bad Prompt Examples

❌ Too vague: "Look at this and tell me what you think" ❌ Missing return format: "Analyze the logs" (what format?) ❌ Too broad: "Research everything about React" (unbounded)

---

Orchestrator-Workers Pattern with agent

Architecture

Main Agent (Orchestrator)
├── Decompose task into subtasks
├── For each subtask:
│   └── agent(subtask_prompt)
│       └── Returns: summary (1-2k tokens)
└── Synthesize all summaries

Example: Multi-File Code Review

Orchestrator Agent Definition:

---
name: Code Review Orchestrator
description: Reviews code changes across multiple files using sub-agents
tools: ["agent", "read_file", "grep_search"]
---
# Code Review Orchestrator

## Workflow

1. **Identify changed files**
- Use grep_search or read_file to list modified files

2. **Dispatch review sub-agents** ⚠️ MUST USE agent
For each file, call #tool:agent with prompt:

Review the file at [filepath]:

• Security issues (HIGH/MEDIUM/LOW)
• Logic bugs
• Style violations

Return as structured JSON: {security: [], bugs: [], style: []}

3. **Synthesize results**
- Aggregate all sub-agent outputs
- Prioritize by severity
- Generate final review report

## CRITICAL: Sub-agent Dispatch

You MUST use #tool:agent for file reviews.
Do NOT review files directly in main context.
Each sub-agent keeps file content isolated.

---

Common Pitfalls

Pitfall 1: Orchestrator Does the Work Itself

❌ Problem: Orchestrator reads files directly instead of delegating

Symptoms:

• No #tool:agent calls in execution
• Main context fills up
• Agent says "I'll review each file" but doesn't spawn sub-agents

Solution: Use explicit, imperative instructions:

## MANDATORY: You MUST use #tool:agent

Do NOT read file contents directly.
Do NOT review code in main context.
For EACH file → agent with specific prompt.

Pitfall 2: Parallel Execution Overhead

⚠️ Note: As of 2026/01, agent supports parallel execution, but with overhead.

Trade-off: Parallel sub-agents add VS Code processing overhead. In one test:

Recommendation: Use parallel sub-agents when:

• Context isolation is the primary goal
• Tasks are truly independent
• Main session needs to stay clean for follow-up work

# For parallel execution, group related files into batches

# to reduce overhead while maintaining context isolation

Pitfall 3: Nested Sub-agent Calls (Not Supported)

❌ Problem: Sub-agent tries to call another sub-agent

Reality: Sub-agents cannot call agent themselves. Nesting is not supported.

Solution: Keep hierarchy flat:

✅ Correct:
Orchestrator → Worker A
            → Worker B
            → Worker C

❌ Wrong:
Orchestrator → Worker A → Sub-Worker (NOT ALLOWED)

Pitfall 4: Vague Sub-agent Prompts

❌ Problem: "Analyze this file" → Sub-agent doesn't know what to return

Solution: Always specify output format:

Return as:

- Summary: (1 paragraph)
- Issues: (bullet list)
- Recommendation: (1 sentence)

Pitfall 5: Sub-agent Handoff to Named Agents

❌ Problem: Trying to use subagentType=my-agent doesn't work

Reality: agent creates fresh agents, cannot handoff to existing agent definitions.

Solution: Define sub-agent behavior in the prompt parameter, not in separate files.

Pitfall 6: Custom Agent as Sub-agent (Experimental)

⚠️ Experimental Feature: As of 2026/01, you can invoke custom agents as sub-agents with additional configuration.

Enable in VS Code:

// settings.json
{
  "chat.customAgentInSubagent.enabled": true
}

Usage:

#tool:agent を使用して、以下の処理をサブエージェントで実行してください。

- prompt: {サブエージェントへの入力}
- agentName: my-custom-agent

Limitations:

• Custom agent must NOT have disable-model-invocation: true (default: false)
• ℹ️ infer: は deprecated。user-invocable / disable-model-invocation を使用すること
• Sub-agent cannot access main session context
• Parallel execution available (2026/01+) but with overhead

Pitfall 7: Restricting Orchestrator's tools Breaks Sub-agents

❌ Problem: Orchestrator の tools: から edit を外してSRPを強制 → サブエージェント（Writer等）が edit を使えなくなる

Reality: 親エージェントの tools: はサブエージェントのツール上限（ceiling）として機能する。親で許可されていないツールは、サブエージェントでも使用不可。

❌ Wrong: Orchestratorで edit を制限
---
name: Orchestrator
tools: ["agent", "read", "todo"]  # edit がない
---
→ Writer サブエージェントが edit/editFiles を使えない!

✅ Correct: tools を省略（全ツール利用可）
---
name: Orchestrator
description: サブエージェントに作業を委譲
---
→ サブエージェントは全ツールを使える

Solution:

• Orchestrator は tools: を省略する（= 全ツール利用可、agent-template.md推奨）
• SRP の強制は tools: ではなく、プロンプト内の MANDATORY 指示で行う
• tools: 制限は Worker エージェント（末端）に対してのみ適用する

---

Inline Sub-agent Pattern (Recommended)

Instead of referencing external .agent.md files, embed the sub-agent's role definition directly in the prompt.

Why Inline?

Example: Inline Developer Sub-agent

`markdown #tool:agent を使用してサブエージェントを起動してください。

prompt: 以下の内容を渡す

Developer Agent

Role

あなたは開発者です。バグ修正、コードの改善を行います。

Goals

• TypeScript のベストプラクティスに従う
• エラーなくコンパイルされることを確認

Done Criteria

• npm run compile がエラーなしで完了

---

タスク

{具体的な修正内容} `

Benefits

1. Reliability: No dependency on external files 2. Portability: Single file works anywhere 3. Clarity: Sub-agent behavior is explicit in the orchestrator

Token Efficiency

Comparison

Trade-off

• Speed: Direct is faster (no sub-agent overhead)
• Context quality: Sub-agents keep main context clean
• Long sessions: Sub-agents prevent context rot

Recommendation

---

Handoffs vs agent

Recommendation:

• Use Handoffs for human-in-the-loop phase transitions
• Use agent (旧 runSubagent) for context-heavy isolated tasks

---

Checklist

## agent Implementation Checklist

### Agent Definition

- [ ] tools includes "agent"
- [ ] Explicit instructions to USE sub-agents (not just "can use")
- [ ] Sub-agent prompt template defined

### Prompt Engineering

- [ ] Clear task description in sub-agent prompt
- [ ] Expected output format specified
- [ ] Constraints/scope defined
- [ ] Return structure (JSON/Markdown/etc.) specified

### Anti-patterns Avoided

- [ ] No "process in parallel" expectations
- [ ] No vague "analyze this" prompts
- [ ] No reliance on handoff to named agents
- [ ] Orchestrator doesn't do sub-agent work itself

### Testing

- [ ] Verified sub-agents are actually called (not skipped)
- [ ] Checked return summaries are appropriately sized
- [ ] Confirmed main context stays clean

---

References

• Chat in IDE - GitHub Docs
• Custom Agents in VS Code
• GitHub Copilot agent (旧 runSubagent) - Zenn
• Context Engineering for Agents - LangChain Blog- Handoffs Guide - Alternative for human-in-the-loop workflows
• Splitting Criteria - When to use sub-agents

---

⚠️ tools 形式の注意点（2026/02 Updated）

VS Code Copilot のカスタムエージェントで正しくサブエージェントを呼び出すには、以下の形式を守る必要があります。

正しいツールエイリアス

参考: GitHub Docs - Custom agents configuration

JSON配列形式を推奨

YAML配列形式は動作しない場合があります。JSON配列形式を使用してください。

正しい形式: tools: ["agent", "read", "edit", "search", "execute", "todo"]

間違い形式: tools:

• agent
• read

シンプルなプロンプト構造

複雑な450行のプロンプトより、シンプルな70行のプロンプトの方が効果的です。

Agent & Prompt Template

Standard structure and specification for .agent.md and .prompt.md files.

Note: Both file types use similar YAML front matter. The mode: field is deprecated for both.

File Format Rules

⚠️ フェンスラッパーに関する重要な注意

.prompt.md と .instructions.md ファイルは 素の YAML フロントマター (`---`) で始めること。 コードフェンス（ ``prompt 等）で囲む必要はない。フェンスで囲むと VS Code がフロントマターを認識できず、プロンプトピッカーに description が表示されなくなる。

`````yaml

✅ .prompt.md — 正しい

--- description: セッション内容をXポスト用に変換 ---

プロンプト本文...

❌ .prompt.md — 間違い（description が表示されない）

````prompt --- description: セッション内容をXポスト用に変換 ---

プロンプト本文...

`````

✅ .agent.md — 正しい（フェンス不要、素の --- だけ）

---
name: my-agent
description: Does something useful
---
# エージェント本文...

````

YAML Front Matter

For .agent.md files

---
name: <agent-name> # Required: Identifier for @mention
description: <description> # Required: One-line role description
model: <model-name> # Optional: LLM model to use
tools: [...] # Optional: Tool whitelist
agents: [...] # Optional: Restrict which subagents may be invoked
handoffs: [...] # Optional: Agent transitions (must be objects with label/agent/prompt/send)
user-invocable: true # Optional: Show in agents dropdown (default: true)
disable-model-invocation: false # Optional: Prevent subagent invocation (default: false)
---

Model note: model: is optional. Do not guess model names. If you have not verified the exact display name in the current environment, omit model: instead of using speculative values like gpt-4o.

When fallback matters, model: can be an ordered array and the first available model is used. Use only model display names verified in the current environment.

model: ["<verified-model-name-1>", "<verified-model-name-2>"]

handoffs は文字列配列ではなく、label・agent・prompt・send を持つオブジェクト配列で定義する。

agents は親 agent が呼び出せる subagent 名の制限。省略すると全許可、[] なら subagent 呼び出し禁止。

⚠️ 非標準フィールド禁止（バリデーションエラーの原因）

author, repository, license, copyright 等のメタデータを YAML frontmatter に書くと バリデーションエラー になる。 これらは YAML の外、--- 終端の直後に HTMLコメント として記述すること。

# ✅ 正しい — メタデータはHTMLコメント
---
name: my-agent
description: Does something useful
---

<!-- author: aktsmm
     repository: https://github.com/aktsmm/ghc_template
     license: CC BY-NC-SA 4.0
     copyright: Copyright (c) 2025 aktsmm -->

# エージェント本文...

# ❌ 間違い — YAMLに非標準フィールドを追加
---
author: aktsmm        ← バリデーションエラー
repository: https://...
name: my-agent
---

For .prompt.md files

---
description: <description> # Required: Brief description of the prompt
# agent: <agent-name> # Optional: Bind to a specific agent
---

Do not add tools: to .prompt.md by default. Prompt-level tools: is an allowlist that overrides the selected or referenced agent's tools for that prompt run. Use it only when losing unrelated built-in, extension, web, or MCP tools is intentional.

⚠️ Deprecated Fields

`infer:` Migration Guide:

infer: true (default) はプルダウン表示とサブエージェント呼び出しの両方を制御していたが、新しいフィールドでは独立制御が可能。

# ❌ Wrong (deprecated)
---
infer: false
---
# ✅ Correct: プルダウンに非表示（サブエージェントとしては呼び出し可能）
---
user-invocable: false
---
# ✅ Correct: サブエージェント呼び出しを禁止（プルダウンには表示）
---
disable-model-invocation: true
---
# ✅ Correct: 両方禁止
---
user-invocable: false
disable-model-invocation: true
---

⚠️ typo注意: user-invokable は誤記で無効。ピッカー非表示には必ず user-invocable: false を使うこと。

⚠️ サブディレクトリの罠（2026年2月時点）: .github/agents/ は直下のファイルだけをスキャン。

サブフォルダに入れると runSubagent でも呼び出せなくなる。フラットに置くこと。

非表示にしたい場合はサブフォルダではなく user-invocable: false を使うこと。

Manifest Validation Checklist

複数の .agent.md をまとめて編集したら、最低限次を確認すること。

• user-invokable などの誤記が front matter に混入していない
• user-invocable: false の agent が意図どおり subagent 専用になっている
• front matter 編集後も本文先頭の ## Role など必須セクションが崩れていない

`mode:` Migration Guide:

# ❌ Wrong (deprecated)
---
mode: agent
---
# ✅ Correct: Specify agent name
---
description: Daily report generator
agent: report-generator
---
# ✅ Correct: Boolean value
---
description: Daily report generator
agent: true
---
# ✅ Correct: Omit (default behavior)
---
description: Daily report generator
---

`agent:` Field Options:

Complete .prompt.md Example

---
description: デイリーレポート自動生成（業務ログから1日分のレポートを作成）
agent: report-generator
---

Tools Pattern Reference:

Common Tool Categories:

---

✅ Correct

---

name: my-agent description: Does something useful

---

`````

Tools Field Behavior

Note: MCP server tools become available at runtime automatically. Unknown tool names cause errors.

Recommended tools: style for .agent.md

For custom agents, prefer the stable aliases below unless you specifically need a narrower tool path.

tools: [read, search]
tools: [read, search, edit]
tools: [agent, read, search]

Use these aliases first:

Avoid raw runtime tool IDs in .agent.md frontmatter. Names such as read_file, grep_search, and semantic_search are chat/runtime tool identifiers, not portable custom-agent tool names, and they trigger validation errors.

Body から特定ツールを明示したい場合は #tool:<name> 参照を使う。

Use #tool:agent for each independent file review.
Use #tool:web when external documentation is required.

⚠️ Orchestrator の tools 制限に注意: 親エージェントの tools: はサブエージェントの ツール上限（ceiling） として機能する。Orchestrator の tools: から edit を外すと、サブエージェント（Writer 等）も edit を使えなくなる。Orchestrator は tools: を省略する（= 全ツール利用可）のが推奨。SRP の強制は tools: ではなくプロンプト内の MANDATORY 指示で行うこと。詳細は agent-guide.md の Pitfall 7 を参照。

⚠️ tools フィールドの注意事項

ツール名は `category/toolName` 形式で指定すること。 カテゴリが間違っていると VS Code がエラーを出す。

`tools:` に登録できないもの（チャット変数としてのみ利用可）:

• problems / changes / usages / codebase / githubRepo → #problems 等でチャット内参照は可能だが、tools: ホワイトリストには登録不可

Agent Body Structure

Built-in Aligned Minimal Template

If you do not need the full structured template, start from this smaller built-in aligned shape and expand only when required.

---
description: "Use when... trigger phrases for subagent discovery"
tools: [read, search]
user-invocable: false
---
You are a specialist at {specific task}. Your job is to {clear purpose}.

## Constraints
- DO NOT {thing this agent should never do}
- DO NOT {another restriction}
- ONLY {the core responsibility}

## Approach
1. {Step one}
2. {Step two}
3. {Step three}

## Output Format
{Exactly what this agent should return}

Use the minimal template when:

• the agent is single-purpose
• tool boundaries matter more than rich documentation
• the return format is more important than a long workflow narrative

Use the full template below when you need explicit I/O contracts, progress reporting, or error handling tables.

Each agent should include these sections:

⚠️ Critical: Done Criteria Placement

Define Done Criteria in exactly ONE place. Multiple definitions cause confusion.

Full Template

````markdown --- name: example-agent description: Brief description of what this agent does

VS Code Copilot tools (adjust for Claude Code: Read, Edit, Search)

tools: ["readFile", "editFiles", "textSearch"] ---

Example Agent

Role

[Single sentence defining this agent's responsibility]

Goals

• Goal 1: [Specific, measurable objective]
• Goal 2: [Another objective]
• Goal 3: [...]

Done Criteria

Task is complete when ALL of the following are true:

• [ ] Criterion 1 (verifiable condition)
• [ ] Criterion 2 (verifiable condition)
• [ ] Criterion 3 (verifiable condition)

Permissions

Allowed

• Action 1
• Action 2

Forbidden

• ❌ Action that should never be done
• ❌ Another prohibited action

Non-Goals

Explicitly define what this agent does NOT do:

• ❌ Do not write code directly (delegate to implementation agent)
• ❌ Do not review own output (delegate to review agent)
• ❌ Do not assume user intent (ask for clarification)

Why Non-Goals? Prevents orchestrators from doing work they should delegate.

I/O Contract

Input

Output

Workflow

1. Step 1: [Action description]

• Details or sub-steps

2. Step 2: [Action description] 3. Step 3: [Action description]

Error Handling

Progress Reporting

For long-running tasks, maintain visibility:

• Use manage_todo_list tool to track task status
• Update status at each sub-task completion
• Provide intermediate reports for tasks > 5 minutes

**Progress:**

- [x] Task 1: Analyze requirements
- [x] Task 2: Generate IR
- [ ] Task 3: Validate output

## Idempotency

- Check current state before making changes
- Use unique identifiers to prevent duplicates
- Design operations to be safely retried

Examples by Role

→ See design-principles.md for detailed design principles.

Orchestrator Agent

VS Code Copilot:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["runSubagent", "readFile", "textSearch", "todos"]
---

Claude Code:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["Task", "Read", "Search", "TodoWrite"]
---

Key characteristics:

• Uses subagent tool for delegation (#tool:agent / Task)
• Maintains high-level view
• Does NOT perform detailed work itself

Available Tools

Built-in tools for custom agents. Tool names differ by platform:

VS Code Copilot Tools (Official)

Claude Code Tools (Anthropic)

Cross-Platform Mapping

Tool Definition Examples

VS Code Copilot:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["runSubagent", "readFile", "textSearch", "todos"]
---

Claude Code:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["Task", "Read", "Search", "TodoWrite"]
---

Tool Reference Syntax

• VS Code Copilot: Use #tool:<tool-name> in prompts (e.g., #tool:runSubagent)
• Claude Code: Reference tools directly by name

MCP Server Tools

Use <server-name>/* format to include all tools from an MCP server.

Troubleshooting: If tools are not recognized:

• VS Code: Check VS Code Chat Tools Reference
• Claude Code: Check Custom Agents Configuration - GitHub Docs

Handoffs (Agent Transitions)

Handoffs enable guided sequential workflows between agents with suggested next steps.

When to Use

• Plan → Implementation: Generate plan, then hand off to implementation agent
• Implementation → Review: Complete coding, then switch to code review agent
• Write Failing Tests → Pass Tests: Generate failing tests first, then implement code

Configuration

---
name: Planner
description: Generate an implementation plan
# VS Code Copilot tools
tools: ["textSearch", "web/fetch", "readFile"]
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
---

Benefits

• Human control: User reviews each phase before proceeding
• Context preservation: Relevant context passed via prompt
• Workflow orchestration: Multi-step tasks with clear boundaries

References

• Custom Agents in VS Code
• Custom Agents Configuration - GitHub Docs

Built-in Customization Patterns

Patterns extracted from VS Code Copilot's built-in customization skills.

Use these as design heuristics for agent workflows and customization creation. Do not copy the built-in commands verbatim.

1. Extract Before You Interview

Built-in create-agent, create-prompt, create-instructions, create-skill, and create-hook all start by reviewing the conversation and generalizing what the user has already been doing.

Use this pattern when:

• The user has already demonstrated a repeated workflow
• Tool preferences or role boundaries are visible from context
• You want to minimize clarification churn

Apply it as:

1. Extract repeated task shape 2. Extract constraints and tool preferences 3. Extract desired output style 4. Ask only for what is still missing

Anti-pattern:

• Starting with a large requirements interview when the conversation already contains the specialization

2. Clarify the Weakest Ambiguity Only

The built-in create flows do not ask every possible setup question. They draft first, then focus on the most ambiguous or behavior-changing part.

Good clarification targets:

• scope: workspace or user profile
• role boundary: when to use this over the default agent
• enforcement: should it guide, warn, ask, or block
• output contract: expected structure or return format

Avoid:

• asking for details that do not change the file design
• collecting exhaustive requirements before a first draft

3. Guidance and Enforcement Are Different Primitives

The built-in agent-customization skill draws a hard line:

• prompts, instructions, skills, and agents are guidance
• hooks are deterministic enforcement at lifecycle events

Use this distinction when designing workflow systems:

If a requirement includes words like "always block", "must ask", "inject at session start", or "run automatically before tool use", evaluate Hook explicitly.

4. Discovery Surface Matters

Built-in customization docs consistently treat descriptions as the routing surface.

Implications:

• descriptions need trigger phrases, not generic summaries
• vague labels reduce agent discovery and slash-command usability
• agent, skill, and instruction discovery all benefit from a strong "Use when..." shape

Use this when reviewing workflow assets:

• can another agent discover this from its description alone?
• would a user understand when to invoke it from the picker?

5. Draft, Then Iterate

The built-in creation flow is not "requirements -> perfect file". It is:

1. extract 2. clarify 3. draft file 4. identify weak spots 5. refine 6. suggest related next customizations

This is a strong pattern for agent workflow design too, especially when creating an orchestrator plus adjacent prompts, instructions, or hooks.

6. Bootstrap and Debug Are First-Class Workflows

Two built-in skills are especially worth borrowing conceptually:

init

What to absorb:

• explore the codebase before writing customization assets
• prefer linking to existing docs instead of copying them
• create or update only customization files, not product code

When useful:

• initializing workflow assets for a repo
• upgrading AGENTS.md and related instructions without touching app code

troubleshoot

What to absorb:

• base conclusions on evidence
• do not guess about why a workflow did or did not trigger
• separate root cause, evidence, and remediation

When useful:

• debugging why an agent was not invoked
• debugging why a prompt, skill, or instruction did not load
• explaining unexpected workflow choices

7. Minimal Reusable Loop

When designing or reviewing agent customizations, this is the compact loop worth keeping:

1. Extract from conversation 2. Choose primitive and scope 3. Clarify only the missing ambiguity 4. Draft the file or workflow 5. Review the weakest part 6. Refine and suggest adjacent assets

If the process starts turning into a large wizard, you are probably over-designing the customization.

Context Engineering

Strategies for curating and managing context in long-running AI agents.

"Context engineering is the art and science of curating what will go into the limited context window."

— Anthropic

Overview

---

Why Context Engineering Matters

Context Rot

As tokens increase, recall accuracy decreases. This is called context rot.

Token Count vs. Recall Accuracy

Low tokens   ████████████████ High accuracy
Medium       ██████████░░░░░░ Moderate
High tokens  ████░░░░░░░░░░░░ Low accuracy (context rot)

Key Insight

"Context must be treated as a finite resource with diminishing marginal returns."

Principle: Find the smallest set of high-signal tokens that maximize the likelihood of desired outcomes.

---

Techniques

1. Compaction

Summarize context when approaching limits, reinitialize with summary.

When to Use

• Context window is 70-80% full
• Long conversation with accumulated tool outputs
• Need to continue with fresh focus

Implementation

Original Context (90% full):
- System prompt
- 50 conversation turns
- 100 tool call results
- Accumulated state

    ↓ Compaction

Compacted Context (30% full):
- System prompt (preserved)
- Summary of key decisions
- Unresolved issues
- 5 most recent files/resources

What to Keep vs. Discard

Anthropic's Tip

"Start by maximizing recall to ensure your compaction prompt captures every relevant piece of information, then iterate to improve precision by eliminating superfluous content."

---

2. Structured Note-taking (Agentic Memory)

Persist notes outside the context window for later retrieval.

When to Use

• Multi-hour tasks with clear milestones
• Progress tracking across context resets
• Learning and improvement over time

Implementation Patterns

Pattern A: File-based Memory
└── NOTES.md or TODO.md persisted to disk

Pattern B: Structured JSON
└── state.json with typed fields

Pattern C: Key-Value Store
└── Database or MCP memory tool

Example: NOTES.md

# Agent Notes

## Current Objective

Training Pikachu to level 25 in Route 1

## Progress

- Steps completed: 1,234
- Pikachu level: 18 → 23 (+5)
- Remaining: 2 levels

## Learned Strategies

- Thunder Shock effective vs. Pidgey
- Avoid Rattata (wastes HP)

## Next Actions

1. Continue grinding until level 25
2. Move to Route 2

Benefits

• Survives context resets
• Agent can read own notes and continue
• Enables long-horizon coherence

---

3. Sub-agent Architectures

Delegate to specialized sub-agents with clean context windows.

When to Use

• Complex research requiring deep exploration
• Parallel exploration of multiple paths
• Need to isolate detailed work from main context

Architecture

graph TD
    A[Main Agent] --> B[Sub-agent 1: Search]
    A --> C[Sub-agent 2: Analysis]
    A --> D[Sub-agent 3: Code Review]
    B --> |Summary 1-2k tokens| E[Synthesis]
    C --> |Summary 1-2k tokens| E
    D --> |Summary 1-2k tokens| E
    E --> A

Key Pattern

Benefits

• Clean separation of concerns
• Detailed search context stays isolated
• Main agent focuses on synthesis

---

Just-in-Time Context Retrieval

Load context dynamically at runtime instead of pre-loading everything.

Pattern

Traditional (Pre-load):
1. Load all relevant files into context
2. Process
3. Respond
→ Wastes context on unused information

Just-in-Time:
1. Keep lightweight references (file paths, queries, links)
2. Load specific data when needed
3. Discard after use
→ Efficient, focused context

Implementation

# Instead of loading entire codebase:
context = read_all_files("src/")  # ❌ Wasteful

# Use just-in-time retrieval:
relevant_files = grep_search("function_name")  # ✅ Targeted
context = read_file(relevant_files[0])         # ✅ On-demand

Progressive Disclosure

"Agents can assemble understanding layer by layer, maintaining only what's necessary in working memory."

---

Hybrid Strategy

Combine pre-retrieval and just-in-time for optimal performance.

Example: Claude Code Approach

Decision Matrix

---

Split / Compact / Reference Loop

When workflow assets keep growing, do not default to adding another agent or another long instruction block.

Use this order instead:

1. Split Separate responsibilities, phases, or heavy examples that are polluting the main context. 2. Compact Rewrite repeated guidance into a smaller rule or decision point. 3. Referenceize Move deep recipes, long tables, and infrequent detail into files loaded on demand.

Practical Rule of Thumb

Apply to Customization Files

For .instructions.md, .prompt.md, .agent.md, and SKILL.md:

• Keep the routing surface and decision points in the main file
• Move recipes, variants, and long examples into references
• Prefer a curated small external-links section over a giant link dump in the main file
• Treat append-only growth as a smell, not as normal maintenance

For always-loaded workspace entry files such as .github/copilot-instructions.md:

• Keep only repo-wide routing and a few global guardrails in the entry file
• Move domain workflows, review rules, upload procedures, and long failure playbooks into dedicated .github/instructions/**/*.instructions.md
• Do not turn the entry file into a Markdown-linked index of rules, skills, or docs. Even when the body stays short, linked references can still make the entry behave like a heavy context surface
• If the entry file starts mixing persona, routing, workflow details, and domain-specific prohibitions, treat that as context-hoarding rather than good documentation
• If removing or renaming the entry file suddenly makes casual chat behave normally again, that is a strong signal the entry file has become too heavy for its role

---

Long-Horizon Task Checklist

## Context Engineering Checklist

### Before Starting

- [ ] Is this a long-horizon task (>30 min continuous work)?
- [ ] Will context window likely fill up?
- [ ] Are there clear milestones to track?

### Technique Selection

- [ ] **Compaction**: Set up summarization trigger at 70% context
- [ ] **Note-taking**: Create NOTES.md or state file
- [ ] **Sub-agents**: Identify tasks suitable for delegation

### During Execution

- [ ] Monitor context usage
- [ ] Write notes at milestones
- [ ] Compact when needed
- [ ] Use just-in-time retrieval for large data

### After Completion

- [ ] Archive notes for future reference
- [ ] Document lessons learned

---

4. Instruction File Optimization

Reduce token cost of definition files that are loaded into every session.

.instructions.md, .prompt.md, .agent.md are loaded in full on every conversation turn. Verbose files waste tokens before the task even starts.

What to Keep vs. Remove

Loading Locations (VS Code Copilot)

Duplicate content across global and workspace scopes doubles token cost.

Checklist

• [ ] Each file contains only user-specific / AI-unknowable information
• [ ] No duplicate content between global and workspace scopes
• [ ] All .prompt.md files have a description frontmatter
• [ ] Stale IDs, paths, or settings removed
• [ ] No conflicting instructions across files
• [ ] Workspace entry files still read like a short routing layer, not like a full operating manual

Red Flags

Diagnosis Order

When workspace behavior becomes unstable, do not jump straight to AGENTS.md mismatch.

Check in this order:

1. Is the always-loaded workspace entry file (.github/copilot-instructions.md) trying to do too many jobs at once? 2. Is the same rule duplicated across entry file, domain instructions, and prompt / agent assets? 3. Has the entry file become a Markdown-linked index that keeps pulling deeper material into the conversational surface? 4. Only after that, check whether AGENTS.md and agent definitions disagree about workflow entry points or role boundaries.

Reason:

• AGENTS.md inconsistency can matter, but over-scoped always-loaded instructions usually create broader symptoms first, especially when casual chat normalizes as soon as the entry file is removed or renamed.

---

Anti-Patterns

---

References

• Effective context engineering for AI agents - Anthropic
• Building effective agents - Anthropic
• How we built our multi-agent research system - Anthropic

Copilot Cloud Agent CI/CD Pitfalls

GitHub Actions で Copilot Cloud Agent の自動 PR パイプラインを組むときの落とし穴と対策。

Token Anti-Recursion

GitHub App トークン（Copilot Cloud Agent 含む）で作成・push した PR は、pull_request イベントで後続ワークフローをトリガーしない。GitHub の再帰防止ルール。

• GITHUB_TOKEN でも同様
• pull_request_target は制限を受けない

対策

後続ワークフロー（validate、auto-merge 等）は pull_request_target をトリガーにする。

on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review, edited]

注意: pull_request_target はベースブランチのワークフローコードで実行される。fork からの PR でコード実行すると危険なため、同一リポジトリ制約を付ける。

jobs:
  validate:
    if: github.event.pull_request.head.repo.full_name == github.repository

workflow_run 連携時の PR 解決

pull_request_target を起点にした workflow を、別 workflow の workflow_run で受ける場合、context.payload.workflow_run.pull_requests が空になることがある。

• pull_requests[0].number を前提にしない
• workflow_run.head_branch から open PR を逆引きする fallback を持つ

let pullRequests = context.payload.workflow_run.pull_requests || [];
if (pullRequests.length === 0 && context.payload.workflow_run.head_branch) {
  const { data: prs } = await github.rest.pulls.list({
    owner: context.repo.owner,
    repo: context.repo.repo,
    state: "open",
    head: `${context.repo.owner}:${context.payload.workflow_run.head_branch}`,
    per_page: 1,
  });
  pullRequests = prs;
}

pull_request_target で PR head を実行する場合の注意

pull_request_target は base branch の workflow 定義で動くが、checkout を PR head SHA に向けると PR 側の script / package.json / build code を実行する。

• same-repo guard を必須にする
• 実行を許す script / 生成物の allowlist を絞る
• fork PR や不特定 contributor を対象に同じ設計を使わない

参照

• GitHub Docs: Automatic token authentication
• GitHub Docs: pull_request_target

Self-Healing Reconcile Pattern

自動生成 PR パイプラインでは、チェーンの途中が壊れると PR と issue が stuck する。

• in-band 回復: validate failure の直後に PR コメントで修正指示を返し、Copilot に再修正させる
• scheduled reconcile: それでも取りこぼした stuck PR / 孤立 issue を定期ジョブで掃除する

rerun failed workflow だけでは直らない。content / policy failure は、失敗理由に応じた修正指示を PR 上に返す設計が必要。

回復対象

設計ポイント

• merge 前にファイル allowlist を検証する（auto-merge と同じ基準）
• needs-human-review ラベル付き PR はスキップする
• merge 後の副作用（deploy、release、通知）は 1 workflow に責務を寄せる。pull_request_target: closed など別 workflow が拾うなら、merge job 側で同じ dispatch を重複実行しない
• PR body を正規化し、Generated from data/events/YYYY-MM-DD.json と Closes #XX を必ず入れる
• Closes #XX パターンを PR body から抽出して linked issue を閉じる
• 閉じた PR/issue にはコメントで理由を残す

Generated Data Invariants

collector が自動修復を持っていても、壊れた生成物が main に入らない guard を別に置く。

• collect 後に generated data validator を実行する
• generated PR validation でも同じ validator を実行する
• validator は source 実装ではなく生成済み artifact の不変条件を見る

例:

• 同じ stable article URL が複数の日次 JSON に出ない
• source marker や closing reference のような canonical metadata が欠落しない
• generated output に既知の不正状態（generic fallback、同一記事の日跨ぎ重複など）が残らない

重要なのは、collect can repair だけで終わらず、repair に失敗した run は CI を落とす まで入れること。

Generated Output Diff Targets

生成物 workflow では、git diff --quiet、git add、canonical drift check の対象を必ず一致させる。

• collector が書き換える generated artifact を一覧化する（例: data, summaries, drafts, translation/summary cache）
• no-change 判定、commit staging、PR auto-fix、final drift check の対象を同じ集合にする
• cache-only drift も publish される品質に影響するなら generated output として扱う
• この集合を workflow invariant validator で固定し、対象漏れを CI で落とす
• workflow / validator / runbook 変更時は、同じ invariant validator を GitHub Actions でも実行する

In-Band Self-Heal Rules

• validate failure 時は、失敗ステップ名だけでなく修正ルールを PR コメントに書く
• self-heal コメント後に Copilot reviewer を再要求し、再修正の起点を明示する
• 同じ原因の自動修正は最大 3 回まで。超えたら PR を close し、linked issue / PR の両方に needs-human-review を付ける
• already gave up 状態では重複コメントを増やさない
• PR だけでなく linked issue にも escalation コメントを残し、なぜ blocked なのか を issue 単体で読めるようにする

Metadata and Closing Discipline

• generated PR の title / body は opened / synchronize 時に正規化する
• linked issue を閉じたいなら、merge job 側の best effort close だけに頼らず、PR body に closing reference を注入する
• source marker と closing reference が missing のままだと、PR merge 後に issue が残留しやすい

Human-Review Block Discipline

• needs-human-review が付いた linked issue は、authoring workflow 側で 自動 assignment と shepherd を止める
• blocked issue を定期実行や手動再実行で勝手に再開しない
• issue のラベル再設定時に needs-human-review を消さない
• 再開条件は明示する。例: ラベルを外すと再度自動化できます

Resume Semantics

• blocked issue を再開するとき、Copilot が assignee に残っていても already assigned だけでは不十分
• 対応する open generated PR が無いなら、assignment を再実行して作業を再開する
• open PR が既にある場合だけ already assigned / in progress と判定する

Duplicate PR Canonicalization

• 同一トピック（例: 同じ date key）で generated PR が複数 open になったら、最新 1 本を canonical にする
• stale duplicate PR は comment を残して自動 close する
• canonical PR の source marker / closing reference を SSOT にする

Failure-Specific Feedback

• build failure は build を直して だけでは弱い。失敗している policy を具体化する
• 例: pages build が published output 内の generic fallback copy を検出して落ちるなら、generic な仮置き文言を対象更新に即した運用影響へ書き換える まで指示する
• self-heal コメントには validate run へのリンクを残し、人が読むときも追跡できるようにする

Customization Decision Guide

Choose the simplest customization primitive that can solve the problem.

Decision Matrix

Guidance vs Enforcement

This distinction is easy to blur when designing workflow customizations.

Examples:

• "Always prefer this review style" -> instruction or skill
• "Ask before running this tool" -> hook
• "Use a specialist with limited tools" -> agent
• "Package a repeatable workflow with resources" -> skill

Escalation Ladder

Use complexity only when required.

1. Prompt 2. Prompt + instructions 3. Skill or single agent 4. Multi-agent workflow 5. Hooks for deterministic enforcement

Questions to Ask First

1. Is this a one-off task or a reusable workflow? 2. Does it need bundled assets, scripts, or references? 3. Does it need a specialist persona or tool restrictions? 4. Must the behavior be enforced deterministically? 5. Should this live in the workspace or the user profile?

Scope Guidance

Overdesign Smells

• Multi-agent proposed before confirming a single agent is insufficient
• Agent created only to hold long instructions
• Skill created even though there are no bundled assets or reusable resources
• Hook proposed for guidance that could stay as instructions
• Workspace asset proposed for a purely personal preference
• Questions asked before extracting obvious specialization from the conversation
• Hook proposed before confirming a lifecycle event or deterministic need
• Prompt file lists tools only to make them available; in VS Code tools: is an allowlist and should be omitted unless narrowing is intentional

Prompt Tool Boundary Rule

In .prompt.md, tools: is an allowlist, not a hint. Omit it unless the slash prompt must intentionally narrow the selected agent's tools.

If tool boundaries are stable and role-like, prefer a custom agent over prompt-level tools:.

Creation Loop

Built-in customization flows follow a lightweight loop that is worth reusing:

1. Extract the reusable pattern from the conversation 2. Clarify only the missing ambiguity 3. Draft the customization file directly 4. Identify the weakest or most ambiguous part 5. Iterate and then suggest the next adjacent customization

Use this loop for prompt / instruction / skill / agent / hook creation unless the task is already fully specified.

Output Pattern

When designing a workflow, include this decision explicitly.

## Primitive Decision

- Best fit: agent
- Why not prompt: needs delegation and tool boundaries
- Why not skill: persona and orchestration are the core requirement
- Scope: workspace

Deep Agent Patterns

Patterns for building research-oriented agents with recursive information gathering and quality evaluation.

Overview

Deep Agents are specialized for comprehensive information gathering with citation-backed outputs. Key characteristics:

• Exhaustive Coverage: Multi-perspective investigation
• Recursive Collection: Follow links to original sources (max 3 levels)
• Quality Gates: Evaluator sub-agent validates output
• Citation Required: Every non-trivial fact needs a reference

Core Structure

---
name: DeepResearch
description: "Comprehensive topic research with citations"
tools: ["search", "web/fetch", "agent", "edit/editFiles", "todo"]
---

Four Phases

Scaling by Complexity

Recursive Collection Strategy

Depth Levels

Stop Conditions

• Same domain: max 3 levels
• Per entry point: max 10 sources

Source Priority

1. Official Docs (Microsoft Docs, GitHub Docs) 2. Official Blogs (Azure Blog, GitHub Blog) 3. Tech Blogs (Zenn, Qiita, dev.to) 4. Community (Stack Overflow, Reddit) 5. Social (Twitter/X) ← Last resort

Sub-agent Definitions

Research Sub-agent

**Purpose**: Search and document findings for a specific perspective.

**Input**:

- Topic: <research target>
- Perspective: <focus area>
- Output file: <report path> (use `-part-N.md` suffix for parallel execution)

**Search Strategy**:

1. Start broad: Short general queries for overview
2. Narrow down: Refine based on discoveries
3. Recursive collect: Follow in-article links
4. Cross-reference: Compare across vendors/specs
5. Alternative paths: Try official sites if paywalled

**Output**: NULL (writes directly to its own dedicated file)
**Parallel Safety**: Each sub-agent writes only to its assigned `-part-N.md` file

Parallel Execution

Overview

Research sub-agents can be launched in parallel by placing multiple runSubagent (or #tool:agent) calls in the same tool-call block. This significantly reduces total execution time when perspectives are independent.

Note: run_in_terminal and semantic_search cannot be called in parallel. runSubagent, read_file, grep_search, file_search can.

File Collision Avoidance

Each sub-agent must write to a dedicated file to prevent write conflicts:

research/YYYY-MM-DD-<slug>-part-1.md  ← Perspective A
research/YYYY-MM-DD-<slug>-part-2.md  ← Perspective B
research/YYYY-MM-DD-<slug>-part-3.md  ← Perspective C

After all sub-agents complete, the orchestrator merges the parts:

1. Deduplicate overlapping content 2. Renumber citation footnotes 3. Add cross-perspective connections 4. Output final research/YYYY-MM-DD-<slug>.md 5. Delete -part-N.md files

When to Parallelize vs Serialize

Cautions

• API Rate Limits: Parallel sub-agents hitting the same API (e.g., Brave Search 1 req/s) may trigger 429 errors. Each sub-agent should handle retries independently.
• Context Isolation: Parallel sub-agents cannot see each other's results. Cross-referencing happens only in the merge step.

Evaluator Sub-agent

**Purpose**: Analyze report quality and identify gaps.

**Input**:

- Path: <report file>
- Topic: <original topic>

**Detection Criteria** (by priority):

1. **Missing information** (high): Gaps in coverage
2. **Missing citations** (high): Facts without references
3. **Unsubstantiated claims** (high): Opinions as facts
4. **Insufficient explanation** (medium): Key concepts unclear
5. **Stale information** (low): Outdated data

**Output**: JSON list of issues found

Stop Conditions

Coverage (early exit OK)

• Each sub-question has 2+ independent sources
• New searches yield no new information
• Contradictions resolved or documented

Budget Limits (hard stop)

Error Handling

Output Format

Report Template

---
topic: <topic>
date: YYYY-MM-DD
status: draft|review|final
sources_count: <N>
reflection_count: <N>
---

# <Topic> Research Report

## TL;DR

<1-3 sentence summary>

## Findings

### <Section 1>

<content>[^1]

### <Section 2>

<content>[^2]

## References

[^1]: <URL> - <description>

[^2]: <URL> - <description>

## Limitations

- <points not verified>
- <areas needing more research>

Manifest (History)

Track research sessions in research/manifest.md:

## Research History

| Date       | Topic   | File   | Status      | Sources |
| ---------- | ------- | ------ | ----------- | ------- |
| YYYY-MM-DD | <topic> | <file> | draft/final | N       |

## Latest Session

### YYYY-MM-DD: <topic>

- **Perspectives**: <list>
- **Reflections**: N/5
- **Stop reason**: Coverage / Budget / User
- **Unresolved**: <remaining issues>

Permissions Pattern

### Allowed
- Web page fetch and analysis
- Documentation search
- File creation in `research/`
- Sub-agent invocation

### Forbidden
- ❌ Don't present inference as fact
- ❌ Don't cite unusual facts without reference
- ❌ Don't edit files outside `research/`

Anti-patterns

Key Principles

1. Facts Only: No inference, no opinions, no recommendations 2. Citation Everything: Every non-trivial fact needs a source 3. Recursive but Bounded: Follow links, but with hard limits 4. Quality Gates: Evaluator sub-agent before finalization 5. Transparent Limitations: Document what wasn't verified

External References

• Anthropic: Multi-Agent Research System - 8 principles for multi-agent design
• LangChain: Deep Agents - 4 elements of Deep Agents
• PromptLayer: How Deep Research Works - 5-phase process, stop conditions
• openjny: なんちゃって Deep Research - VS Code Copilot implementation
• OpenAI: Introducing Deep Research - Official specification

External Resources for AI Agents

AI エージェント開発に役立つ外部リソース集。

First-Hop References

まず最初に当たるリンク。設計判断や platform behavior を確認したいときはここから入る。

Deep References

深掘り用。設計原則の確認後に、具体的な prompt / skill / hook / orchestration の実装例を探すときに使う。

プロンプト・インストラクション

Claude Code 関連

VS Code カスタマイズ

ツール・ユーティリティ

Community Exploration

コミュニティ資産の探索用。first-hop の代わりではなく補助として使う。

注目カテゴリ（Awesome Claude Code より）

Agent Skills

• DevOps スキル、セキュリティスキル、Web 資産生成など

Workflows & Knowledge Guides

• AB Method, RIPER Workflow, Ralph Wiggum パターン

Tooling

• IDE 統合、使用量モニター、オーケストレータ

Hooks

• TDD Guard, TypeScript Quality Hooks, Britfix

How to Use This List

1. プロジェクトに合わせて選択: 全てを導入せず、必要なものだけ 2. カスタマイズ: そのまま使わず、プロジェクト固有の要件を追加 3. 定期更新: これらのリソースは頻繁に更新されるのでチェック 4. ライセンス確認: 各リソースのライセンスを確認してから使用

Selection Rule

• 設計判断に迷ったら First-Hop References を先に使う
• 実装パターンや周辺事例を広く探したいときだけ Deep References / Community Exploration へ進む
• 本体 SKILL に戻す外部リンクは First-Hop の中から少数だけ選ぶ

Hooks Guide

Hooks are deterministic lifecycle automation for agent sessions.

Use hooks when workflow behavior must run, block, ask, or inject context at a known event. Do not use hooks for guidance that can remain conversational.

When to Use

Good fit

• block dangerous commands before execution
• require confirmation at specific lifecycle events
• inject standard runtime context at session start
• run validation or formatting after successful tool use

Bad fit

• style guidance that can live in instructions
• role specialization that belongs in an agent
• reusable workflows with assets that belong in a skill

Guidance vs Enforcement

If the requirement includes "always block", "must ask", "auto-run", or "inject at session start", evaluate Hook first.

Locations

Prefer workspace hooks for team policy. Keep personal automation outside the repo when it should not be shared.

Lifecycle Events

Minimal Shape

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ]
  }
}

Each command can define platform-specific overrides, cwd, env, and timeout.

Decision Heuristic

Choose Hook only if all of these are true:

1. The behavior must happen at a specific lifecycle event 2. Guidance alone is insufficient 3. A shell command can evaluate or enforce the rule safely

If any of the three is false, prefer prompt / instruction / skill / agent.

Core Principles

1. Keep hooks small and auditable 2. Prefer explicit block/ask rules over opaque automation 3. Avoid hardcoded secrets or environment-specific values 4. Do not let long-running hooks stall normal workflow

Common Patterns

Ask before dangerous tool use

Use PreToolUse when a command or tool category needs human confirmation.

Auto-validate after edits

Use PostToolUse when formatting, linting, or policy checks should run after successful file changes.

Inject startup context

Use SessionStart when the agent should receive deterministic context before normal work begins.

Session-scoped guardrails

If the platform supports hooks that are activated only for a specific skill, command, or session, use them for safeguards that would be too noisy as always-on policy.

Good fits:

• stricter destructive-command blocking while touching production or infrastructure
• write-freeze rules during debugging or audit-only work
• temporary validation that belongs to one workflow but not normal chat

Keep these hooks narrow, visible, and easy to disable when the workflow ends.

Lightweight telemetry

Hooks can also record small routing or workflow signals when you need evidence for improvement.

Good fits:

• skill name or workflow name
• manual vs automatic trigger
• success, fallback, or blocked outcome
• missing expected trigger, when the platform exposes it

Use local append-only logs or aggregated counters. Do not log prompt text, secrets, personal data, customer data, or raw tool payloads.

Anti-patterns

• using hooks for soft preferences that belong in instructions
• building large workflow logic inside hooks
• creating hooks before you can name the lifecycle event they depend on
• running slow hooks that make ordinary tasks feel broken
• making a high-friction hook always-on when it only belongs to one risky workflow
• collecting telemetry broadly without a concrete routing or quality question

VS Code Custom Agents — 配置・アクセス制御リファレンス

Merged from former vscode-custom-agents skill (2026-02-26)

配置ルール（Critical）

.github/agents/ は直下のみスキャンされる

✅ 認識される
.github/agents/
├── orchestrator.agent.md
├── coding.executor.md
└── quality.reviewer.md

❌ 認識されない
.github/agents/
├── executors/
│   └── coding.executor.md    ← 無視される
└── reviewers/
    └── quality.reviewer.md   ← 無視される

根拠: VS Code 公式ドキュメント (2026-02 時点)

"VS Code detects any .md files in the .github/agents folder of your workspace as custom agents."

サブディレクトリの再帰スキャンは非対応（実証テスト済み）。

配置場所の選択肢

ファイル拡張子

アクセス制御（3段階）

frontmatter プロパティ

重要: agents リストに明示すると disable-model-invocation: true をオーバーライドできる。

パターン早見表

# 1. ユーザーが直接呼ぶ + サブエージェントとしても呼ばれる（デフォルト）
user-invocable: true    # (省略可)

# 2. サブエージェント専用（ピッカー非表示）
user-invocable: false

# 3. ユーザー専用（他エージェントから呼ばれない）
disable-model-invocation: true

# 4. 特定の親からのみ呼ばれるサブエージェント
user-invocable: false
disable-model-invocation: true
# → 親側の agents リストに明示して呼ぶ

⚠️ Deprecated プロパティ

Orchestrator + Workers パターン

# orchestrator.agent.md
---
name: orchestrator
user-invocable: true
disable-model-invocation: true
tools: ["codebase", "terminal", "agent"] # "agent" が必須
agents:
  - coding-executor
  - quality-reviewer
---

# coding.executor.md
---
name: coding-executor
user-invocable: false
tools: ["codebase", "terminal"]
---

ポイント:

• orchestrator に agent ツールを含めないとサブエージェント呼び出しが機能しない
• agents リストで呼び出せるサブエージェントを制限する
• agents: [] で全サブエージェント利用を禁止
• agents: '*' で全許可（デフォルト）

トラブルシューティング

デバッグ方法

1. Chat Diagnostics: チャットビューで右クリック → Diagnostics で認識エージェント一覧を確認 2. `runSubagent` テスト: サブエージェントを直接呼び出して応答確認 3. セッションコンテキスト確認: <agents> タグに何が注入されているかで認識状態を判定

Pattern 0: Plan-First (Meta-Pattern)

Always create a plan before execution

Back to overview.md

Diagram

graph LR
    A[Task Request] --> B[Create Plan]
    B --> C[User Reviews Plan]
    C -->|Approved| D[Execute]
    C -->|Changes Needed| B
    D --> E[Track Progress]
    E --> F[Complete]

Characteristics

When to Use

• Task is complex or multi-step
• Execution is costly (time, resources, or reversibility)
• Ambiguity exists in requirements
• Risk of misunderstanding user intent

Implementation Pattern

Step 1: Analyze Request
  - Understand goal and constraints
  - Identify subtasks and dependencies

Step 2: Generate Plan
  - List concrete steps with rationale
  - Estimate effort/time per step
  - Identify risks and alternatives

Step 3: Present for Approval
  - Show plan in clear format
  - Ask: "Does this plan meet your expectations?"

Step 4: Execute (only after approval)
  - Follow plan systematically
  - Report progress at key milestones

Plan Format Example

## Plan for [Task Name]

**Goal:** [Clear statement of what will be accomplished]

**Steps:**
1. [Action] - [Rationale] (Est: [time/effort])
2. [Action] - [Rationale] (Est: [time/effort])

**Risks:**
- [Risk 1]: [Mitigation approach]

**Approval Needed:** Please confirm before I proceed.

Why This Matters

From vscode-ai-toolkit best practices:

"Generate a plan first and ask the user for approval. This prevents wasted effort on the wrong approach."

Anti-Pattern: Plan-Free Execution

Bad: Jump straight to implementation without discussing approach Good: Propose plan, get feedback, adjust, then execute