creating-skill-pro

Define a directory containing a SKILL.md file with YAML frontmatter holding a name and description, then add routing instructions in the body. The init_skill.py script generates a minimal or workflow template skeleton with optional references, scripts, assets, and evals directories.

Build an eval set with prompts and verifiable expectations, then run with-skill versus without-skill configurations across multiple runs. The aggregate_benchmark.py script computes pass rates, timing, and token deltas into benchmark.json and a Markdown summary.

Trigger failures usually come from descriptions that describe implementation instead of user intent and timing. Create should-trigger and should-not-trigger query sets, run trigger evaluations, then iteratively rewrite the description using the improvement loop with a held-out test set.

A good description states what the skill does, when it must be used, and how users commonly phrase the request, staying under 1024 characters. It should prioritize user intent and trigger timing over technical implementation vocabulary.

No, the scripts use neutral interfaces and accept an injected optimizer or runner command rather than binding to a specific vendor CLI. If automated execution is unavailable, the workflow degrades to a semi-manual mode saving inputs, outputs, and human judgments.

Move long examples, schemas, and domain knowledge into references/ when they are only needed on demand, and move repetitive, error-prone, deterministic logic into scripts/. The top-level SKILL.md should stay under roughly 500 lines and only hold philosophy, judgment frameworks, and routing.