Review Claude Code sub-agent implementations for best practices in configuration, tool access, hooks, and delegation patterns. Use when creating, auditing, or optimizing sub-agents.
Instrucciones de origen · Vista previa de solo lectura
name
sub-agent-review
description
Review Claude Code sub-agent implementations for best practices in configuration, tool access, hooks, and delegation patterns. Use when creating, auditing, or optimizing sub-agents.
Review Claude Code sub-agent configurations for best practices.
Target: $ARGUMENTS (path to sub-agent file or agents directory)
When to Use This Skill
Creating new sub-agents
Auditing existing sub-agent configurations
Optimizing sub-agent performance and cost
Reviewing tool access and permissions
Implementing sub-agent hooks
Review Process
Discover - Find agent files at $ARGUMENTS (.claude/agents/ or ~/.claude/agents/)
Validate - Check frontmatter and configuration
Evaluate - Score against best practices
Report - Generate findings with recommendations
Sub-Agent File Structure
File Format
Sub-agents are Markdown files with YAML frontmatter:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
model: sonnet
---
Storage Locations
Location
Scope
Priority
Use Case
--agents CLI flag
Session only
1 (highest)
Testing, automation
.claude/agents/
Project
2
Team-shared agents
~/.claude/agents/
User
3
Personal agents
Plugin agents/
Plugin scope
4 (lowest)
Distributed agents
Frontmatter Configuration
Required Fields
Field
Description
Example
name
Unique identifier (kebab-case)
code-reviewer
description
When Claude should delegate
Reviews code for quality. Use proactively after code changes.
Optional Fields
Field
Description
Default
tools
Allowed tools (allowlist)
Inherits all
disallowedTools
Denied tools (denylist)
None
model
sonnet, opus, haiku, inherit
inherit
permissionMode
Permission handling
default
skills
Skills to preload
None
hooks
Lifecycle hooks
None
Configuration Checklist
1. Naming & Description
Name is kebab-case and descriptive
Description explains WHEN to use the agent
Description includes "use proactively" if auto-delegation desired
Description is specific enough for accurate delegation
Critical: Agents directory must be at plugin root, not inside .claude-plugin/.
Plugin Agent Frontmatter
Plugin agents support additional frontmatter fields:
---
description: What this agent specializes in
capabilities: ["task1", "task2", "task3"]
---# Agent Name
Detailed description of the agent's role and when Claude should invoke it.
## Capabilities- Specific task the agent excels at
- Another specialized capability
## Context and examples
When this agent should be used and what problems it solves.
Claude delegates based on description and capabilities
Manual invocation
Users can invoke plugin agents directly
Coexistence
Plugin agents work alongside built-in and user agents
Plugin Anti-Patterns
Anti-Pattern
Problem
Fix
Agents in .claude-plugin/
Not discovered
Move to plugin root
Absolute paths in hooks
Breaks on install
Use ${CLAUDE_PLUGIN_ROOT}
Missing capabilities
Poor auto-delegation
Add capability list
Non-executable scripts
Hooks fail silently
Run chmod +x
Example: Well-Configured Sub-Agent
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
