skill-authoring

Use when authoring, creating, refining, or troubleshooting agent skills — scaffold SKILL.md and frontmatter, write and optimize the trigger description, structure the body with progressive disclosure, validate structure, and test or debug activation. 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.

Quality

96%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Failed to scan

The risk profile of this skill

Quality

Content

92%Weight 40%Scale 1-3

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

A lean, table-driven meta-skill body with concrete commands, a clear fast-path workflow, and well-signaled progressive disclosure in intent. Its main defect is that the majority of referenced bundle files are missing, so the disclosure structure does not actually resolve.

Suggestions

Create the referenced workflow files (workflows/create.md, synthesize.md, test.md, debug.md, refine.md) or remove their links from the Choose the Job table so no routing target is dead.

Add the missing templates/ (simple.md, router.md), spec/specification.md, README.md, and sources/ entries, or prune the references to match the shipped bundle.

Verify every relative path in the body resolves under the skill directory before validating, since validate.sh only checks structure and will not catch dangling cross-file links.

Dimension	Reasoning	Score
Conciseness	The body is table-driven and assumes Claude's competence — it does not explain what skills or frontmatter are; framing lines like 'Done means the skill loads for the right requests...' carry signal. Minor redundancy between Cardinal Rules and Description Requirements is acceptable for a meta-skill quick-reference.	3 / 3
Actionability	Provides copy-paste-ready commands backed by real scripts ('python scripts/init.py my-skill', './scripts/validate.sh path/to/skill', 'skills-ref validate'), a concrete description formula template, and a Choose/Do/Show/Guard/Check body shape — executable and specific.	3 / 3
Workflow Clarity	The Fast Path gives a clear 4-step sequence with an explicit validation checkpoint ('Validate structure and, when relevant, activation behavior'), and Report Back defines a reporting sequence; validation is emphasized throughout including 'Test activation before deployment'.	3 / 3
Progressive Disclosure	Structure is well-designed — a router table signals one-level-deep 'read first' vs 'use when needed' references — but scored against the actual bundle, most routing targets (workflows/create.md, synthesize.md, test.md, debug.md, refine.md, templates/*, spec/specification.md, README.md, sources/) do not exist, so navigation breaks for 5 of 7 jobs.	2 / 3
	Total	11 / 12 Passed

Description

100%Weight 40%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.

A strong, third-person description with explicit triggers, concrete capabilities, and good natural-keyword coverage. It is somewhat long and restates triggers multiple times, but every clause adds real signal rather than fluff.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'scaffold SKILL.md and frontmatter, write and optimize the trigger description, structure the body with progressive disclosure, validate structure, and test or debug activation' — matching the multi-action anchor.	3 / 3
Completeness	Explicitly answers both what (scaffold/description/body/validate/test) and when via repeated 'Use when...' / 'Also when...' trigger clauses, satisfying the both-what-and-when anchor.	3 / 3
Trigger Term Quality	Covers natural user phrasings across the skill's range: 'authoring, creating, refining, or troubleshooting agent skills', 'a skill won't trigger', 'loads incorrectly', 'the agent ignores it entirely', and 'a skill misbehaved'.	3 / 3
Distinctiveness Conflict Risk	Occupies a clear niche (agent skill authoring) with distinct triggers unlikely to fire for unrelated skills; no overlap risk with generic document or code skills.	3 / 3
	Total	12 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 14 missing	Warning

	Total	15 / 16 Passed

Repository: joshuadavidthomas/agent-skills
Path: skill-authoring/SKILL.md
Commit: 516dee7

Reviewed: 11 days 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.