Guide · Agent skill
How to use the Agent Development Guide agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The agent-development skill is a guide that Claude loads when you ask it to create a Claude Code subagent, which is a specialised helper that runs a multi-step task on its own. It is written for plugin developers and teams who want their agents to follow one consistent file format. After this guide you will know how to install the skill, how to trigger it with a natural request, what the skill gives the agent, and what to check before you rely on the result.
Agent Development Guideanthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 2Start a request for an agent. Describe the agent you need in plain words, for example asking for a subagent that reviews code for security issues.
- 3Choose a unique name. Pick a lowercase, hyphenated identifier of 3 to 50 characters that does not start or end with a hyphen.
- 4Write a trigger-focused description. Use 'Use this agent when...' and name two to four trigger scenarios, plus cases where the agent should not be used.
- 5Set model, color and tools. Use inherit for the model, pick a color for the agent's job, and list only the tools it needs.
- 6Write the system prompt. Use second person, define responsibilities, a step-by-step process, output format and edge cases, and keep it within the length guidance.
- 7Validate and save. Run scripts/validate-agent.sh in a Bash shell, then save the file as agents/agent-name.md in your plugin.
What does the agent-development skill make Claude do?
When you ask for help creating a subagent, this skill gives Claude the file format, naming rules, field options and writing guidance to follow. It explains how to write the description that tells Claude when to use the agent, how to write the system prompt, and how to limit which tools the agent can use.
The skill also includes a script, scripts/validate-agent.sh, that checks an agent file for correct structure. Agents are meant for autonomous work, while commands are for actions a user starts directly.
- Agent file format: Markdown with YAML frontmatter
- Frontmatter fields: name, description, model, color and tools
- System prompt design: second-person writing, process steps, output format and edge cases
- Triggering through the description field, with prose examples
- A reference file of templates and complete example agents
How do you install the agent-development skill?
Download the ZIP file from this page. Then choose one of two install locations. For a personal install, unzip the folder into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need a special command. Ask for agent help in plain words. The skill's description lists phrases that should activate it, so the closer your request is to them, the more reliable the trigger.
Phrases the description names include 'create an agent', 'add an agent', 'write a subagent', 'agent frontmatter', 'when to use description', 'agent examples', 'agent tools', 'agent colors' and 'autonomous agent'. You can also ask for guidance on agent structure, system prompts, triggering conditions or agent best practices for Claude Code plugins.
- Write a subagent that reviews pull requests for security issues in my plugin.
- Add an agent to my plugin that generates API docs from code comments.
- What should my agent's description say so Claude knows when to use it?
- Which tools should a read-only analysis agent be allowed to use?
What does a complete agent file look like?
An agent is a Markdown file with a YAML frontmatter block followed by the system prompt. The frontmatter holds the name, description, model, color and optional tools list. The body is written in second person and includes a 'When to invoke' section with worked scenarios.
Save the finished file as agents/agent-name.md inside your plugin. All .md files in the agents/ folder are auto-discovered.
---
name: code-reviewer
description: Use this agent when the user has written code and needs quality review. Typical triggers include an explicit review request and a pre-commit check. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Grep", "Glob"]
---
You are an expert code quality reviewer...How should you fill in the name, description, model, color and tools fields?
The name must be 3 to 50 characters, using lowercase letters, numbers and hyphens, starting and ending with a letter or number. The description is the most important field, because Claude uses it to decide when to dispatch the agent. Name two to four trigger scenarios in it and say when the agent should not be used.
Set model to inherit unless the agent needs a specific model. Pick a color that matches the agent's job. Limit tools to the minimum the agent needs; if you omit the field, the agent can use all tools.
- name: lowercase, numbers, hyphens; 3-50 characters; no underscores
- model: inherit (recommended), sonnet, opus or haiku
- color: blue, cyan, green, yellow, magenta or red
- tools: for example read-only ["Read", "Grep", "Glob"] or code generation ["Read", "Write", "Grep"]
How do you check an agent file with the validation script?
The skill includes scripts/validate-agent.sh, which checks an agent file for correct structure. Running it requires a Bash shell. The script is part of this skill, so review it before running it on your machine.
The skill's validation rules set length limits you can check by hand: the description should be 10 to 5,000 characters (200 to 1,000 is best), and the system prompt should be 20 to 10,000 characters (500 to 3,000 is best).
- Run the script in a Bash shell
- Check identifier length and characters
- Check description length and that it names trigger conditions
- Check system prompt length and structure
What people use it for
- Building a code review agent that runs security and quality checks after code is written
- Creating a test generator that reads code and proposes tests, with Read, Write and Grep as its only tools
- Writing a read-only analysis agent limited to Read, Grep and Glob
- Standardising the agents a team writes so every agent file has the same structure and validation
- Producing an agent definition from a short description using the AI-assisted prompt pattern in the skill
Frequently asked questions
How do I install the agent-development skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What do I need to use the agent-development skill?
The skill's listing says you need a Bash shell to run the validation script and Claude Code or a compatible agent runtime to load the agent files it helps you write. The listing says it runs scripts and does not use the network.
Is the agent-development skill free?
The listing states the licence is Apache-2.0. This guide does not cover pricing, so check the source page for any cost information.
Is this skill for non-developers?
Not really. It is for plugin developers building custom Claude Code subagents and teams standardising internal agents. If you only want to use an existing agent, this skill is not the right fit.
Why won't Claude use my agent?
The description field controls when Claude dispatches an agent. Make sure it starts with 'Use this agent when', names two to four trigger scenarios, and covers different phrasings of the same intent. Check that the name follows the naming rules too.
Can I restrict which tools an agent can use?
Yes. Add a tools array to the frontmatter, such as ["Read", "Grep", "Glob"] for read-only analysis. If you omit tools, the agent has access to all tools, so the skill recommends limiting them to the minimum needed.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a plugin developer or a team that needs consistent, validated Claude Code subagent files and you are comfortable running a Bash script. Pick something else if you only want to use existing agents or need a one-off prompt that does not need a reusable autonomous helper.
Download the skill