Our review

Walks the agent through authoring and validating skills: frontmatter, a lean main file, progressive disclosure through reference files, and skillgrade evaluations.

Strengths

Clean five-step procedure running from metadata validation to a hallucination-gap review
Explicitly pushes dense rules, large schemas and templates out into references/ and assets/
Puts guardrails on inline shell snapshots: keep output short, declare read-only allowed-tools
Treats validation as deterministic graders first, LLM rubrics only when judgment is truly needed

Limitations

Assumes prior knowledge of the SKILL.md format, allowed-tools and skillgrade, none of which are explained
Ships no templates or worked examples of frontmatter, references, or an eval
Inline-command guidance stays generic and needs manual adaptation to a real repository

When to use it

Reach for it when creating a new skill directory or tightening the metadata, structure, and evals of an existing skill.

When not to use it

Skip it for ordinary app documentation, generic README edits, or library code unrelated to agent skills.

Examples

New skill from scratch

Create a new skill directory called 'pr-review' that reviews pull request diffs and flags risky changes. Write the SKILL.md frontmatter with a tight description and clear negative triggers, then keep the body to a high-level workflow.

Tighten metadata

My 'sql-migration' skill never gets picked up by the router. Review its description, make the triggers more specific, and add negative triggers so it stops firing on unrelated database questions.

Split and validate

This SKILL.md is 400 lines and half of it is a big JSON schema plus templates. Move the dense parts into references/ and assets/, point the agent at them with progressive disclosure, and add a skillgrade eval with a deterministic structural check.

name: skill-creator description: Guides the agent through authoring and validating agent skills. Use when creating new skill directories, tightening skill metadata, extracting supporting references, or preparing skillgrade evals. Do not use for general app documentation, generic README editing, or non-agentic library code.

Skill Authoring Procedure

Create professional-grade skills with lean context, deterministic structure, and validation.

When to Use This Skill

User wants to create a new skill directory
User wants to improve a skill's discoverability or metadata
User wants to split large instructions into references or scripts
User wants to add or update skillgrade validation

Procedures

Step 1: Validate the Skill Metadata

Check that the frontmatter uses a unique lowercase name, a specific description, and clear negative triggers.

Keep the description short enough to fit within the agent router's metadata budget.

Step 2: Keep the Main Skill Lean

Write the main SKILL.md as a high-level workflow.

Move dense rules, large schemas, and reusable templates into references/ or assets/.

Use scripts/ only for fragile or repetitive logic that should not be re-authored by the agent.

Step 3: Use Progressive Disclosure

Command the agent to read supporting files only when the current step needs them.

Prefer one-level-deep support files with explicit relative paths.

When a skill depends on repository state that will differ at invocation time, prefer a guarded inline shell snapshot such as !`node -e "..."` instead of baking the current state into prose.

Only do this when the command materially improves the invoked prompt, and keep the output short and deterministic.

If a skill uses inline commands, declare the minimum required allowed-tools entries in frontmatter and keep them read-only.

Step 4: Add Validation

Create a skillgrade eval when the skill needs regression testing.

Use a deterministic grader for structural checks and an LLM rubric only when qualitative judgment is necessary.

Step 5: Review for Hallucination Gaps

Inspect the skill for any step where the agent is forced to guess.

Replace ambiguous prose with concrete commands, file names, or output expectations.

Error Handling

If a skill cannot be validated, reduce scope until the missing behavior becomes testable.
If the description is too broad, tighten the trigger text before adding more instructions.
If the supporting material grows too large, extract it into a separate file and point the agent to it explicitly.
If an inline command would require broad shell access or produce noisy output, keep the skill static and tell the agent to inspect the files explicitly instead.

Skill Authoring and Validation

Recommended for