skill-creation-guide
Guide the user through creating a new Claude Code skill — SKILL.md format, frontmatter, progressive disclosure, when to use reference files, common pitfalls.
45
47%
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 ./plugins/glean-skills/skills/skill-creation-guide/SKILL.mdQuality
Discovery
57%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 identifies a clear and distinctive niche (creating Claude Code skills) and lists relevant subtopics, but lacks an explicit 'Use when...' clause and could be more specific about concrete actions performed. The trigger terms are adequate but miss common user phrasings.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to create, write, or set up a new SKILL.md file, or asks about skill file format, structure, or best practices.'
Include more natural trigger term variations such as 'create a skill', 'write a skill file', 'skill template', 'new skill', 'skill authoring'.
Rephrase topic areas as concrete actions, e.g., 'Generates SKILL.md files with proper frontmatter, structures content using progressive disclosure, identifies when to use reference files, and warns about common pitfalls.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (creating Claude Code skills) and lists several aspects covered (SKILL.md format, frontmatter, progressive disclosure, reference files, common pitfalls), but these read more like topic areas than concrete actions the skill performs. | 2 / 3 |
Completeness | The 'what' is reasonably covered (guide through creating a new Claude Code skill with specific topics), but there is no explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes relevant terms like 'SKILL.md', 'frontmatter', 'skill', and 'Claude Code' that users might mention, but misses common natural variations like 'create a skill', 'write a skill file', 'skill template', or 'how to make a skill'. | 2 / 3 |
Distinctiveness Conflict Risk | The description targets a very specific niche — creating Claude Code SKILL.md files — which is unlikely to conflict with other skills. The mention of SKILL.md format, frontmatter, and progressive disclosure makes it clearly distinguishable. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable overview of skill creation but suffers from a lack of clear workflow sequencing and validation steps. The 'BE SKEPTICAL' section, while valuable in concept, is overly verbose and dominates the skill. The actionable guidance is present but incomplete — it gives templates and principles without fully executable examples or a clear end-to-end creation workflow with checkpoints.
Suggestions
Add a clear numbered workflow for skill creation (e.g., 1. Evaluate need → 2. Draft frontmatter → 3. Write body → 4. Test trigger → 5. Validate output) with explicit validation checkpoints at each stage.
Replace the verbose 'BE SKEPTICAL' decision matrices with a compact checklist or decision table, or move it to a separate reference file.
Include a complete, copy-paste-ready example of a finished SKILL.md (not just the template skeleton) showing a real skill with frontmatter, triggers, workflow, and output format.
Add a validation/testing step explaining how to verify a skill works correctly after creation (e.g., 'Test by saying the trigger phrase and confirming the skill activates').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill contains some unnecessary explanations (e.g., 'What is a Skill?' section explains concepts Claude already knows, and the 'BE SKEPTICAL' section is quite verbose with its emoji-laden decision matrices). The structure is reasonable but could be tightened significantly. | 2 / 3 |
Actionability | The skill provides a SKILL.md template structure and some concrete guidance (file paths, command examples), but the actual skill creation process lacks executable, step-by-step instructions. The template is more of a skeleton than a copy-paste-ready example, and the 'Best Practices' section gives principles rather than concrete demonstrations with before/after examples. | 2 / 3 |
Workflow Clarity | There is no clear sequential workflow for creating a skill. The content jumps between evaluation criteria, structure templates, best practices, and file locations without a coherent step-by-step process. There are no validation checkpoints (e.g., 'test your skill by invoking it', 'verify the frontmatter parses correctly'). | 1 / 3 |
Progressive Disclosure | The content is organized into logical sections with headers, which is good. However, there are no references to external files for detailed content (e.g., an examples file, a reference for advanced patterns), and the 'BE SKEPTICAL' section is a large inline block that could be a separate reference. No bundle files are provided to support progressive disclosure. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- gleanwork/claude-plugins
- Commit
39a5c99
- 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.