This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
49
53%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/plugin-dev/skills/agent-development/SKILL.mdQuality
Discovery
72%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description excels at trigger term coverage and distinctiveness, providing a comprehensive list of natural phrases that would help Claude select this skill correctly. However, it is weak on specifying what the skill actually does — it reads more like a trigger list than a capability description. Adding concrete actions (e.g., 'Generates agent YAML configuration, writes system prompts, and scaffolds subagent files') would significantly improve it.
Suggestions
Add a clear 'what it does' statement listing concrete actions, e.g., 'Generates agent YAML frontmatter, writes system prompts, scaffolds subagent files, and configures agent tools for Claude Code plugins.'
Restructure to lead with capabilities first, then follow with 'Use when...' clause containing the trigger terms, rather than leading entirely with trigger conditions.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions some domain-specific concepts like 'agent structure', 'system prompts', 'triggering conditions', 'agent frontmatter', and 'agent development best practices for Claude Code plugins', but it doesn't list concrete actions the skill performs (e.g., 'generates agent YAML frontmatter', 'writes system prompts'). It focuses more on when to trigger than what it actually does. | 2 / 3 |
Completeness | The 'when' is very well covered with explicit trigger phrases and conditions. However, the 'what does this do' is weak — it says 'needs guidance on agent structure, system prompts, triggering conditions' but doesn't clearly state what the skill produces or what concrete actions it performs. The what is only implied through the trigger terms. | 2 / 3 |
Trigger Term Quality | The description includes an extensive list of natural trigger terms users would say: 'create an agent', 'add an agent', 'write a subagent', 'agent frontmatter', 'agent tools', 'agent colors', 'autonomous agent'. These are realistic phrases a user would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | The description is clearly scoped to Claude Code plugin agent development, with very specific trigger terms like 'agent frontmatter', 'subagent', and 'Claude Code plugins'. This is a distinct niche unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is comprehensive in coverage but severely undermined by verbosity and repetition. The same concepts (trigger scenarios in description, 'When to invoke' section, prose bullets) are restated 5+ times across different sections. While the file format and frontmatter field documentation are useful, the skill would be far more effective at 30-40% of its current length with concrete, fully worked examples replacing the template placeholders.
Suggestions
Cut content by 60%+: eliminate repeated guidance about trigger scenarios/description format (appears in Frontmatter Fields, Creating Agents, Quick Reference, Best Practices, and Implementation Workflow), and remove explanations of basic concepts like second-person writing.
Replace placeholder templates with one or two complete, realistic agent examples (e.g., a fully worked code-reviewer agent with real system prompt content) instead of multiple partial templates with '[condition]' placeholders.
Move detailed reference content (validation rules, color guidelines, system prompt design patterns) into the referenced files (references/system-prompt-design.md, etc.) and keep only a concise summary in SKILL.md.
Add explicit validation feedback loops: specify what validate-agent.sh outputs on failure, common failure modes, and fix-then-retry steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Explains many concepts Claude already knows (what second person is, what YAML frontmatter is, basic file organization). Extensive repetition — the description format, 'When to invoke' pattern, and trigger scenario guidance are repeated 5+ times across different sections. The DO/DON'T lists, validation rules, and best practices sections heavily overlap each other. | 1 / 3 |
Actionability | Provides a complete file format template and concrete examples of good/bad names, which is useful. However, much of the content is template-level with placeholders like '[condition]' and '[Step 1]' rather than fully worked real-world examples. The AI-assisted generation section provides a JSON schema but no complete, copy-paste-ready agent file with realistic content. | 2 / 3 |
Workflow Clarity | The implementation workflow at the end lists 9 steps in sequence, and the manual creation method has 7 steps. However, there are no validation checkpoints or feedback loops — step 7 mentions running a validation script but doesn't specify what to do if validation fails. Testing guidance is vague ('Check Claude loads the agent') without concrete verification commands or expected outputs. | 2 / 3 |
Progressive Disclosure | References to external files (references/, examples/, scripts/) are well-signaled with clear descriptions. However, no bundle files are provided, so these references are unverifiable. The SKILL.md itself is monolithic — the inline content is far too long and much of it (system prompt design patterns, complete validation rules, color guidelines) should be in the referenced files rather than inline. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
fcdcd07
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.