skill-authoring
Use when authoring, creating, refining, or troubleshooting agent skills — covers SKILL.md structure, frontmatter syntax, description optimization, and activation testing. Also when building a new skill from scratch, when a skill won't trigger, loads incorrectly, or the agent ignores it entirely. Use when a skill misbehaved in the current session and needs adjustment based on learnings.
72
87%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Failed to scan
The risk profile of this skill
Quality
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 strong description that excels at completeness and distinctiveness, with excellent 'Use when' guidance covering multiple trigger scenarios. The trigger terms are natural and varied, covering both creation and debugging use cases. The main weakness is that the specific capabilities could be more concretely enumerated — it leans slightly toward describing scenarios rather than listing discrete actions the skill performs.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (agent skills / SKILL.md) and mentions some actions like 'authoring, creating, refining, troubleshooting' and touches on specific areas like 'frontmatter syntax, description optimization, activation testing,' but doesn't list multiple concrete discrete actions (e.g., 'generate frontmatter YAML, write trigger descriptions, debug activation rules'). | 2 / 3 |
Completeness | The description clearly answers both 'what' (covers SKILL.md structure, frontmatter syntax, description optimization, activation testing) and 'when' with explicit 'Use when...' clauses covering multiple trigger scenarios (authoring, troubleshooting, skill not triggering, skill misbehaving). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would actually say: 'skill won't trigger,' 'loads incorrectly,' 'agent ignores it,' 'building a new skill from scratch,' 'SKILL.md,' 'frontmatter syntax,' 'description optimization,' and 'skill misbehaved.' These cover a wide range of natural phrasings a user might employ. | 3 / 3 |
Distinctiveness Conflict Risk | This skill occupies a very clear niche — meta-skill authoring for agent skills/SKILL.md files. The triggers are highly specific to skill creation and debugging, making it unlikely to conflict with other skills that handle general coding, documentation, or other tasks. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong meta-skill that effectively serves as a router for skill authoring tasks. Its greatest strengths are the clear job-routing table, concrete tooling commands, and excellent progressive disclosure structure. The main weakness is moderate verbosity — some sections could be tightened without losing clarity, particularly the Cardinal Rules table and the Progressive Disclosure section which partially restates the skill's own structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-structured and avoids explaining basic concepts, but some sections are somewhat verbose for what they convey. The 'Writing SKILL.md Bodies' and 'Progressive Disclosure' sections repeat ideas already implied by the structure. The Cardinal Rules table is useful but lengthy. Overall mostly efficient with some room to tighten. | 2 / 3 |
Actionability | Provides concrete, executable commands (init.py, validate.sh, skills-ref validate), specific YAML templates for descriptions with good/bad examples, a clear directory structure, and a formula for writing descriptions. The job-routing table gives specific file paths to follow. The guidance is copy-paste ready and specific. | 3 / 3 |
Workflow Clarity | The job-selection table provides clear routing to specific workflows. The Fast Path section gives a concise 4-step sequence for simple edits. The 'Writing SKILL.md Bodies' section provides a clear 5-step shape (Choose, Do, Show, Guard, Check) with validation as the final step. The 'Report Back' section defines expected outputs. Multi-step processes are delegated to workflow files, which is appropriate for a router skill. | 3 / 3 |
Progressive Disclosure | Excellent progressive disclosure structure. The SKILL.md serves as a clear router/overview, with well-signaled one-level-deep references to workflows/, references/, templates/, scripts/, and spec/. The job table makes navigation intuitive with 'read first' and 'then use when needed' columns. Content is appropriately split between the overview and referenced files. | 3 / 3 |
Total | 11 / 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.
- Repository
- joshuadavidthomas/agent-skills
- Commit
40067f1
- 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.