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.