Write A Skill

Write A Skill

The meta-skill for building skill packages. It turns standards/skill-authoring-standard.md from a document you agree with into a gate you can run: scaffold the package, write a description that actually activates, place content in the right file, and lint against all 11 patterns before anyone reviews it. Most rejected skills fail on two things — a description nothing matches, and a SKILL.md carrying content that belonged in references/.

When to use this skill

• Creating a new skill from a one-line idea and needing the package structure right the first time
• Reviewing a skill PR and wanting a mechanical pass before spending attention on judgement
• Fixing a skill that never activates despite being well written — almost always a description problem
• Splitting an oversized SKILL.md that has crept past 500 lines
• Auditing a whole domain for description collisions after adding several neighbouring skills
• Onboarding a new author who needs the standard operationalised rather than explained

Inputs the skill expects

• The skill's one-sentence purpose and the domain directory it belongs in
• The three to five user sentences that should activate it (these become the description)
• Which existing skills sit closest to it in trigger space
• Whether it emits a deliverable (drives the Pattern 11 Clarify First gate) or only advises
• The analysis each script will perform, and the sample input each will run against
• Any deep knowledge that will exceed the SKILL.md budget and belongs in references/

Under Pattern 9 this skill is self-contained except for one permitted outbound reference: standards/skill-authoring-standard.md. Standards apply library-wide, so citing them does not create a cross-skill dependency. Nothing here may point at another skill's files.

Clarify First

Before scaffolding, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Trigger sentences — the literal phrases a user would type; they set the description, which decides whether the skill ever activates
• Nearest existing skills — determines whether this should be a new package or an extension of one that already owns the trigger space
• Generative or advisory — generative skills require the Clarify First gate; advisory ones must omit it
• What the scripts compute — a skill whose scripts only reformat user input will not clear the 40% time-saving bar

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Scaffold a new package

1. Write the description first, before any other content. If you cannot express the trigger set in 240 characters, the skill's scope is still too broad — narrow it.
2. Fill in a spec JSON: name, title, description, category, domain, script names, and whether the skill is generative.
3. Run the scaffolder with --dry-run to inspect the file plan, then again to write it.
4. Fill every TODO marker. The scaffold is deliberately unshippable until you do.

python3 engineering/write-a-skill/scripts/skill_scaffold.py \
  --input engineering/write-a-skill/assets/sample_skill_spec.json \
  --out engineering --dry-run --format text

The scaffolder refuses specs whose description exceeds 240 characters or lacks a Use when clause. That refusal is the point — it stops you building 4,000 lines of package around a skill that will never activate.

Workflow 2 — Audit descriptions for activation and collision

1. Run the auditor across the target domain, or against a JSON list while drafting.
2. Fix anything scoring under 70: budget overruns, missing Use when, filler adjectives.
3. Read the collision report. Any pair above 0.50 overlap means an assistant is guessing between them — either merge the skills or re-cut their triggers so each owns distinct vocabulary.

python3 engineering/write-a-skill/scripts/description_audit.py \
  --input engineering/write-a-skill/assets/sample_descriptions.json \
  --min-score 70 --collision-threshold 0.5 --format text

Exit code is 1 when any description scores below --min-score, which makes this usable as a CI gate. Point --domain engineering at a whole directory to audit every shipped description at once.

Workflow 3 — Lint before review

1. Run the linter in --strict mode so warnings fail too.
2. Fix errors in pattern order — P2 and P1 findings first, since frontmatter and description problems invalidate everything downstream.
3. Re-run until clean, then run each workflow's bash block verbatim and paste the output into the PR. A skill whose own examples were never executed is not done.
4. Hand the reviewer assets/skill-review-checklist.md for the judgement half.

python3 engineering/write-a-skill/scripts/skill_lint.py \
  --skill engineering/write-a-skill \
  --rules engineering/write-a-skill/assets/sample_lint_rules.json \
  --strict --format json

The linter distinguishes tools from helper modules. A scripts/*.py file that a sibling script imports and that has no __main__ guard is a library, so the argparse / --format / guard requirements are not applied to it; it is still checked for stdlib-only imports and the line-count budget. Imports that resolve to a .py file in the same scripts/ directory are permitted under Pattern 9 — reaching into a different skill's directory stays an error. Verify both behaviours with the built-in fixtures before shipping a linter change:

python3 engineering/write-a-skill/scripts/skill_lint.py --selftest

Decision frameworks

Where does this content go?

The single most common authoring mistake is putting everything in SKILL.md. Route content by asking what reads it and when.

If SKILL.md exceeds 500 lines, the split is almost never "trim prose." It is one whole section that should have been a reference from the start.

Description budget allocation [PROVEN]

240 characters, spent in this order:

Never spend budget on: the skill's own name, feature enumerations (those are tags), "pairs with X" routing prose (that goes in the body), or adjectives. The description is resident in context for every session in which the skill is installed — it is the most expensive text in the package per byte.

Does this deserve to be a skill? [RECOMMENDED]

Two "do not build it" columns is a rejection. One is a warning worth arguing about.