writing-agents
Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool
52
56%
Does it follow best practices?
Impact
—
No eval scenarios have been run
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 a reasonable 'when to use' clause but lacks a clear 'what it does' statement describing concrete capabilities. It uses relevant but incomplete trigger terms and would benefit from more specific action verbs and broader keyword coverage to help Claude distinguish it from other potentially similar skills.
Suggestions
Add an explicit 'what' clause before the 'Use when' that lists concrete actions, e.g., 'Defines agent configurations, system prompts, tool permissions, and handoff logic for multi-agent workflows.'
Expand trigger terms to include natural user phrases like 'multi-agent', 'orchestration', 'delegate tasks', 'worker agent', 'agent prompt', or 'agent setup'.
Clarify what 'Task tool' refers to or add context so the description is self-contained and distinguishable from other agent-related skills.
| 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 configuring prompts, setting tool permissions, defining handoff logic, etc. | 2 / 3 |
Completeness | The description is structured as a 'Use when...' clause addressing the 'when' question, but the 'what does this do' part is weak — it only implies capabilities through the trigger conditions rather than explicitly stating what the skill provides or produces. | 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', 'worker agent', or 'agent configuration'. 'Task tool' is somewhat technical jargon. | 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-related skills or configuration skills. The niche is somewhat clear but not sharply defined. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent actionable guidance with clear workflows and concrete examples for creating agents, but suffers significantly from verbosity. Many sections repeat concepts (good/bad examples appear in multiple places), generic patterns that Claude could generate are spelled out in full, and the overall length (~350+ lines) wastes context window. The content would benefit greatly from being split into a concise overview with references to detailed supporting files.
Suggestions
Cut content by ~50%: remove the Common Agent Patterns section (Specialist/Orchestrator/Reviewer templates are generic enough for Claude to generate), consolidate the duplicate good/bad examples between 'Anatomy of an Effective Agent' and 'Anti-Patterns to Avoid' sections, and trim the research query examples to 1-2 domains instead of 4.
Extract the detailed 'Anatomy of an Effective Agent' section and 'Common Agent Patterns' into a separate AGENT-REFERENCE.md file, keeping only a brief summary and link in the main skill.
Add explicit links to the referenced prerequisite skills (test-driven-development, writing-skills) rather than just naming them.
Remove the Agents vs Skills comparison table and model selection table — Claude already understands these distinctions from its training and system context.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~350+ lines. It over-explains concepts Claude already knows (TDD cycles, what personas are, what orchestrators do), includes lengthy comparison tables, and repeats patterns multiple times (e.g., good/bad examples for persona, scope, anti-patterns, and descriptions are shown in both the anatomy section AND the anti-patterns section). The agent patterns section (Specialist, Orchestrator, Reviewer) adds generic templates Claude could generate on its own. | 1 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: specific file paths (.claude/agents/), exact YAML frontmatter format, executable bash commands, complete example agent definitions, specific search queries to run, and a detailed checklist. The examples are copy-paste ready and the workflow steps are specific enough to follow directly. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced (Research → Context → Write → Session Restart) with explicit validation checkpoints via the RED-GREEN-REFACTOR testing cycle. The comprehensive checklist at the end serves as a verification step. The session restart requirement is clearly called out as a critical step with specific user messaging. | 3 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with no references to supporting files. Content like the Common Agent Patterns templates, the full anatomy examples, and the detailed research queries could be split into separate reference files. The skill references 'test-driven-development' and 'writing-skills' as prerequisites but doesn't link to them. For a skill this long, better splitting would significantly improve usability. | 2 / 3 |
Total | 9 / 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
76a5a21
- 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.