skill-best-practices

SKILL.md

Skill Authoring Procedure

Follow these steps to generate a skill that adheres to the agentskills.io specification and progressive disclosure principles.

Bundled Path Rule

Resolve bundled paths relative to the directory that contains this SKILL.md. When invoking a helper from another working directory, expand <skill-best-practices-dir> to that directory first so the command is unambiguous.

Step 1: Initialize and Validate Metadata

Define a unique name: 1-64 characters, lowercase, numbers, and single hyphens only.

Draft a description: Max 1,024 characters, written in the third person, including negative triggers.

Execute Validation Script (read-only helper): Run the validation script to ensure compliance before proceeding:
python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"

If the script returns an error, self-correct the metadata based on the stderr output and re-run until successful.