writing-agents
Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool
76
63%
Does it follow best practices?
Impact
97%
1.14xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/writing-agents/SKILL.mdQuality
Discovery
50%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 provides reasonable trigger guidance with a 'Use when...' clause but lacks a concrete 'what does this do' section describing specific capabilities. It names the domain adequately but misses natural keyword variations and specific actions that would help Claude confidently select this skill over others.
Suggestions
Add an explicit 'what' clause before the 'Use when' that lists specific capabilities, e.g., 'Defines agent configurations including system prompts, tool permissions, and handoff logic for the Task tool.'
Expand trigger terms to include natural variations users might say, such as 'multi-agent', 'orchestration', 'delegation', 'sub-agent', 'agent setup', or 'agent workflow'.
Add more specificity about what distinguishes this from general agent-related skills, e.g., mention specific file formats, configuration patterns, or the Task tool's unique features.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (agents/subagents) and some actions (creating, editing, defining roles), but doesn't list specific concrete capabilities like 'configure tool permissions, set system prompts, define handoff conditions'. | 2 / 3 |
Completeness | The description is essentially only a 'Use when...' clause with implicit 'what' (creating/editing agents). It lacks an explicit 'what does this do' section describing the skill's capabilities before the trigger guidance. | 2 / 3 |
Trigger Term Quality | Includes relevant terms like 'agents', 'subagent', and 'Task tool', but misses common user variations such as 'multi-agent', 'orchestration', 'delegation', 'sub-agent', 'agent configuration', or 'agent definition'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Task tool' and 'subagent roles' provides some specificity, but 'creating new agents' and 'editing existing agents' could overlap with general agent/workflow configuration skills. The niche is somewhat clear but not sharply defined. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and highly actionable skill for writing agents, with excellent workflow clarity including a full RED-GREEN-REFACTOR cycle and detailed checklists. Its main weakness is length — at 300+ lines it could benefit from splitting detailed examples and patterns into separate reference files, and some content is repeated (anti-patterns appear both in the anatomy section and the dedicated anti-patterns section). The concrete examples, good/bad comparisons, and specific tool invocations make it very practical despite the verbosity.
Suggestions
Extract the 'Common Agent Patterns' section (Specialist, Orchestrator, Reviewer) into a separate AGENT-PATTERNS.md reference file to reduce the main skill's length
Remove the 'Anti-Patterns to Avoid' section near the end since the same examples already appear inline in the 'Anatomy of an Effective Agent' section — or consolidate into one location
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is quite lengthy (~300+ lines) with some redundancy. The comparison table (Agents vs Skills) and model selection table are useful, but sections like 'The Bottom Line' repeat what's already been said. The anti-patterns section at the end duplicates examples shown earlier in the anatomy section. Some trimming would improve token efficiency. | 2 / 3 |
Actionability | Highly actionable with concrete file structures, YAML frontmatter examples, specific bash commands, good/bad persona comparisons, exact directory paths, and copy-paste ready agent templates. The workflow steps include specific tool invocations (Glob, Grep, WebSearch) and example search queries. | 3 / 3 |
Workflow Clarity | The agent creation workflow is clearly sequenced (Research → Context → Write → Session Restart) with explicit steps within each phase. The RED-GREEN-REFACTOR testing cycle is well-defined with specific actions at each stage. The comprehensive checklist at the end serves as a validation checkpoint covering all phases. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and sections, but it's monolithic — everything is in one long file with no references to external files for detailed content. The common agent patterns section and the full anatomy section could be split into separate reference files. The references at the end link externally but there's no internal file decomposition. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- aaddrick/claude-desktop-debian
- Commit
814cd52
- Reviewed
Table of Contents
Is this your skill?
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.