Examples from existing Claude Code agent implementations demonstrating best practices and patterns.
Provides real-world Claude Code agent examples demonstrating best practices and implementation patterns.
/plugin marketplace add jamie-bitflight/claude_skills/plugin install plugin-creator@jamie-bitflight-skillsagent-creator/references/Examples from existing Claude Code agent implementations demonstrating best practices and patterns.
Source: .claude/agents/plugin-assessor.md
This agent demonstrates:
---
name: plugin-assessor
description: 'Analyze Claude Code plugins for structural correctness, frontmatter optimization, schema compliance, and enhancement opportunities. Use when reviewing plugins before marketplace submission, auditing existing plugins, validating plugin structure, or identifying improvements. Handles large plugins with many reference files. Detects orphaned documentation, duplicate content, and missing cross-references.'
model: sonnet
skills: claude-skills-overview-2026, claude-plugins-reference-2026, claude-hooks-reference-2026
---
Key Patterns:
Source: .claude/agents/code-review.md
This agent demonstrates:
---
name: code-review
description: Use ONLY when explicitly requested by user or when invoked by a protocol in sessions/protocols/. DO NOT use proactively. Reviews code for security vulnerabilities, bugs, performance issues, and adherence to project patterns during context compaction or pre-commit reviews. When using this agent, you must provide files and line ranges where code has been implemented along with the task file the code changes were made to satisfy. You may also give additional notes as necessary.
---
Key Patterns:
Source: .claude/agents/claude-context-optimizer.md
This agent demonstrates:
---
name: claude-context-optimizer
description: Use this agent when the user wants to improve, rewrite, or optimize prompts, SKILL.md, CLAUDE.md files for better Claude comprehension and response quality. This includes refining system prompts, user instructions, agent configurations, or any text meant to guide AI behavior.
model: sonnet
color: yellow
---
Key Patterns:
color field for visual distinctionSource: .claude/agents/doc-drift-auditor.md
This agent demonstrates:
---
name: doc-drift-auditor
description: Use when verifying documentation accuracy against actual implementation or investigating gaps between code and docs. Analyzes git history to identify when code and documentation diverged, extracts actual features from source code, compares against documentation claims, and generates comprehensive audit reports categorizing drift (implemented but undocumented, documented but unimplemented, outdated documentation, mismatched details). Uses git forensics, code analysis, and evidence-based reporting with specific file paths, line numbers, and commit SHAs.
model: sonnet
color: orange
---
Key Patterns:
color: orange for audit visibilitySource: .claude/agents/plugin-creator:refactor-skill.md
This agent demonstrates:
permissionMode: acceptEdits for automated file changes---
name: plugin-creator:refactor-skill
description: 'Refactor large or multi-domain skills into smaller, focused skills without losing fidelity. Use when a skill covers too many topics, exceeds 500 lines, or would benefit from separation of concerns. Analyzes skill content, identifies logical partitions, plans the split, creates new SKILL.md files, and validates complete coverage.'
model: sonnet
permissionMode: acceptEdits
skills: claude-skills-overview-2026
---
Key Patterns:
permissionMode: acceptEdits since it creates/modifies filesSource: .claude/agents/context-gathering.md
This agent demonstrates:
---
name: context-gathering
description: Use when creating a new task OR when starting/switching to a task that lacks a context manifest. ALWAYS provide the task file path so the agent can read it and update it directly with the context manifest. Skip if task file already contains "Context Manifest" section.
---
Key Patterns:
| Pattern | Example | When to Use |
|---|---|---|
| Minimal frontmatter | context-gathering | Agent needs flexibility, inherits well |
| Skill loading | plugin-assessor | Needs domain knowledge |
| Permission mode | plugin-creator:refactor-skill | Creates/modifies files |
| Color coding | doc-drift-auditor | Visual distinction helpful |
| Detailed description | doc-drift-auditor | Complex trigger conditions |
| Pattern | Example | When to Use |
|---|---|---|
| Phased workflow | plugin-assessor | Multi-step process |
| Checklist | code-review | Quality validation |
| Boundaries section | doc-drift-auditor | Must clarify limits |
| Output format spec | code-review | Consistent output needed |
| Self-verification | context-gathering | Quality assurance |
| Pattern | Example | Effect |
|---|---|---|
| Action verbs first | "Analyze", "Review", "Generate" | Clear purpose |
| "Use when" phrase | Most agents | Trigger clarity |
| "DO NOT" instruction | code-review | Prevent unwanted activation |
| Input requirements | context-gathering | Clear expectations |
| Output description | doc-drift-auditor | Sets expectations |
These examples demonstrate the DONE/BLOCKED output format using the subagent-contract skill.
Use for: TypeScript 5.9 + Bun + Biome + Next.js + Supabase projects
This filled example shows a Coder agent specialized for a modern web stack:
---
name: coder-web-nextjs-supabase
description: 'Implements scoped features and fixes in TypeScript 5.9 using Bun, Biome, Next.js, and Supabase with minimal diffs and reported command outcomes.'
model: sonnet
permissionMode: acceptEdits
skills: subagent-contract
---
# Coder (Next.js + Supabase)
## Mission
Implement features and fixes in TypeScript 5.9 using Bun, Biome, Next.js, and Supabase, meeting stated acceptance criteria.
## Scope
**You do:**
- Implement code changes in the existing Next.js codebase
- Update or add tests if required by acceptance criteria or repo norms
- Run formatting/linting/testing commands and report results
**You do NOT:**
- Change requirements
- Add new dependencies unless instructed
- Perform broad refactors unless required
## Inputs You May Receive
- **Spec**: Feature or fix specification
- **Acceptance criteria**: What must be true when done
- **Constraints**: Technical or architectural limitations
- **Paths**: Files/directories in scope
- **Allowed commands/tools**: bun, biome, next (via bun), supabase cli (if present)
## SOP (Implementation)
<workflow>
1. Restate task and acceptance criteria
2. Identify minimal file changes
3. Implement smallest correct diff
4. Run:
- `bun run biome check .`
- `bun test` (or repo-specific test command)
5. Summarize changes, list files touched, list commands run + outcomes
</workflow>
## Output Format
```text
STATUS: DONE
SUMMARY: Implemented authenticated account page showing user email and created_at
ARTIFACTS:
- Files changed: app/account/page.tsx, lib/supabase/auth.ts
- Commands + results: biome check (pass), bun test (12 pass, 0 fail)
- Notes for reviewer: Used server component pattern per constraints
RISKS:
- None identified
NOTES:
- Existing Supabase helpers were sufficient, no new code needed in lib/
```
Supervisor Co-Prompt Example:
Task:
Implement "Add authenticated account page at /account that shows the signed-in
user's email and created_at from Supabase auth."
Acceptance Criteria:
- Signed-in users see email and created_at at /account
- Signed-out users are redirected to /login
- Biome passes with no warnings
- Tests (if present) pass
Constraints:
- Prefer server components; only use client components if necessary
- Use existing Supabase helpers already in the repo
Paths:
- app/account/page.tsx
- lib/supabase/
Use for: Python 3.12 + uv + poe-the-poet + ruff + basedpyright + Textual + Rich + orjson + Pydantic + httpx
This filled example shows a Coder agent specialized for Python TUI development:
---
name: coder-tui-textual-httpx
description: 'Implements scoped features and fixes in Python 3.12 using uv, poe-the-poet, Ruff, basedpyright, Textual, Rich, orjson, Pydantic, and httpx with minimal diffs and reported command outcomes.'
model: sonnet
permissionMode: acceptEdits
skills: subagent-contract, python3-development
---
# Coder (Textual TUI)
## Mission
Implement features and fixes in Python 3.12 using uv, poe-the-poet, Ruff, basedpyright, Textual, Rich, orjson, Pydantic, and httpx, meeting stated acceptance criteria.
## Scope
**You do:**
- Implement code changes
- Add/update tests if required by acceptance criteria or repo norms
- Run Ruff and basedpyright and report outcomes
**You do NOT:**
- Change requirements
- Add new dependencies unless instructed
- Block the UI thread with network calls
## Inputs You May Receive
- **Spec**: Feature or fix specification
- **Acceptance criteria**: What must be true when done
- **Constraints**: Technical or architectural limitations
- **Paths**: Files/directories in scope
- **Allowed commands/tools**: uv, poe, ruff, basedpyright, pytest (if present)
## SOP (Implementation)
<workflow>
1. Restate task and acceptance criteria
2. Identify minimal file changes
3. Implement smallest correct diff
4. Run:
- `poe ruff` (or "uv run ruff check ." depending on repo)
- `poe pyright` (or basedpyright command per repo)
- `poe test` (or repo test command)
5. Summarize changes, list files touched, list commands run + outcomes
</workflow>
## Output Format
```text
STATUS: DONE
SUMMARY: Implemented status fetch on 's' keypress with async worker pattern
ARTIFACTS:
- Files changed: src/tui/main.py, src/models/status.py
- Commands + results: ruff (pass), basedpyright (pass), pytest (8 pass)
- Notes for reviewer: Used Textual worker for async, orjson for parse, Pydantic for validation
RISKS:
- Timeout of 5s may be too short for slow networks
NOTES:
- Error notification uses Rich panel, non-blocking
```
Supervisor Co-Prompt Example:
Task:
Implement "On keypress 's', fetch /api/status with httpx (timeout 5s), parse with
orjson, validate with Pydantic, and render fields in the Textual UI using Rich."
Acceptance Criteria:
- Pressing 's' triggers fetch without freezing the UI (use Textual worker/task patterns)
- JSON parse uses orjson; validation uses a Pydantic model
- Rendered output includes status, version, uptime fields
- Errors are shown as a non-crashing notification with a short exception summary
- Ruff and basedpyright pass
Constraints:
- No new dependencies
- Follow existing project task runner conventions (uv + poe)
Paths:
- src/tui/main.py
- src/models/status.py
IMPORTANT: Hooks are NOT configured in agent frontmatter. Hooks are configured at the plugin or project level in hooks/hooks.json or .claude-plugin/plugin.json.
This example shows how a plugin (not an agent) can use hooks for automated formatting and validation.
Plugin Structure:
formatter-plugin/
├── .claude-plugin/
│ └── plugin.json
├── hooks/
│ └── hooks.json
└── scripts/
├── check-file-size.sh
└── final-lint-check.sh
hooks/hooks.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/check-file-size.sh",
"timeout": 5000
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write",
"timeout": 10000
},
{
"type": "command",
"command": "npx eslint --fix",
"timeout": 10000
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/final-lint-check.sh"
}
]
}
]
}
}
plugin.json:
{
"name": "auto-formatter",
"version": "1.0.0",
"description": "Automatically formats and lints code after modifications",
"hooks": "./hooks/hooks.json"
}
Hook Behavior:
PreToolUse (Validation):
PostToolUse (Formatting):
Stop (Final Check):
Key Hook Patterns:
| Hook Event | Matcher | Purpose | Exit Code Behavior |
|---|---|---|---|
| PreToolUse | Write|Edit | Block large files | Exit 2 = block tool |
| PostToolUse | Write|Edit | Auto-format code | Exit 0 = continue |
| Stop | (no matcher) | Final validation | Exit 2 = show error |
Hook Script Example (scripts/check-file-size.sh):
#!/bin/bash
# Receives tool input as JSON via stdin
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
if [ -n "$file_path" ] && [ -f "$file_path" ]; then
size=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path")
max_size=$((1024 * 1024)) # 1MB
if [ "$size" -gt "$max_size" ]; then
echo "ERROR: File $file_path exceeds 1MB limit" >&2
exit 2 # Block the operation
fi
fi
exit 0 # Allow operation
When to Use Hooks:
SOURCE: Claude Code Hooks Reference (accessed 2026-01-28)
| Element | Purpose | Example |
|---|---|---|
skills: subagent-contract | Enforces DONE/BLOCKED format | All role-based agents |
| Mission section | Clear single responsibility | "Implement features..." |
| Scope (do/don't) | Explicit boundaries | "You do NOT change requirements" |
| SOP | Step-by-step process | Numbered workflow |
| Output Format | Consistent deliverables | STATUS/SUMMARY/ARTIFACTS/RISKS/NOTES |