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.