Skill · skill

Skill skill provides a fast path from real work to a reusable skill whose instructions change observable behavior. Its standard is whether a decision changes, an artifact gets created, or a mistake gets caught. Each paragraph must affect what the assistant does; inactive detail moves into a reference explicitly used by a workflow step or is removed.

The process starts with conversation history or notes. Extract the user's corrections and rejections, the outputs they accepted and the mechanism that worked, repeated manual tasks, and research facts that influence decisions. Corrections become rules with reasons or checks. Work performed manually twice becomes a candidate script. Verified research stays distinct from unverified information, and unverified numbers do not become rules.

Use it when creating, rewriting, or renaming a skill, turning a conversation or methodology into one, or auditing a skill that does not affect results. It focuses on a short creation and effect-testing loop. Heavy benchmarking, repeated evaluations, variance analysis, and description-optimization loops belong to the separate skill-creator workflow.

A static health score checks structure rather than instruction correctness. A quick effect comparison is also distinct from a benchmark. Neither result alone proves that a skill reliably improves every task.

Convert knowledge into increasingly explicit mechanisms: required artifacts read by later steps, gates before dependent work, deterministic scripts, checklists at named moments, templates or examples, and references with a defined reading point and expected output. Explain the reason for a rule briefly. For taste-sensitive work, include a bad-to-good example rather than relying on adjectives.

The skill folder contains SKILL.md for frontmatter and ordered steps, scripts for deterministic operations, references for selectively loaded detail, and assets copied into outputs. Names are short, lowercase-hyphenated, and match the folder. Check collisions with installed skills and familiar tools before choosing or changing one. The description stays within 1024 characters, states what the skill does, and includes use triggers in the user's actual phrasing and languages. The body aims below roughly 500 lines, with each numbered step ending in an artifact, decision, or check.

Static inspection checks name agreement, trigger wording, description length, collisions, orphan files, missing paths, oversized bodies, excessive capitals, and steps without outputs. The upstream helper documents this command:

python3 <this skill's base directory>/scripts/skill_audit.py <skill_dir>     # or --all; --badge prints a README badge

This entry bundles documentation and license only. The audit and report scripts are absent: inspect the structure directly with read-only tools, or obtain consent before fetching and inspecting the pinned upstream scripts. Do not treat the command as evidence that a bundled helper exists.

For the effect test, write two or three realistic prompts and three observable effects for each. Run a fresh pass with the skill and, when needed, without it. Effects appearing in both are not attributable to the skill. Missing effects call for stronger artifacts or gates rather than more passive prose.

Keep new acceptance and rejection lessons in lessons.md, promote recurring lessons to checks, rerun the audit after edits, and show a diff summary. Prune instructions that never affect the test and update referenced paths when renaming.