Agent skill

claude-code-agents

Create and configure Claude Code agents with YAML frontmatter, tool selection, model specification, and naming conventions. Reference for building specialized AI subagents that handle complex, multi-step tasks.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/claude-code-agents-majiayu000-claude-skill-regist

SKILL.md

Claude Code Agents — Meta Reference

This skill provides the definitive reference for creating Claude Code agents. Use this when building new agents or understanding agent architecture.

Quick Reference

Field Purpose Required
name Agent identifier (kebab-case) Yes
description When to invoke this agent Yes
tools Allowed tool list No (defaults: all)
model Claude model variant No (default: sonnet)

Agent Structure

text
.claude/agents/
├── code-reviewer.md
├── security-auditor.md
├── test-architect.md
└── system-architect.md

Agent Template

markdown
---
name: agent-name
description: When to use this agent (single line)
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Agent Name

You are a [role description].

## Responsibilities

- Responsibility 1
- Responsibility 2
- Responsibility 3

## Workflow

1. Step 1: [action]
2. Step 2: [action]
3. Step 3: [action]

## Output Format

[Specify expected output structure]

Frontmatter Specification

name (required)

yaml
name: security-auditor

Rules:

  • Kebab-case only
  • Match filename (without .md)
  • Descriptive but concise

description (required)

yaml
description: Analyze code for security vulnerabilities using OWASP Top 10

Rules:

  • Single line, under 200 characters
  • Explain WHEN Claude should invoke this agent
  • Include key capabilities

tools (optional)

yaml
tools: Read, Grep, Glob, Bash, Edit, Write

Available tools:

Tool Purpose Use When
Read Read files Always include
Grep Search content Code analysis
Glob Find files File discovery
Bash Run commands Build, test, git
Edit Modify files Code changes
Write Create files New files
WebFetch Fetch URLs Documentation lookup
WebSearch Search web Research tasks
Task Spawn subagents Delegation

Minimal permissions principle: Only include tools the agent needs.

model (optional)

yaml
model: sonnet  # or opus, haiku
Model Use For Cost
haiku Simple, fast tasks Low
sonnet Most tasks (default) Medium
opus Complex reasoning High

Agent Categories

Analysis Agents (Read-only)

yaml
tools: Read, Grep, Glob

Examples:

  • code-reviewer - Review code quality
  • security-auditor - Find vulnerabilities
  • architecture-analyzer - Analyze system design

Implementation Agents (Read-write)

yaml
tools: Read, Grep, Glob, Edit, Write, Bash

Examples:

  • backend-engineer - Build APIs
  • frontend-engineer - Build UIs
  • test-engineer - Write tests

Research Agents (Web access)

yaml
tools: Read, WebFetch, WebSearch

Examples:

  • documentation-researcher - Find docs
  • technology-scout - Evaluate options

Agent Design Patterns

Single-Responsibility Agent

markdown
---
name: sql-optimizer
description: Analyze and optimize SQL queries for performance
tools: Read, Grep, Glob
model: sonnet
---

# SQL Optimizer

You optimize SQL queries. Focus on:

1. Index usage analysis
2. Query plan examination
3. Performance recommendations

Output optimization suggestions with before/after examples.

Orchestrator Agent

markdown
---
name: fullstack-builder
description: Coordinate frontend, backend, and database changes
tools: Read, Grep, Glob, Task
model: sonnet
---

# Fullstack Builder

You coordinate multi-layer changes by delegating to specialized agents:

1. Analyze requirements
2. Delegate database changes to sql-engineer
3. Delegate API changes to backend-engineer
4. Delegate UI changes to frontend-engineer
5. Verify integration

Verification Agent

markdown
---
name: pre-commit-checker
description: Verify code quality before commits
tools: Read, Grep, Bash
model: haiku
---

# Pre-Commit Checker

Run quality checks:
- [ ] Linting passes
- [ ] Tests pass
- [ ] No console.logs
- [ ] No TODO comments
- [ ] Types correct

Return PASS or FAIL with details.

Agent ↔ Skill Relationship

Agents do work → Skills provide knowledge

text
Agent: backend-engineer
  ├── Uses skill: software-backend (API patterns)
  ├── Uses skill: dev-api-design (REST/GraphQL)
  └── Uses skill: data-sql-optimization (query optimization)

Agents reference skills implicitly—Claude loads relevant skill content based on context.

Naming Conventions

Pattern Example Use For
{role} code-reviewer General role
{domain}-{role} security-auditor Domain-specific
{action}-{target} test-generator Action-focused
{tech}-{role} typescript-migrator Tech-specific

Invocation Patterns

Direct (user triggers)

User: "Review this code for security issues"
Claude: [invokes security-auditor agent]

Via Command

markdown
<!-- .claude/commands/security.md -->
Run security analysis using the security-auditor agent.

Via Another Agent

yaml
# Parent agent
tools: Task  # Can spawn subagents

Quality Checklist

text
AGENT VALIDATION CHECKLIST

Frontmatter:
[ ] name matches filename (kebab-case)
[ ] description explains when to invoke
[ ] tools are minimal necessary
[ ] model appropriate for task complexity

Content:
[ ] Clear role definition
[ ] Specific responsibilities listed
[ ] Workflow steps defined
[ ] Output format specified

Integration:
[ ] Related skills identified
[ ] Commands reference this agent (if applicable)

Security Best Practices

Deny-All Default

Start with no tools, add only what's needed:

yaml
# Reviewer: read-only
tools: Read, Grep, Glob

# Builder: add write access
tools: Read, Grep, Glob, Edit, Write, Bash

Dangerous Command Awareness

Require explicit confirmation for:

  • rm -rf — Recursive delete
  • git push --force — Overwrite history
  • sudo — Elevated permissions
  • DROP TABLE — Database destruction
  • Infrastructure changes (Terraform, K8s)

Context Isolation

  • Each subagent has isolated context window
  • Orchestrator maintains global state (compact)
  • Use CLAUDE.md for shared conventions
  • Never pass full codebase to subagents

Navigation

Resources

Related Skills

Didn't find tool you were looking for?

Be as detailed as possible for better results