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.md

• frameworks/shared-skills/skills/claude-code-agents/references/agent-tools.md

• frameworks/shared-skills/skills/claude-code-agents/data/sources.json

• frameworks/shared-skills/skills/claude-code-skills/SKILL.md

• frameworks/shared-skills/skills/claude-code-commands/SKILL.md

• frameworks/shared-skills/skills/claude-code-hooks/SKILL.md