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

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.cursor/skills/write-a-skill/SKILL.md

Quality

Content

70%Scale 1-3

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

This is a solid meta-skill for creating new skills, with clear workflow, good structure, and a useful review checklist. Its main weaknesses are some verbosity in the description requirements section (explaining concepts Claude already understands) and the lack of a fully concrete, complete example of a finished skill rather than just a template skeleton. The actionability would benefit from a real worked example showing a complete SKILL.md from start to finish.

Suggestions

Add a complete, concrete example of a finished SKILL.md (not just a template with placeholders) to improve actionability—show a real skill with filled-in content.

Trim the 'Description Requirements' section—remove the explanation of how the agent uses descriptions internally and just provide the format rules and good/bad examples.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but includes some unnecessary explanation. The 'Description Requirements' section over-explains what a description is and how the agent uses it, which Claude already understands. The 'When to Add Scripts' and 'When to Split Files' sections are concise and useful. Some padding like 'The bad example gives your agent no way to distinguish this from other document skills' is unnecessary.	2 / 3
Actionability	Provides a concrete directory structure, a SKILL.md template, and checklists, which are useful. However, the template is a skeleton with placeholder comments rather than executable/filled-in examples. The process steps are more of a conversation guide than concrete executable actions. No actual complete example of a finished skill is provided.	2 / 3
Workflow Clarity	The three-step process (gather requirements → draft → review) is clearly sequenced. The review checklist at the end provides explicit validation checkpoints. The workflow is appropriate for the task—creating a skill is inherently a collaborative, iterative process, and the feedback loop (review with user, iterate) is well-defined.	3 / 3
Progressive Disclosure	Content is well-organized into distinct sections with clear headers. The skill itself teaches progressive disclosure and models it appropriately. Each section covers a distinct concern (structure, template, descriptions, scripts, splitting, review). No bundle files are needed for this meta-skill, and the content is appropriately sized for a single file.	3 / 3
	Total	10 / 12 Passed

Description

82%Scale 1-3

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 well-constructed description that clearly communicates both what the skill does and when to use it. Its main weakness is that the capability description uses somewhat abstract terms ('proper structure', 'progressive disclosure', 'bundled resources') rather than concrete actions, and the trigger terms, while natural, are broad enough to potentially conflict with other creation-focused skills.

Suggestions

Replace abstract terms like 'proper structure' and 'progressive disclosure' with more concrete actions, e.g., 'generate YAML frontmatter, create markdown skill files, organize skill sections'.

Add more specific trigger terms to reduce conflict risk, e.g., 'SKILL.md, skill file, .md skill template, agent capability'.

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 terms 'proper structure', 'progressive disclosure', and 'bundled resources' are somewhat abstract rather than concrete actions 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' (explicit 'Use when user wants to create, write, or build a new skill' clause).	3 / 3
Trigger Term Quality	Includes natural trigger terms users would say: 'create', 'write', 'build', 'new skill'. These are common, natural phrases a user would use when requesting this capability.	3 / 3
Distinctiveness Conflict Risk	The term 'skill' is fairly specific to this domain, but 'create', 'write', and 'build' are very broad verbs that could overlap with other creation-oriented skills. The phrase 'agent skills' helps narrow it, but there's still some risk of triggering when users want to create other types of content.	2 / 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: SnowingFox/ai-skills
Path: .cursor/skills/write-a-skill/SKILL.md
Commit: d6882ad

Reviewed: ~13 hours 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.