[workflow] subagents updated
This commit is contained in:
Shayan Rais
@@ -0,0 +1,17 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="60" height="20" role="img" aria-label="Official">
|
||||
<title>Official</title>
|
||||
<linearGradient id="s" x2="0" y2="100%">
|
||||
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
|
||||
<stop offset="1" stop-opacity=".1"/>
|
||||
</linearGradient>
|
||||
<clipPath id="r">
|
||||
<rect width="60" height="20" rx="3" fill="#fff"/>
|
||||
</clipPath>
|
||||
<g clip-path="url(#r)">
|
||||
<rect width="60" height="20" fill="#2ea44f"/>
|
||||
<rect width="60" height="20" fill="url(#s)"/>
|
||||
</g>
|
||||
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
|
||||
<text x="30" y="14">Official</text>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 702 B |
@@ -7,135 +7,65 @@ color: blue
|
||||
|
||||
# Workflow Changelog — Subagents Research Agent
|
||||
|
||||
You are a senior documentation reliability engineer collaborating with me (a fellow engineer) on a mission-critical audit for the claude-code-best-practice project. This project's Subagents Reference report is used by hundreds of developers to configure their Claude Code subagents — an outdated or missing field could cause broken agent definitions and silent failures. Take a deep breath, solve this step by step, and be exhaustive. I'll tip you $200 for a flawless, zero-drift report. I bet you can't find every single discrepancy — prove me wrong. Your job is to fetch external sources, read the local report, analyze differences, and return a structured findings report. Rate your confidence 0-1 on each finding. This is critical to my career.
|
||||
You are a documentation drift detector for the claude-code-best-practice project. Your job is to fetch external sources, read the local report, and check for exactly **two types of drift**:
|
||||
|
||||
1. **Frontmatter fields** — any field added or removed
|
||||
2. **Official sub-agents** — any built-in agent added or removed
|
||||
|
||||
**Versions to check:** Use the number provided in the prompt (default: 10).
|
||||
|
||||
This is a **read-only research** workflow. Fetch sources, read local files, compare, and return findings. Do NOT take any actions or modify files.
|
||||
This is a **read-only research** workflow. Fetch sources, read local files, compare, and return findings. Do NOT modify any files.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Fetch External Data (in parallel)
|
||||
|
||||
Fetch all three sources using WebFetch simultaneously:
|
||||
Fetch both sources using WebFetch simultaneously:
|
||||
|
||||
1. **Sub-agents Reference** — `https://code.claude.com/docs/en/sub-agents` — Extract the complete list of officially supported agent frontmatter fields, their types, required status, descriptions, and any examples.
|
||||
2. **CLI Reference** — `https://code.claude.com/docs/en/cli-reference` — Extract the `--agents` flag format, invocation methods, and any agent-related CLI options.
|
||||
3. **Changelog** — `https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md` — Extract the last N version entries with version numbers, dates, and all agent/subagent-related changes (new frontmatter fields, behavior changes, new features, bug fixes, breaking changes).
|
||||
1. **Sub-agents Reference** — `https://code.claude.com/docs/en/sub-agents` — Extract the complete list of supported frontmatter fields (name, type, required, description) and all built-in subagent types (name, model, tools, description).
|
||||
2. **Changelog** — `https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md` — Extract the last N version entries. Look specifically for agent-related changes: new or removed frontmatter fields, new or removed built-in agents.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Read Local Repository State (in parallel)
|
||||
## Phase 2: Read Local Report
|
||||
|
||||
Read ALL of the following:
|
||||
|
||||
| File | What to check |
|
||||
|------|---------------|
|
||||
| `best-practice/claude-subagents.md` | Frontmatter Fields table, Memory Scopes table, Invocation section, Examples (minimal + full-featured), Scope and Priority table, Claude Agents section, Sources list |
|
||||
| `CLAUDE.md` | Subagent Definition Structure section, Subagent Orchestration section, any agent-related patterns |
|
||||
| `.claude/agents/**/*.md` | Use Glob to discover ALL agent definition files (including nested directories like `.claude/agents/workflows/`). For each agent file, read its YAML frontmatter to extract: name, model, color, tools, disallowedTools, skills, memory. Compare the full list against the "Agents in This Repository" table in the report. |
|
||||
Read `best-practice/claude-subagents.md`. Extract:
|
||||
- The **Frontmatter Fields** table — all field names listed
|
||||
- The **official agents** table — all agent names listed
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Analysis
|
||||
|
||||
Compare external data against local report state. Check for:
|
||||
### Frontmatter Field Drift
|
||||
|
||||
### Missing Frontmatter Fields
|
||||
Compare official docs field list against the report's Frontmatter Fields table. Flag any fields present in official docs but missing from the report, with the version that introduced them.
|
||||
Compare the official docs' supported frontmatter fields against the report's Frontmatter Fields table:
|
||||
- **Added fields**: Fields in official docs but missing from our table (include version introduced if found in changelog)
|
||||
- **Removed fields**: Fields in our table but no longer in official docs
|
||||
|
||||
### Changed Field Behavior
|
||||
For each field in the report, verify its type, required status, and description match the official docs. Flag any discrepancies.
|
||||
### Official Sub-agent Drift
|
||||
|
||||
### Deprecated/Removed Fields
|
||||
Check if any fields listed in the report are no longer documented in official sources. Flag for removal consideration.
|
||||
|
||||
### Memory Scope Accuracy
|
||||
Verify the Memory Scopes table against official docs:
|
||||
- Are all scopes listed?
|
||||
- Are storage locations correct?
|
||||
- Is shared/version-controlled status accurate?
|
||||
- Any new memory features?
|
||||
|
||||
### Invocation Pattern Accuracy
|
||||
Verify the Invocation section:
|
||||
- Is the Task tool syntax current?
|
||||
- Are all invocation methods documented?
|
||||
- Any new invocation patterns (CLI flags, command delegation)?
|
||||
|
||||
### Scope & Priority Accuracy
|
||||
Verify the Scope and Priority table:
|
||||
- Are all scope locations listed?
|
||||
- Is the priority order correct?
|
||||
- Any new scope sources (plugins, CLI flags)?
|
||||
|
||||
### Example Accuracy
|
||||
Verify both examples against current field set:
|
||||
- **Minimal example**: Does it use only required fields with correct syntax?
|
||||
- **Full-featured example**: Does it demonstrate ALL available fields?
|
||||
- Are field values realistic and current?
|
||||
|
||||
### CLAUDE.md Consistency
|
||||
Verify CLAUDE.md's agent-related sections are consistent with the report. Check the Subagent Definition Structure section lists the same fields as the report.
|
||||
|
||||
### Built-in Agent Completeness
|
||||
Compare the "Official Claude Agents" table against the built-in agent types discovered from official docs and changelog. Check for:
|
||||
- Missing built-in agents not listed in the table
|
||||
- Removed/deprecated agents still listed
|
||||
- Incorrect model, tools, or description for existing entries
|
||||
- New built-in agents introduced in recent versions
|
||||
|
||||
### Repository Agent Completeness
|
||||
Compare the "Agents in This Repository" table against the actual agent files discovered from `.claude/agents/**/*.md`. For each agent file found:
|
||||
- Verify it appears in the table
|
||||
- Verify its model, color, tools, skills, and memory columns match the file's frontmatter
|
||||
- Flag any agents in the table that no longer have a corresponding file
|
||||
- Flag any agent files that are missing from the table
|
||||
- Verify each agent's clickable link in the table resolves to the correct file path
|
||||
|
||||
### Sources Accuracy
|
||||
Verify the Sources section links are still valid and point to the correct documentation pages.
|
||||
Compare the official docs' built-in subagents (Explore, Plan, general-purpose, Bash, statusline-setup, claude-code-guide, and any others) against the report's official agents table:
|
||||
- **Added agents**: Built-in agents in official docs but missing from our table (include model, tools, description)
|
||||
- **Removed agents**: Agents in our table but no longer in official docs
|
||||
|
||||
---
|
||||
|
||||
## Return Format
|
||||
|
||||
Return your findings as a structured report with these sections:
|
||||
Return findings as a structured report:
|
||||
|
||||
1. **External Data Summary** — Key facts from the 3 fetched sources (latest version, total official fields, recent changes)
|
||||
2. **Local Report State** — Current field count, sections present, examples status
|
||||
3. **Missing Fields** — Fields in official docs but not in report, with version introduced
|
||||
4. **Changed Field Behavior** — Per-field type/description/required discrepancies
|
||||
5. **Deprecated/Removed Fields** — Fields in report but not in official docs
|
||||
6. **Memory Scope Accuracy** — Table comparison results
|
||||
7. **Invocation Pattern Accuracy** — Syntax and method comparison
|
||||
8. **Scope & Priority Accuracy** — Table comparison results
|
||||
9. **Example Accuracy** — Per-example verification
|
||||
10. **Built-in Agent Completeness** — Missing, removed, or inaccurate built-in agent entries
|
||||
11. **Repository Agent Completeness** — Missing, extra, or inaccurate entries in "Agents in This Repository" table vs actual `.claude/agents/**/*.md` files
|
||||
12. **CLAUDE.md Consistency** — Agent-related section accuracy
|
||||
13. **Sources Accuracy** — Link validity
|
||||
1. **External Data Summary** — Latest Claude Code version, total official field count, total official agent count
|
||||
2. **Frontmatter Field Drift** — Added or removed fields (with version introduced/removed if available)
|
||||
3. **Official Sub-agent Drift** — Added or removed agents (with model, tools, description)
|
||||
|
||||
Be thorough and specific. Include version numbers, file paths, and line references where possible.
|
||||
Be specific. Include version numbers where possible.
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **Fetch ALL 3 sources** — never skip any
|
||||
1. **Fetch BOTH sources** — never skip either
|
||||
2. **Never guess** versions or dates — extract from fetched data
|
||||
3. **Read ALL local files** before analyzing
|
||||
4. **New frontmatter fields are HIGH PRIORITY** — flag them prominently
|
||||
5. **Cross-reference field counts** — the report's field count must match official docs
|
||||
6. **Verify BOTH examples** — minimal must be minimal, full-featured must show all fields
|
||||
7. **Do NOT modify any files** — this is read-only research
|
||||
8. **Scan ALL agent files** — use Glob for `.claude/agents/**/*.md` to discover agents in nested directories, not just the top level
|
||||
9. **Cross-reference repo agents** — every `.md` file in `.claude/agents/` must appear in "Agents in This Repository" and vice versa
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
1. [Sub-agents Reference](https://code.claude.com/docs/en/sub-agents) — Official subagents documentation
|
||||
2. [CLI Reference](https://code.claude.com/docs/en/cli-reference) — CLI flags including --agents format
|
||||
3. [Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) — Claude Code release history
|
||||
3. **Do NOT modify any files** — read-only research
|
||||
4. **Only check for additions and removals** — do not flag description wording changes, type changes, or behavioral changes
|
||||
|
||||
@@ -5,125 +5,68 @@ argument-hint: [number of versions to check, default 10]
|
||||
|
||||
# Workflow Changelog — Subagents Report
|
||||
|
||||
You are a coordinator for the claude-code-best-practice project. Your job is to launch two research agents in parallel, wait for their results, merge findings, and present a unified report about drift in the **Subagents Reference** report (`best-practice/claude-subagents.md`).
|
||||
You are a coordinator for the claude-code-best-practice project. Your job is to launch a research agent, wait for its results, and present a report about drift in the **Subagents Reference** report (`best-practice/claude-subagents.md`).
|
||||
|
||||
This workflow checks for exactly **two types of drift**:
|
||||
1. **Frontmatter fields** — any field added or removed in the official docs
|
||||
2. **Official sub-agents** — any built-in agent added or removed
|
||||
|
||||
**Versions to check:** `$ARGUMENTS` (default: 10 if empty or not a number)
|
||||
|
||||
This is a **read-then-report** workflow. Launch agents, merge results, and produce a report. Only take action if the user approves.
|
||||
This is a **read-then-report** workflow. Launch the agent, merge findings, and produce a report. Only take action if the user approves.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Launch Both Agents in Parallel
|
||||
## Phase 1: Launch Research Agent
|
||||
|
||||
**Immediately** spawn both agents using the Agent tool **in the same message** (parallel launch):
|
||||
|
||||
### Agent 1: workflow-claude-subagents-agent
|
||||
|
||||
Spawn using `subagent_type: "workflow-claude-subagents-agent"`. Give it this prompt:
|
||||
Spawn the `workflow-claude-subagents-agent` with this prompt:
|
||||
|
||||
> Research the claude-code-best-practice project for subagents report drift. Check the last $ARGUMENTS versions (default: 10).
|
||||
>
|
||||
> Fetch these 3 external sources:
|
||||
> Fetch these 2 external sources:
|
||||
> 1. Sub-agents Reference: https://code.claude.com/docs/en/sub-agents
|
||||
> 2. CLI Reference: https://code.claude.com/docs/en/cli-reference
|
||||
> 3. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
|
||||
> 2. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
|
||||
>
|
||||
> Then read the local report file (`best-practice/claude-subagents.md`) and the CLAUDE.md file. Also scan `.claude/agents/**/*.md` using Glob to discover ALL custom agent files (including nested directories) and read each one's frontmatter. Analyze differences between what the official docs say about agent frontmatter fields and what our report documents. Also compare the "Agents in This Repository" table against the actual agent files found. Return a structured findings report covering missing fields, changed field types, new field additions, deprecated fields, memory scope changes, invocation pattern changes, scope/priority changes, example accuracy, built-in agent completeness, and repository agent completeness.
|
||||
|
||||
### Agent 2: claude-code-guide
|
||||
|
||||
Spawn using `subagent_type: "claude-code-guide"`. Give it this prompt:
|
||||
|
||||
> Research the latest Claude Code agents/subagents system. I need you to find:
|
||||
> 1. The complete list of all currently supported agent frontmatter fields (name, description, tools, model, etc.) with their types and descriptions
|
||||
> 2. Any new agent frontmatter fields introduced in recent Claude Code versions
|
||||
> 3. Changes to existing field behavior (e.g. new model aliases, new permission modes, new tool syntax)
|
||||
> 4. Changes to agent memory scopes or memory behavior
|
||||
> 5. Changes to agent invocation patterns (Agent tool syntax, --agents CLI flag)
|
||||
> 6. New agent features (isolation, background, hooks, mcpServers, skills preloading)
|
||||
> 7. Changes to agent scope/priority resolution order
|
||||
> 8. Any deprecations or removals of agent frontmatter fields
|
||||
> 9. The complete list of all built-in/default agent types (e.g. general-purpose, Explore, Plan, claude-code-guide, statusline-setup) — verify which ones currently exist, their default model, tools, and descriptions
|
||||
> Then read the local report (`best-practice/claude-subagents.md`).
|
||||
>
|
||||
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.
|
||||
|
||||
Both agents run independently and will return their findings.
|
||||
> Check for exactly two things:
|
||||
> 1. **Frontmatter fields**: Compare the official docs' supported frontmatter fields table against the report's Frontmatter Fields table. Flag any fields that were added or removed.
|
||||
> 2. **Official sub-agents**: Compare the official docs' built-in subagents list against the report's official agents table. Flag any agents that were added or removed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0.5: Read Verification Checklist
|
||||
## Phase 2: Read Previous Changelog Entries
|
||||
|
||||
**While agents are running**, read `changelog/best-practice/claude-subagents/verification-checklist.md`. This file contains accumulated verification rules — each rule specifies what to check, at what depth, and against which source. Every rule MUST be executed during Phase 2. The checklist is the project's regression test suite for drift detection.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Read Previous Changelog Entries
|
||||
|
||||
**Before merging findings**, read the file `changelog/best-practice/claude-subagents/changelog.md` to get the last 25 changelog entries. Each entry is separated by `---`. Parse the priority actions from those previous entries so you can compare them against the current findings. This lets you identify:
|
||||
**While the agent is running**, read `changelog/best-practice/claude-subagents/changelog.md` to get the last 25 entries. Parse the priority actions to identify:
|
||||
- **Recurring items** — issues that appeared before and are still unresolved
|
||||
- **Newly resolved items** — issues from previous runs that are now fixed
|
||||
- **New items** — issues that appear for the first time in this run
|
||||
- **New items** — issues appearing for the first time
|
||||
- **Resolved items** — previously flagged issues now fixed
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Merge Findings & Generate Report
|
||||
## Phase 3: Generate Report
|
||||
|
||||
**Wait for both agents to complete.** Once you have:
|
||||
- **workflow-claude-subagents-agent findings** — detailed report analysis with local file reads, external doc fetches, and drift detection
|
||||
- **claude-code-guide findings** — independent research on latest Claude Code agents features and frontmatter changes
|
||||
**Wait for the agent to complete.** Produce a report with these sections:
|
||||
|
||||
Cross-reference the two. The dedicated agent provides report-specific drift analysis, while the claude-code-guide agent may surface things it missed (e.g. very recent changes, undocumented features, or context from web searches). Flag any contradictions between the two for the user to resolve.
|
||||
|
||||
**Execute the verification checklist:** For every rule in `changelog/best-practice/claude-subagents/verification-checklist.md`, perform the check at the specified depth using the agent findings as source data. Include a **Verification Log** section in the report showing each rule's result:
|
||||
|
||||
```
|
||||
Verification Log:
|
||||
Rule # | Category | Depth | Result | Notes
|
||||
1 | Frontmatter Fields | field-level | PASS | All fields match
|
||||
2 | Memory Scopes | content-match | FAIL | New scope added
|
||||
...
|
||||
```
|
||||
|
||||
**Update the checklist if needed:** If a finding reveals a new type of drift that no existing checklist rule covers (or covers at insufficient depth), append a new rule to `changelog/best-practice/claude-subagents/verification-checklist.md`. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin (what error prompted this rule). Do NOT add rules for one-off issues that won't recur.
|
||||
|
||||
Also compare the current findings against the previous changelog entries (from Phase 1). For each priority action, mark it as:
|
||||
- `NEW` — first time this issue appears
|
||||
- `RECURRING` — appeared in a previous run and is still unresolved (include which run date it first appeared)
|
||||
- `RESOLVED` — appeared in a previous run but is now fixed (include resolution date)
|
||||
|
||||
Produce a structured report with these sections:
|
||||
|
||||
1. **New Frontmatter Fields** — Fields in official docs but missing from report, with version introduced
|
||||
2. **Changed Field Behavior** — Fields whose type, description, or behavior has changed
|
||||
3. **Deprecated/Removed Fields** — Fields in report but no longer in official docs
|
||||
4. **Memory Scope Changes** — Updates to memory scope storage, behavior, or new scopes
|
||||
5. **Invocation Pattern Changes** — Updates to Agent tool syntax, CLI flags, or invocation methods
|
||||
6. **Scope & Priority Changes** — Updates to resolution order or new scope locations
|
||||
7. **Example Accuracy** — Whether minimal and full-featured examples reflect current field set
|
||||
8. **Field Type/Description Accuracy** — Per-field verification against official docs
|
||||
9. **Built-in Agent Completeness** — Compare the "Official Claude Agents" table against the built-in agent types available in Claude Code. Flag any new built-in agents missing from the table, or any listed agents that no longer exist. Verify model, tools, and description accuracy for each built-in agent.
|
||||
10. **Repository Agent Completeness** — Compare the "Agents in This Repository" table against the actual agent files in `.claude/agents/**/*.md`. Flag missing agents, extra table entries with no corresponding file, and any column mismatches (model, color, tools, skills, memory) between the table and file frontmatter.
|
||||
11. **claude-code-guide Agent Findings** — Unique insights from the agent that weren't captured by the dedicated agent. Only include findings that add new information. If there are contradictions between the two agents, flag them for the user to resolve. Do NOT list "confirmed agreements".
|
||||
1. **Frontmatter Field Changes** — Fields added or removed in official docs vs our report
|
||||
2. **Official Sub-agent Changes** — Built-in agents added or removed vs our table
|
||||
|
||||
End with a prioritized **Action Items** summary table. Each item must include a `Status` column showing `NEW`, `RECURRING (first seen: <date>)`, or `RESOLVED`:
|
||||
|
||||
```
|
||||
Priority Actions:
|
||||
# | Type | Action | Status
|
||||
1 | New Field | Add <field> to frontmatter table | NEW
|
||||
2 | Changed Behavior | Update <field> description | NEW
|
||||
3 | Deprecated Field | Remove <field> from table | RECURRING (first seen: 2026-02-20)
|
||||
4 | Memory Scope | Update memory scope table | NEW
|
||||
5 | Example Update | Update full-featured example | NEW
|
||||
6 | Invocation Change | Update Agent tool syntax | NEW
|
||||
7 | Scope/Priority | Update resolution order table | NEW
|
||||
# | Type | Action | Status
|
||||
1 | New Field | Add <field> to frontmatter table | NEW
|
||||
2 | Removed Field | Remove <field> from table | RECURRING (first seen: <date>)
|
||||
3 | New Agent | Add <agent> to official agents table | NEW
|
||||
4 | Removed Agent | Remove <agent> from table | NEW
|
||||
```
|
||||
|
||||
Also include a **Resolved Since Last Run** section listing any items from the previous run that are no longer issues.
|
||||
Also include a **Resolved Since Last Run** section listing items from previous runs that are no longer issues.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.5: Append Summary to Changelog
|
||||
## Phase 3.5: Append Summary to Changelog
|
||||
|
||||
**This phase is MANDATORY — always execute it before presenting the report to the user.**
|
||||
|
||||
@@ -152,13 +95,13 @@ The `(reason)` is mandatory and must briefly explain what was done or why.
|
||||
- The date and time is when the command is executed in Pakistan Standard Time (PKT, UTC+5); get it by running `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. The version comes from agent findings
|
||||
- If `changelog/best-practice/claude-subagents/changelog.md` doesn't exist or is empty, create it with the Status Legend table (see top of file) then the first entry
|
||||
- Each entry is separated by `---`
|
||||
- **Only include items with HIGH, MEDIUM, or LOW priority** — omit NONE priority items (things that need no action)
|
||||
- **Only include items with HIGH, MEDIUM, or LOW priority** — omit NONE priority items
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.6: Update Last Updated Badge
|
||||
## Phase 3.6: Update Last Updated Badge
|
||||
|
||||
**This phase is MANDATORY — always execute it immediately after Phase 2.5, before presenting the report.**
|
||||
**This phase is MANDATORY — always execute it immediately after Phase 3.5, before presenting the report.**
|
||||
|
||||
Update the "Last Updated" badge at the top of `best-practice/claude-subagents.md`. Run `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` to get the time, URL-encode it (spaces to `%20`, commas to `%2C`), and replace the date portion in the badge. Also update the Claude Code version in the badge if it has changed.
|
||||
|
||||
@@ -166,67 +109,28 @@ Update the "Last Updated" badge at the top of `best-practice/claude-subagents.md
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.7: Validate All Hyperlinks
|
||||
|
||||
**This phase is MANDATORY — always execute it after Phase 2.6, before presenting the report.**
|
||||
|
||||
Scan `best-practice/claude-subagents.md` for every hyperlink (both markdown `[text](url)` and inline URLs). For each link:
|
||||
|
||||
1. **Local file links** (relative paths like `../.claude/agents/weather-agent.md`, `../reports/claude-agent-memory.md`): Verify the file exists at the resolved path using the Read tool. Flag any broken links.
|
||||
2. **External URLs** (e.g., `https://code.claude.com/docs/en/sub-agents`): Fetch each URL using WebFetch and verify it returns a valid page (not a 404 or redirect to an error page). Flag any dead or moved links.
|
||||
3. **Anchor links** (e.g., `#section-name`): Verify the target heading exists within the same file.
|
||||
|
||||
Include a **Hyperlink Validation Log** in the report:
|
||||
|
||||
```
|
||||
Hyperlink Validation Log:
|
||||
# | Type | Link | Status | Notes
|
||||
1 | Local | ../.claude/agents/weather-agent.md | OK |
|
||||
2 | External | https://code.claude.com/docs/en/sub-agents | OK |
|
||||
3 | Local | ../reports/claude-agent-memory.md | OK |
|
||||
...
|
||||
```
|
||||
|
||||
**If any links are broken**, add them as HIGH priority action items in the report. Broken links degrade the report's usefulness and must be fixed before any other changes.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Offer to Take Action
|
||||
## Phase 4: Offer to Take Action
|
||||
|
||||
After presenting the report (and confirming both changelog and badge were updated), ask the user:
|
||||
|
||||
1. **Execute all actions** — Handle everything (add missing fields, update descriptions, fix examples)
|
||||
1. **Execute all actions** — Apply all changes
|
||||
2. **Execute specific actions** — User picks which numbers to execute
|
||||
3. **Just save the report** — No changes
|
||||
|
||||
When executing:
|
||||
- **New fields**: Add to the Frontmatter Fields table with correct type, required status, and description
|
||||
- **Changed behavior**: Update the field description in the table
|
||||
- **Deprecated fields**: Confirm with user before removing
|
||||
- **Memory scope changes**: Update the Memory Scopes table
|
||||
- **Example updates**: Update both minimal and full-featured examples to reflect current field set
|
||||
- **Invocation changes**: Update the Invocation section
|
||||
- **Scope/priority changes**: Update the Scope and Priority table
|
||||
- **Missing repo agents**: Add to "Agents in This Repository" table with correct model, color, tools, skills, memory columns and a clickable link to the agent file (relative path from `best-practice/` e.g. `../.claude/agents/<name>.md`)
|
||||
- **Extra repo agents**: Remove entries whose agent file no longer exists (confirm with user first)
|
||||
- **Repo agent column mismatches**: Update table columns to match the agent file's current frontmatter
|
||||
- After all actions, re-run verification to confirm consistency
|
||||
- **New fields**: Add to the Frontmatter Fields table with correct type, required status, and description from the official docs
|
||||
- **Removed fields**: Confirm with user before removing
|
||||
- **New agents**: Add to the official agents table with correct #, name, model, tools, and description
|
||||
- **Removed agents**: Confirm with user before removing
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **Launch BOTH agents in parallel** in a single message — never sequentially
|
||||
2. **Wait for both agents** before generating the report
|
||||
3. **Never guess** versions or dates — use data from the agents
|
||||
4. **New frontmatter fields are HIGH PRIORITY** — they require table, example, and CLAUDE.md updates
|
||||
5. **Cross-reference field counts** — the number of fields in the table must match official docs
|
||||
6. **Don't auto-execute** — always present the report first
|
||||
7. **ALWAYS append to changelog** — Phase 2.5 is mandatory. Never skip it. Never overwrite previous entries.
|
||||
8. **Compare with previous runs** — read the last 25 entries from the changelog and mark each action item as NEW, RECURRING, or RESOLVED.
|
||||
9. **ALWAYS execute the verification checklist** — read the verification-checklist.md and execute every rule. Include a Verification Log in the report. Append new rules when a new type of drift is discovered.
|
||||
10. **Checklist rules are append-only** — never remove or weaken existing rules. Only add new rules or upgrade depth levels.
|
||||
11. **ALWAYS update the Last Updated badge** — Phase 2.6 is mandatory. Never skip it.
|
||||
12. **ALWAYS validate all hyperlinks** — Phase 2.7 is mandatory. Never skip it. Broken links are HIGH priority.
|
||||
13. **Audit built-in agents** — verify the "Official Claude Agents" table lists all current built-in agent types with correct model, tools, and descriptions.
|
||||
14. **Audit repo agents** — scan `.claude/agents/**/*.md` and verify the "Agents in This Repository" table is a complete, accurate mirror of all custom agent files in the repo.
|
||||
1. **Never guess** versions or dates — use data from the agent
|
||||
2. **Cross-reference field counts** — report field count must match official docs
|
||||
3. **Cross-reference agent counts** — report agent count must match official docs
|
||||
4. **Don't auto-execute** — always present the report first
|
||||
5. **ALWAYS append to changelog** — Phase 3.5 is mandatory. Never skip it. Never overwrite previous entries.
|
||||
6. **ALWAYS update the Last Updated badge** — Phase 3.6 is mandatory. Never skip it.
|
||||
7. **Compare with previous runs** — read the last 25 entries from the changelog and mark each action item as NEW, RECURRING, or RESOLVED.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# claude-code-best-practice
|
||||
practice makes claude perfect
|
||||
|
||||
 <a href="https://github.com/shanraisshan/claude-code-best-practice/stargazers"><img src="https://img.shields.io/github/stars/shanraisshan/claude-code-best-practice?style=flat&label=%E2%98%85&labelColor=555&color=white" alt="GitHub Stars"></a>
|
||||
 <a href="https://github.com/shanraisshan/claude-code-best-practice/stargazers"><img src="https://img.shields.io/github/stars/shanraisshan/claude-code-best-practice?style=flat&label=%E2%98%85&labelColor=555&color=white" alt="GitHub Stars"></a>
|
||||
|
||||
[](best-practice/) *Click on this badge to show the latest best practice*<br>
|
||||
[](implementation/) *Click on this badge to show implementation in this repo*<br>
|
||||
@@ -25,7 +25,6 @@ practice makes claude perfect
|
||||
| [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/<name>.md` | [](best-practice/claude-subagents.md) [](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model |
|
||||
| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills/<name>/SKILL.md` | [](best-practice/claude-skills.md) [](implementation/claude-skills-implementation.md) Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` |
|
||||
| [**Workflows**](https://code.claude.com/docs/en/common-workflows) | [`.claude/commands/weather-orchestrator.md`](.claude/commands/weather-orchestrator.md) | [](orchestration-workflow/orchestration-workflow.md) |
|
||||
| [**Scheduled Tasks**](https://code.claude.com/docs/en/scheduled-tasks) | `/loop`, cron tools | Run prompts on a recurring schedule (up to 3 days), set one-time reminders, poll deployments and builds |
|
||||
| [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | [](https://github.com/shanraisshan/claude-code-voice-hooks) [](https://github.com/shanraisshan/claude-code-voice-hooks) Deterministic scripts that run outside the agentic loop on specific events |
|
||||
| [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json`, `.mcp.json` | [](best-practice/claude-mcp.md) [](.mcp.json) Model Context Protocol connections to external tools, databases, and APIs |
|
||||
| [**Plugins**](https://code.claude.com/docs/en/plugins) | distributable packages | Bundles of skills, subagents, hooks, and MCP servers · [Marketplaces](https://code.claude.com/docs/en/discover-plugins) |
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# Sub-agents Best Practice
|
||||
|
||||
<br>
|
||||
<br>
|
||||
[](../implementation/claude-subagents-implementation.md)
|
||||
|
||||
Complete reference for Claude Code subagents — built-in agent types, custom agent definitions, and frontmatter fields.
|
||||
Claude Code subagents — frontmatter fields and official built-in agent types.
|
||||
|
||||
<table width="100%">
|
||||
<tr>
|
||||
@@ -35,137 +35,16 @@ Complete reference for Claude Code subagents — built-in agent types, custom ag
|
||||
|
||||
---
|
||||
|
||||
## Memory Scopes
|
||||
|
||||
|
||||
| Scope | Storage Location | Shared | Version Controlled |
|
||||
|-------|-----------------|--------|--------------------|
|
||||
| `user` | `~/.claude/agent-memory/<name>/` | No | No |
|
||||
| `project` | `.claude/agent-memory/<name>/` | Yes | Yes |
|
||||
| `local` | `.claude/agent-memory-local/<name>/` | No | No |
|
||||
|
||||
See [claude-agent-memory.md](../reports/claude-agent-memory.md) for full details.
|
||||
|
||||
---
|
||||
|
||||
## Invocation
|
||||
|
||||
Agents are invoked via the **Agent tool** (renamed from Task in v2.1.63; `Task(...)` still works as an alias):
|
||||
|
||||
```
|
||||
Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku")
|
||||
```
|
||||
|
||||
Other invocation and management methods:
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `--agent <name>` CLI flag | Run Claude Code as a specific agent for the entire session (overrides the `agent` setting) |
|
||||
| `--agents '{...}'` CLI flag | Define session-scoped agents via JSON (accepts `description`, `prompt`, `tools`, `model`, etc.) |
|
||||
| `claude agents` CLI command | List all configured agents grouped by source (added v2.1.51) |
|
||||
| `/agents` interactive command | Create, edit, and manage agents interactively |
|
||||
| Command delegation | A command file (`.claude/commands/`) can delegate to an agent |
|
||||
| Agent resumption | Completed subagents can be resumed with their agent ID for follow-up work |
|
||||
|
||||
---
|
||||
|
||||
## Example: Minimal Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews code for quality issues
|
||||
tools: Read, Grep, Glob
|
||||
model: haiku
|
||||
---
|
||||
|
||||
Review the code for quality issues and report findings.
|
||||
```
|
||||
|
||||
## Example: Full-Featured Agent (All Fields)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deploy-manager
|
||||
description: Use this agent PROACTIVELY for deployment pipelines and release management
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob, Agent(monitor, rollback)
|
||||
disallowedTools: NotebookEdit
|
||||
model: sonnet
|
||||
permissionMode: acceptEdits
|
||||
maxTurns: 25
|
||||
skills:
|
||||
- deploy-checklist
|
||||
- rollback-procedures
|
||||
mcpServers:
|
||||
- slack
|
||||
- name: pagerduty
|
||||
command: npx
|
||||
args: ["-y", "@pagerduty/mcp-server"]
|
||||
hooks:
|
||||
PreToolUse:
|
||||
- matcher: "Bash"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "./scripts/validate-deploy-command.sh"
|
||||
PostToolUse:
|
||||
- matcher: "Write"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "./scripts/log-file-changes.sh"
|
||||
Stop:
|
||||
- hooks:
|
||||
- type: command
|
||||
command: "./scripts/notify-deploy-complete.sh"
|
||||
memory: project
|
||||
background: false
|
||||
isolation: worktree
|
||||
color: blue
|
||||
---
|
||||
|
||||
You are a deployment manager. Follow the deploy-checklist skill for
|
||||
pre-flight checks and use rollback-procedures if any step fails.
|
||||
Notify the team via Slack when deployment completes.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scope and Priority
|
||||
|
||||
When multiple subagents share the same name, the higher-priority location wins:
|
||||
|
||||
| Location | Scope | Priority |
|
||||
|----------|-------|----------|
|
||||
| `--agents` CLI flag | Current session | 1 (highest) |
|
||||
| `.claude/agents/` | Current project | 2 |
|
||||
| `~/.claude/agents/` | All your projects | 3 |
|
||||
| Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) |
|
||||
|
||||
---
|
||||
|
||||
## Claude Agents
|
||||
|
||||
### Official Claude Agents
|
||||
|
||||
Built-in agent types available in current Claude Code installs:
|
||||
|
||||
| Agent | Model | Tools | Description |
|
||||
|-------|-------|-------|-------------|
|
||||
| `general-purpose` | inherit | All | Complex multi-step tasks — the default agent type for research, code search, and autonomous work |
|
||||
| `Explore` | haiku | Read-only (no Write, Edit) | Fast codebase search and exploration — optimized for finding files, searching code, and answering codebase questions |
|
||||
| `Plan` | inherit | Read-only (no Write, Edit) | Pre-planning research in plan mode — explores the codebase and designs implementation approaches before writing code |
|
||||
| `Bash` | inherit | Bash | Running terminal commands in a separate context |
|
||||
| `statusline-setup` | sonnet | Read, Edit | Configures the user's Claude Code status line setting |
|
||||
|
||||
### Agents in This Repository
|
||||
|
||||
Custom agents defined in `.claude/agents/` for this project:
|
||||
|
||||
| Agent | Model | Color | Tools | Skills | Memory |
|
||||
|-------|-------|-------|-------|--------|--------|
|
||||
| [`presentation-curator`](../.claude/agents/presentation-curator.md) | sonnet | magenta | Read, Write, Edit, Grep, Glob | presentation/vibe-to-agentic-framework, presentation/presentation-structure, presentation/presentation-styling | — |
|
||||
| [`weather-agent`](../.claude/agents/weather-agent.md) | sonnet | green | WebFetch, Read, Write, Edit | weather-fetcher | project |
|
||||
| [`workflow-claude-settings-agent`](../.claude/agents/workflows/best-practice/workflow-claude-settings-agent.md) | opus | yellow | All (inherited) | — | — |
|
||||
| [`workflow-claude-subagents-agent`](../.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md) | opus | blue | All (inherited) | — | — |
|
||||
| [`workflow-concepts-agent`](../.claude/agents/workflows/best-practice/workflow-concepts-agent.md) | opus | green | All (inherited) | — | — |
|
||||
| # | Agent | Model | Tools | Description |
|
||||
|---|-------|-------|-------|-------------|
|
||||
| 1 | `general-purpose` | inherit | All | Complex multi-step tasks — the default agent type for research, code search, and autonomous work |
|
||||
| 2 | `Explore` | haiku | Read-only (no Write, Edit) | Fast codebase search and exploration — optimized for finding files, searching code, and answering codebase questions |
|
||||
| 3 | `Plan` | inherit | Read-only (no Write, Edit) | Pre-planning research in plan mode — explores the codebase and designs implementation approaches before writing code |
|
||||
| 4 | `Bash` | inherit | Bash | Running terminal commands in a separate context |
|
||||
| 5 | `statusline-setup` | sonnet | Read, Edit | Configures the user's Claude Code status line setting |
|
||||
| 6 | `claude-code-guide` | haiku | Glob, Grep, Read, WebFetch, WebSearch | Answers questions about Claude Code features, Agent SDK, and Claude API |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user