writing-agents

Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

Quality

56%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/writing-agents/SKILL.md

Quality

Content

62%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is highly actionable with excellent workflow clarity, providing concrete templates, examples, and a comprehensive checklist for agent creation. However, it is significantly over-long and repetitive—the same concepts (anti-patterns, personas, scope boundaries) are illustrated multiple times across different sections. The content would benefit greatly from aggressive trimming and splitting detailed reference material into separate files.

Suggestions

Cut content by ~40%: remove the duplicate anti-patterns section (keep either the 'Anatomy' examples or the 'Anti-Patterns to Avoid' section, not both), trim the Common Agent Patterns to just names and one-line descriptions, and remove the model selection table (Claude knows model capabilities).

Move the detailed 'Common Agent Patterns' templates and the 'Agent Creation Checklist' into separate reference files (e.g., AGENT_PATTERNS.md, AGENT_CHECKLIST.md) and link to them from the main skill.

Remove explanatory text Claude already knows, such as 'The persona is the agent's DNA' and 'A well-defined persona produces consistent behavior across interactions'—just show the good/bad examples directly.

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 extensive example searches Claude could generate itself, and repeats the same points multiple times (e.g., anti-patterns examples appear in both the 'Anatomy' section and the 'Anti-Patterns to Avoid' section). The comparison table, model selection table, and multiple pattern templates add significant bulk that could be condensed.	1 / 3
Actionability	The skill provides concrete, executable guidance throughout: specific file structures, exact YAML frontmatter format, copy-paste ready agent templates, specific bash commands for exploration, and clear examples of good vs bad patterns. The workflow steps are specific and actionable with real commands and file paths.	3 / 3
Workflow Clarity	The agent creation workflow is clearly sequenced (Research → Context → Write → Restart) with explicit steps within each phase. The RED-GREEN-REFACTOR testing cycle is well-defined with specific actions at each stage. The checklist at the end provides comprehensive validation checkpoints, and the session restart requirement is clearly called out as a critical step.	3 / 3
Progressive Disclosure	The skill references prerequisite skills (test-driven-development, writing-skills) and external URLs, but all content is monolithically inline. The common agent patterns, detailed examples, and the extensive checklist could be split into separate reference files. For a 350+ line skill, the lack of any content delegation to supporting files is a missed opportunity.	2 / 3
	Total	9 / 12 Passed

Description

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' trigger but lacks explicit detail about what the skill actually does (concrete outputs, specific configurations, or formats). It relies on somewhat domain-specific terminology ('Task tool') without covering natural user language variations, and the what/when distinction is blurred since the entire description is a single 'Use when' clause.

Suggestions

Add an explicit 'what it does' clause before the 'Use when' trigger, e.g., 'Generates agent definitions, system prompts, and tool configurations for multi-agent workflows.'

Include more natural trigger terms users might say, such as 'multi-agent', 'orchestration', 'delegate tasks', 'worker agent', 'agent prompt', or 'agent setup'.

List specific concrete actions the skill performs, such as 'define system prompts, configure tool access, set up handoff logic, specify agent responsibilities'.

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 answering the 'when' question, but the 'what does this do' part is weak — it only implies the skill helps with agent creation/editing without explicitly stating what it produces or how it helps. The what and when are conflated rather than clearly separated.	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 that users may not naturally use.	2 / 3
Distinctiveness Conflict Risk	The mention of 'Task tool' and 'subagent roles' provides some specificity, but 'agents' is a broad term that could overlap with other agent-related skills. The description doesn't clearly carve out a unique niche beyond general agent management.	2 / 3
	Total	8 / 12 Passed

Validation

100%

Warnings & errors only

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: 2d1d0c5

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.