Claude Code Agent Development Guide
Design, write, and validate autonomous agents for Claude Code plugins.
The document explicitly recommends least-privilege tool lists and the repository context warns users to trust plugins; however, omitting tools grants access to all tools, and there is no concrete policy for user confirmation, sensitive-data handling, data-flow disclosure, external side effects, or rollback, so points are deducted.
The skill provides substantial structure, field rules, workflows, edge cases, and validation guidance; however, key paths were not executed in this static review, and the documentation requires prose trigger examples while validate-agent.sh separately expects <example> tags, creating an internal convention mismatch. Failure diagnostics and reproducibility evidence are limited, so points are deducted.
The intended audience, agent-development scenarios, inputs, and trigger conditions are generally clear, including proactive and reactive invocation; however, non-fit boundaries, trigger conflicts with competing agents, Chinese-language support, and mainland-China environment fit are not sufficiently addressed, so points are deducted.
The skill includes a version, readable information architecture, progressive reference material, examples, directory and validation guidance, while repository license and official maintenance context provide governance signals; however, it lacks a skill-specific changelog, explicit maintenance responsibility, and a clear update path, and its validator requirements conflict with the prose guidance, so points are deducted.
Copyable frontmatter, system-prompt templates, complete examples, a creation workflow, and validation commands can directly support the core agent-creation task; however, users must still replace placeholders and review outputs, runnable correctness is not established by the static material, and claims such as production-ready or battle-tested lack execution evidence, so the static ceiling applies and points are deducted.
The material is auditable and includes explicit rules, validator source, examples, and a revision-pinned review scope; however, it contains no executed CI results, committed key-path test evidence, or independent corroboration, so the score is capped at the static-review maximum.
- Do not treat omitted tools as a safe default; specify the minimum tool set for each agent and add confirmation, scope, and recovery guidance for writes, execution, or external services.
- Before using validate-agent.sh, reconcile its <example> check with the documentation's prose-trigger format; documentation-compliant agents may otherwise receive warnings or fail.
- Claims such as production-ready, battle-tested, and reliable triggering are not supported by execution results in the supplied static material and still require practical validation.
- Chinese-language prompting, Chinese trigger semantics, and mainland-China network reachability are not documented and should be addressed for FollowSkills users.
What it does & when to use it
This skill is a development guide for agents used in Claude Code plugins. It explains agent file organization, YAML frontmatter, triggering conditions, system-prompt design, model selection, color identification, and tool restrictions. It also covers validation, trigger testing, directory organization, and namespacing. It is a fit for developers adding or maintaining plugin agents, rather than for general automation or standalone model API integrations.
It guides users in creating agents/agent-name.md, defining name, description, model, and color, and writing system prompts with responsibilities, analysis steps, output formats, quality standards, and edge-case handling. It provides validation rules for identifiers, descriptions, and prompts. It also explains how to use scripts/validate-agent.sh for structural validation, scripts/test-agent-trigger.sh for trigger testing, and the plugin README for documentation.
- A Claude Code plugin developer needs to generate an autonomous agent from a user requirement and wants to follow the AI-assisted creation workflow.
- A developer is manually creating an agent for code review, test generation, or API documentation and needs a concrete file and frontmatter structure.
- A plugin maintainer needs to improve triggering descriptions across proactive requests, reactive requests, and alternate phrasings.
- A team wants to restrict an agent's permissions and needs guidance on applying least privilege to its tool list.
- A developer needs to verify that an agent loads correctly, follows its process, and returns the required format.
Pros & cons
- Covers the workflow from agent identifier and frontmatter through prompt design, testing, and documentation.
- Includes concrete field constraints and valid and invalid identifier examples.
- Emphasizes triggering conditions, output formats, quality standards, and edge cases.
- Documents validation and trigger-testing scripts.
- It is explicitly designed for Claude Code plugins, so other agent platforms require adaptation to their loading, directory, and invocation mechanisms.
- The source does not show the implementation of the validation scripts or complete example files, so their exact coverage cannot be confirmed.
- The skill provides guidance rather than executing agent creation or testing itself.
- The exact marketplace plugin name required for installation is not provided.
How to install
The skill is located at plugins/plugin-dev/skills/agent-development/SKILL.md. The README says the plugin directory can be installed through Claude Code's plugin system using /plugin install {plugin-name}@claude-plugins-official. The source does not provide the exact marketplace plugin name for this skill, so no specific name can be supplied.
How to use
In a Claude Code environment with the relevant plugin skill installed, ask for help with requests such as “create an agent,” “add an agent,” “write a subagent,” or “help me write agent frontmatter.” The skill provides guidance on agent structure, triggering conditions, system prompts, models, colors, tool restrictions, and validation. The source does not define a separate command or API invocation method.