| name | claude-code-agents |
| description | Create and maintain Claude Code agents/subagents (.claude/agents/*.md) with YAML frontmatter (name/description/tools/model/permissionMode/skills/hooks), least-privilege tool selection, delegation patterns (Task), context budgeting, and safety best practices. |
Claude Code Agents
Create and maintain Claude Code agents/subagents with predictable behavior, least-privilege tools, and explicit delegation contracts.
Quick Start
- Create an agent file at
.claude/agents/<agent-name>.md (kebab-case filename).
- Add YAML frontmatter (required:
name, description; optional: tools, model, permissionMode, skills, hooks).
- Write the agent prompt: responsibilities, workflow, and an output contract.
- Minimize tools: start read-only, then add only what the agent truly needs.
- Test on a real task and iterate.
Minimal template:
---
name: sql-optimizer
description: Optimize SQL queries, explain tradeoffs, and propose safe indexes
tools: Read, Grep, Glob
model: sonnet
---
# SQL Optimizer
## Responsibilities
- Diagnose bottlenecks using query shape and plans when available
- Propose optimizations with risks and expected impact
## Workflow
1. Identify the slow path and data volume assumptions
2. Propose changes (query rewrite, indexes, stats) with rationale
3. Provide a verification plan
## Output Contract
- Summary (1–3 bullets)
- Recommendations (ordered)
- Verification (commands/tests to run)
Workflow (2026)
- Define the agent’s scope and success criteria.
- Choose a model based on risk, latency, and cost (default to
sonnet for most work).
- Choose tools via least privilege; avoid granting
Edit/Write unless required.
- If delegating with
Task, define a handoff contract (inputs, constraints, output format).
- Add safety rails for destructive actions and secrets.
- Add a verification step (checklist, tests, or a dedicated verifier agent).
Frontmatter Fields (Summary)
name (REQUIRED): kebab-case; match filename (without .md).description (REQUIRED): state when to invoke + what it does; include keywords users will say.tools (OPTIONAL): explicit allow-list; prefer small, purpose-built sets.model (OPTIONAL): haiku for fast checks, sonnet for most tasks, opus for high-stakes reasoning, inherit to match parent.permissionMode (OPTIONAL): prefer defaults; change only with a clear reason and understand the tradeoffs.skills (OPTIONAL): preload skill packs for domain expertise; keep the list minimal.hooks (OPTIONAL): automate guardrails; prefer using the hooks skill for patterns and safety.
For full tool semantics and permission patterns, use references/agent-tools.md. For orchestration and anti-patterns, use references/agent-patterns.md.
2026 Best Practices (Domain Expertise)
- Use small, specialized agents; avoid “god agents”.
- Keep agent prompts short; put repo conventions in
CLAUDE.md/project memory and domain knowledge in skills.
- Budget context: pass file paths, minimal snippets, and constraints; avoid dumping long logs/code.
- Use explicit handoffs for subagents: “Goal / Constraints / Inputs / Output Contract”.
- Add a verifier step for risky changes (security, migrations, infra, auth).
- Treat CLI fields/features as moving; verify against official docs in
data/sources.json.
Validation Checklist
- Frontmatter:
name matches filename; description is single-line and trigger-oriented; tools are minimal; model fits risk.
- Prompt: responsibilities are concrete; workflow is actionable; output contract is explicit.
- Delegation: subagent briefs are specific and bounded; orchestrator verifies integration.
- Safety: confirm destructive ops; avoid secrets/PII; follow repository policies.
Navigation
frameworks/shared-skills/skills/claude-code-agents/references/agent-patterns.mdframeworks/shared-skills/skills/claude-code-agents/references/agent-tools.mdframeworks/shared-skills/skills/claude-code-agents/data/sources.jsonframeworks/shared-skills/skills/claude-code-skills/SKILL.mdframeworks/shared-skills/skills/claude-code-commands/SKILL.mdframeworks/shared-skills/skills/claude-code-hooks/SKILL.md
