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

92%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Failed to scan

The risk profile of this skill

Quality

Content

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 for skill authoring that practices what it preaches regarding progressive disclosure and actionability. It effectively routes to sub-workflows via a clear job-selection table, provides concrete tooling commands, and includes specific examples for description writing. The main weakness is moderate verbosity — some sections could be tightened given that the target audience is an LLM agent that already understands concepts like progressive disclosure and directory structure conventions.

Suggestions

Tighten the Cardinal Rules table by removing entries that are self-evident to an LLM agent (e.g., 'Critical instructions appear early', 'Precision before addition') or consolidate them into fewer, higher-impact rules to improve conciseness.

Dimension	Reasoning	Score
Conciseness	The skill is generally well-structured and avoids explaining basic concepts, but it's somewhat lengthy for a routing/meta skill. Some sections like 'Progressive Disclosure' and 'Writing SKILL.md Bodies' contain guidance that could be more tightly compressed or deferred to reference files. The Cardinal Rules table is useful but a few entries border on obvious advice for an LLM agent.	2 / 3
Actionability	The skill provides concrete, executable commands (scaffold scripts, validation scripts), specific YAML examples for good/bad descriptions, a clear formula for writing descriptions, and a structured body-writing pattern (Choose/Do/Show/Guard/Check). The tooling section has copy-paste ready commands.	3 / 3
Workflow Clarity	The job-selection table provides clear routing to specific workflows with explicit 'read first' and 'then use when needed' columns. The Fast Path section gives a clear 4-step sequence for simple edits. The body-writing shape (Choose/Do/Show/Guard/Check) includes a validation checkpoint. The 'Done means...' definition at the top sets clear success criteria.	3 / 3
Progressive Disclosure	Excellent progressive disclosure structure: the SKILL.md serves as a clear router to workflow files (create, synthesize, test, debug, refine), reference files (rules, examples, patterns), templates, and specs. All references are one level deep and clearly signaled with specific 'when to use' context in the job table. The layered loading model (name/description → body → references) is explicitly documented.	3 / 3
	Total	11 / 12 Passed

Description

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 a strong description that clearly defines a meta-skill for authoring and troubleshooting agent skills. It excels at listing concrete actions, providing multiple explicit trigger scenarios covering both creation and debugging use cases, and occupying a distinct niche that is unlikely to conflict with other skills. The only minor weakness is that it's somewhat verbose and could be slightly more concise, but the detail serves the purpose of comprehensive trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: scaffold SKILL.md and frontmatter, write and optimize trigger description, structure body with progressive disclosure, validate structure, test or debug activation. These are clearly defined, actionable capabilities.	3 / 3
Completeness	Clearly answers both 'what' (scaffold SKILL.md, write trigger descriptions, validate structure, debug activation) and 'when' with multiple explicit trigger clauses: 'Use when authoring...', 'Also when building a new skill from scratch', 'when a skill won't trigger', 'when a skill misbehaved'. The description opens with 'Use when' and provides additional trigger scenarios.	3 / 3
Trigger Term Quality	Includes strong natural trigger terms users would say: 'agent skills', 'SKILL.md', 'frontmatter', 'trigger description', 'skill won't trigger', 'loads incorrectly', 'agent ignores it', 'building a new skill', 'misbehaved'. Good coverage of both creation and troubleshooting scenarios.	3 / 3
Distinctiveness Conflict Risk	Occupies a very clear niche — meta-skill authoring for agent skills specifically. Terms like 'SKILL.md', 'frontmatter', 'trigger description', 'skill won't trigger' are highly distinctive and unlikely to conflict with other skills that perform domain-specific tasks.	3 / 3
	Total	12 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: joshuadavidthomas/agent-skills
Commit: d20109a

Reviewed: 4 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.