skill-authoring
Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.
82
78%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/core/src/methodology/packs/meta/skill-authoring/SKILL.mdQuality
Discovery
100%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 an excellent skill description that clearly defines what the skill does (creates SKILL.md files with specific structural components), when to use it (explicit trigger scenarios), and occupies a distinct niche unlikely to conflict with other skills. It uses proper third-person voice, is concise yet comprehensive, and includes natural trigger terms users would actually say.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Creates and structures SKILL.md files', 'YAML frontmatter', 'trigger phrases', 'directive instructions', 'decision trees', 'code examples', and 'verification checklists'. These are all concrete, specific deliverables. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates and structures SKILL.md files with specific components) and 'when' (explicit 'Use when...' clause listing five distinct trigger scenarios). Both halves are well-articulated. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'write a new skill', 'create a skill file', 'author agent capabilities', 'generate skill documentation', 'define a skill template', 'Claude Code agents', 'SKILL.md'. Good coverage of variations. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche — SKILL.md files for AI coding agents is a very specific domain. The triggers ('skill file', 'skill template', 'SKILL.md', 'agent capabilities') are unlikely to conflict with general documentation or coding skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a competent meta-skill for authoring SKILL.md files with good structural organization and appropriate progressive disclosure to external references. Its main weaknesses are the lack of a concrete end-to-end worked example (showing a complete skill being authored) and the absence of an explicit sequential workflow with validation checkpoints. Some content explains concepts Claude already understands (tone guidance, what semantic versioning means) which reduces token efficiency.
Suggestions
Add a complete end-to-end worked example showing a real SKILL.md being authored from frontmatter to final content, demonstrating all the patterns described in the guide.
Restructure the authoring process as an explicit numbered workflow with validation checkpoints (e.g., 'Step 1: Draft frontmatter → Validate fields against constraints → Step 2: Write body → Verify against checklist → Step 3: Test triggers').
Remove or significantly compress the voice/tone section and basic explanations (e.g., what semantic versioning is) since Claude already knows these concepts — a single line like 'Use second person, present tense, active voice' suffices without the ✅/❌ examples.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-organized but includes some unnecessary explanations that Claude already knows (e.g., voice and tone guidance like 'use second person, present tense, active voice' with examples, explaining what semantic versioning is). The anti-patterns table and some structural advice could be tightened. However, much of the content is domain-specific enough to justify its inclusion. | 2 / 3 |
Actionability | The skill provides structural templates and examples (decision trees, process steps, code examples), but they are mostly meta-templates rather than executable, copy-paste-ready content. The frontmatter table and trigger examples are concrete, but the actual skill-authoring process lacks a specific end-to-end worked example showing a complete SKILL.md being authored from scratch. | 2 / 3 |
Workflow Clarity | The skill presents a clear anatomy/structure and includes publication and testing checklists, but the actual authoring workflow is not sequenced as explicit steps with validation checkpoints. There's no 'Step 1: Create frontmatter → Step 2: Write body → Step 3: Validate' flow with feedback loops. The testing section lists what to verify but doesn't integrate into a sequential process. | 2 / 3 |
Progressive Disclosure | The skill appropriately references external files (PACKS.md for pack organization, MAINTENANCE.md for versioning policy) with clear one-level-deep signaling. The main content stays focused on the overview and core authoring guidance while deferring detailed topics to separate documents. Sections are well-organized with clear headers for navigation. | 3 / 3 |
Total | 9 / 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
- rohitg00/skillkit
- Commit
a9e5c83
- 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.