Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
84
80%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/productivity/write-a-skill/SKILL.mdQuality
Discovery
89%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 solid description that clearly communicates both what the skill does and when to use it, with good trigger terms. Its main weakness is that the 'what' portion uses somewhat abstract concepts ('proper structure', 'progressive disclosure', 'bundled resources') rather than listing concrete actions. Overall it performs well for skill selection purposes.
Suggestions
Replace abstract terms like 'proper structure' and 'progressive disclosure' with more concrete actions, e.g., 'Generate YAML frontmatter, write step-by-step instructions, and bundle example resources into skill markdown files.'
| 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 observable actions like 'generate YAML frontmatter' or 'create markdown files with examples'. | 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. | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would say: 'create', 'write', 'build', 'new skill'. These are common verbs a user would naturally use when requesting skill creation. The term 'agent skills' is also specific and relevant. | 3 / 3 |
Distinctiveness Conflict Risk | The description targets a very specific niche—creating agent skills—which is unlikely to conflict with other skills. The combination of 'agent skills', 'progressive disclosure', and 'bundled resources' makes this clearly distinguishable. | 3 / 3 |
Total | 11 / 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 solid meta-skill for creating new skills, with excellent workflow clarity and progressive disclosure. Its main weaknesses are moderate verbosity in the description requirements section and the use of placeholder text in the template rather than a fully concrete, filled-in example. The review checklist is a strong validation mechanism.
Suggestions
Replace placeholder text in the SKILL.md template (e.g., '[Minimal working example]') with a concrete, filled-in example of a simple skill to make the template fully actionable.
Tighten the 'Description Requirements' section by removing the explanation of how the agent uses descriptions internally—just state the format rules and show the 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 is somewhat verbose. The 'Good example' vs 'Bad example' comparison for descriptions is helpful but could be tighter. The 'When to Add Scripts' and 'When to Split Files' sections are lean and well-done. | 2 / 3 |
Actionability | Provides a clear template and directory structure, which is concrete and useful. However, the SKILL.md template contains placeholder text like '[Minimal working example]' and '[Step-by-step processes with checklists]' rather than filled-in executable examples. The process steps are more of a conversational workflow than copy-paste-ready instructions. | 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 provides an explicit validation checkpoint. For a skill-creation workflow, this level of structure is appropriate and includes feedback loops (review with user, verify against checklist). | 3 / 3 |
Progressive Disclosure | The skill is well-organized with clear sections that progress from process to structure to template to specific guidance topics. The template itself demonstrates progressive disclosure by showing how to reference REFERENCE.md. Content is appropriately split into logical sections without being monolithic, and no bundle files are needed for this self-contained meta-skill. | 3 / 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.
733d312
Table of Contents
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.