write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

Quality

72%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./write-a-skill/SKILL.md

Quality

Discovery

75%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a reasonably good description that clearly communicates both what the skill does and when to use it, with a distinct niche. Its main weaknesses are moderate specificity—the capabilities described are somewhat abstract rather than listing concrete actions—and trigger term coverage that could be broader to capture more natural user phrasings.

Suggestions

Add more concrete actions to improve specificity, e.g., 'Generates YAML frontmatter, creates markdown skill files, organizes bundled resources' instead of abstract terms like 'proper structure'.

Expand trigger terms in the 'Use when' clause to include variations like 'add a skill', 'skill template', 'SKILL.md', or 'define a new tool'.

Dimension	Reasoning	Score
Specificity	Names the domain (agent skills) and some actions ('create new agent skills with proper structure, progressive disclosure, and bundled resources'), but the actions are somewhat abstract—'proper structure' and 'progressive disclosure' are concepts rather than concrete operations like 'generate YAML frontmatter' or 'create markdown templates'.	2 / 3
Completeness	Clearly answers both 'what' (create new agent skills with proper structure, progressive disclosure, and bundled resources) and 'when' (Use when user wants to create, write, or build a new skill) with an explicit 'Use when' clause and trigger terms.	3 / 3
Trigger Term Quality	Includes natural terms like 'create', 'write', 'build', and 'new skill', which users would likely say. However, it misses variations like 'add a skill', 'make a skill', 'skill template', 'SKILL.md', or 'skill file', reducing coverage of natural trigger terms.	2 / 3
Distinctiveness Conflict Risk	The concept of 'agent skills' with 'progressive disclosure' and 'bundled resources' is a very specific niche that is unlikely to conflict with other skills. The trigger terms are narrowly scoped to skill creation specifically.	3 / 3
	Total	10 / 12 Passed

Implementation

70%

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

This is a reasonably well-structured meta-skill for creating new skills. Its strengths are clear workflow sequencing, a useful review checklist, and good progressive disclosure. Its weaknesses are moderate verbosity in the description requirements section and a template that uses placeholders rather than a fully fleshed-out concrete example, reducing actionability.

Suggestions

Replace the SKILL.md template placeholders (e.g., '[Minimal working example]') with a complete, filled-in example skill to make the template truly copy-paste actionable.

Trim the 'Description Requirements' section—remove the explanation of how agents read descriptions and keep just the format rules, good example, and bad example.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but includes some unnecessary explanation, particularly the 'Description Requirements' section which over-explains concepts Claude already understands (what a description is, how agents read them). The good/bad example contrast is helpful but the surrounding explanation is verbose.	2 / 3
Actionability	Provides a concrete directory structure, a SKILL.md template, and a review checklist, which are useful. However, the template is skeletal with placeholder comments rather than executable/filled-in content, and the process steps are more of a conversational workflow than concrete commands or copy-paste-ready artifacts.	2 / 3
Workflow Clarity	The three-step process (gather requirements → draft → review) is clearly sequenced with specific sub-items at each stage. The review checklist at the end serves as an explicit validation checkpoint. For this type of skill (creating documents, not destructive operations), this level of workflow clarity is appropriate.	3 / 3
Progressive Disclosure	The skill is well-organized with clear sections that progress from process to structure to template to specific guidance topics. It's under 100 lines, appropriately self-contained, and the template itself demonstrates progressive disclosure by showing how to reference separate files like REFERENCE.md and EXAMPLES.md.	3 / 3
	Total	10 / 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: mattpocock/skills
Commit: 651eab0

Reviewed: 9 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.