From AI Writer
Create and update agent definition files following Anthropic best practices. Use when writing agent files, creating subagents, designing agent systems, or troubleshooting agent discovery and delegation issues.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-writer:agent-writerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create well-structured agent definition files for Claude Code following Anthropic's best practices for subagents and multi-agent systems.
Create well-structured agent definition files for Claude Code following Anthropic's best practices for subagents and multi-agent systems.
Creating a new agent:
Agent definitions use Markdown files with YAML frontmatter:
---
name: agent-name
description: When to use this agent
tools:
allowed:
- Read
- Grep
- Glob
model: sonnet
---
# Agent Identity
You are a [role] specializing in [domain].
## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Deliverables
Provide output in this format:
- [Structure]
## Guardrails
**NEVER:**
- [Anti-pattern 1]
**ALWAYS:**
- [Best practice 1]
| Scope | Location | Use When |
|---|---|---|
| Project | .claude/agents/ | Agent is codebase-specific, version controlled |
| User | ~/.claude/agents/ | Personal agent used across all projects |
| Plugin | <plugin>/agents/ | Distributing via plugin system |
Priority: Managed > CLI > Project > User > Plugin
name:
name: code-reviewer
name: ai-marketplace:compile-debug # Plugin namespace
description:
# Good - specific with triggers
description: "Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code."
# Bad - too vague
description: "Helper agent"
tools: - Principle of least privilege
tools:
allowed:
- Read
- Grep
- Glob
model: - Strategic assignment
model: opus # High-stakes reviews
model: haiku # Fast exploration
skills: - Preload context
skills:
- compile-bisect
- pytorch-inductor
For complete field reference, see reference.md
Formula: [What it does] + [When to use it] + [Key triggers]
✅ Good:
description: "Skill-driven debugger specialist for automatically isolating compilation failures. Use when debugging torch.compile errors, crashes, or incorrect output to identify which backend/subsystem fails."
❌ Too vague:
description: "Helper agent"
Tips:
# Agent Name
## Identity
You are a [role] specializing in [domain]. Your role is to:
- [Primary responsibility 1]
- [Primary responsibility 2]
**Scope**: [What's in scope]
**Not in scope**: [What to delegate]
## Deliverables
Return [format] in this structure:
[Expected output format]
## Workflow
1. **[Phase 1]**
- [Steps]
- [Expected outcome]
2. **[Phase 2]**
- [Steps]
- [Expected outcome]
## Guardrails
**NEVER:**
- [Anti-pattern with reason]
**ALWAYS:**
- [Best practice with reason]
Grant only the tools necessary for the agent's purpose.
Read-Only Analysis:
tools:
allowed:
- Read
- Grep
- Glob
Code Modification:
tools:
allowed:
- Read
- Edit
- Write
- Grep
- Glob
Agent (no nesting)AskUserQuestionEnterPlanModeExitPlanModeScheduleWakeupRoutes tasks to specialists and synthesizes responses:
callable_agents:
- specialist-1
- specialist-2
parent_agent: null
Deep expertise in specific domain:
callable_agents:
- compile-debug
parent_agent: compile-debug
For detailed patterns, see reference.md
Critical: Subagents start with fresh context.
Subagents receive:
Subagents do NOT receive:
Best Practice: Include necessary context in delegation prompt.
# Bad - assumes prior knowledge
"Continue with the approach we discussed"
# Good - provides full context
"Implement OAuth 2.0 with JWT tokens. Files: src/auth/login.py, src/auth/tokens.py. Requirements: 1hr token expiry, refresh support."
❌ Vague descriptions - "Helper agent" ✅ Specific descriptions - "Skill-driven debugger for torch.compile failures"
❌ Overly broad scope - One agent doing everything ✅ Focused purpose - Single, specific capability
❌ Excessive tool access - Read-only agent with Write/Edit ✅ Least privilege - Only necessary tools
❌ Missing context - "Debug the issue" ✅ Full context - "Debug auth failure in login.py. Error: 'Invalid token'. Stack trace: [...]"
name is lowercase, hyphens only, max 64 charsdescription is specific and < 1024 charstools uses least privilegemodel matches task complexitySee examples.md for complete agent definitions:
See reference.md for:
When creating an agent with this skill, I will:
Ask clarifying questions:
Create agent definition with:
Validate against requirements:
Provide testing instructions:
The result will be a complete, working agent definition following all Anthropic best practices.
npx claudepluginhub torchedhat/ai-marketplace --plugin ai-writerGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.