Skip to content

borghei/Claude-Skills / engineering/write-a-skill

write-a-skill

Verified

Author, lint, and publish skill packages that satisfy the library authoring standard. Use when creating a new skill, reviewing a skill PR, or fixing one that never activates.

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
  • Writing for an agent reader — deciding whether a skill is user-only, building a thin skill that chains others, or tightening AGENTS.md / CLAUDE.md

Scope rule

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, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • 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 need the Clarify First gate; advisory ones may include it when their advice depends on inputs users often leave out.
  • What the scripts compute: a skill whose scripts only reformat user input will not clear the 40% time-saving bar.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Quick Start

python3 engineering/write-a-skill/scripts/skill_lint.py --skill <domain>/<skill> --strict
python3 engineering/write-a-skill/scripts/description_audit.py --domain <domain> --min-score 70

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 codes: 0 all pass, 1 any description scores below --min-score (the CI gate), 2 bad input (missing file or directory, invalid JSON, wrong shape). Point --domain engineering at a whole directory to audit every shipped description at once; it walks nested skill folders and reads folded (>, >-), literal (|), quoted and plain description values.

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

Workflow 4 — Write for the agent that reads it

Every file in a package, and every steering file in a repo, is read first by a model that pays for each token and acts on each line. Read references/writing-for-agents.md before deciding three things:

  1. Who invokes it. Side effects the user must choose (publish, deploy, open tickets), a ritual with a user-chosen moment, or an expensive run: add disable-model-invocation: true. The linter rejects any value other than true or false.
  2. Whether it is a composing skill that chains other skills by name and passes artifacts by path, holding no domain content of its own.
  3. How the steering lines read. One short imperative line per fact; prune a line every time you add one.

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.

ContentDestinationTest
Workflows, decision tables, activation contextSKILL.mdAn assistant needs it on every invocation
Frameworks, benchmark tables, maturity models, regulatory detailreferences/*.mdNeeded on some invocations; would blow the 500-line budget
Deterministic analysis over user datascripts/*.pyA human would otherwise do it by hand for 15+ minutes
Anything the user fills in and keepsassets/*The output belongs to the user, not the skill

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:

SegmentBudgetContains
What it does~80 charsOne clause, concrete verb, the artifact produced
Use when triggers~140 chars3 trigger phrases in the user's own words
Slack~20 charsLeave it — descriptions grow at every revision

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?

SignalBuild itDo not build it
Time saved per use15+ minutesUnder 5 minutes
Repeat frequencyMonthly or moreOnce ever
Judgement encodedReal thresholds, named methodsGeneric process everyone knows
Nearest skill's trigger overlapUnder 0.4Over 0.6 — extend that skill instead
ScriptsCompute something non-obviousReformat what the user typed

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

Script count and shape [PROVEN]

Two to three scripts, 150-300 lines each. Under 150 lines means the tool does not justify a file; over 300 means it is two tools. Every script takes --format {text,json} with text as the default, exits 1 on findings so CI can gate on it and 2 on bad input so a tool error is never mistaken for a finding, and ships a sample_*.json in assets/ so the workflow block in SKILL.md is runnable by someone who just cloned the repo.

Anti-Patterns

The Keyword-Stuffed Description

Mistake: Padding the description with every synonym the author can think of, on the theory that more words means more matches. Why it happens: Discovery feels like search, and search rewards keywords. It also feels free, because the cost is paid in someone else's context window. Instead: Write the three sentences a user would actually type, and lift the distinctive nouns and verbs from those. Then run description_audit.py — if it reports a collision above 0.5 with a neighbouring skill, the fix is sharper scope, not more words.

The Encyclopedia SKILL.md

Mistake: Writing an 900-line SKILL.md that covers the domain exhaustively, with references/ left empty. Why it happens: The author knows the domain deeply and everything genuinely feels important. Splitting also feels like admitting the content is second-tier. Instead: Keep in SKILL.md only what an assistant needs on every single invocation — workflows, decision tables, activation context. Move frameworks and exhaustive detail to references/ and link them by relative path. references/ is not the demotion bin; it is where deep content is actually usable, because it gets loaded on demand instead of never.

The Untested Workflow

Mistake: Shipping bash blocks in Workflows that were written by hand and never executed, often with flags the script does not implement. Why it happens: The workflow is written before the script is finished, and nobody goes back once the flags settle. Instead: Run every bash block verbatim against the shipped sample data as the last step before opening the PR, and paste the real output into the PR description. A script that crashes on its own sample input is the single loudest quality signal a reviewer can get.

The Menu Skill

Mistake: Presenting five approaches with balanced pros and cons and letting the reader choose. Why it happens: It feels more honest and less presumptuous than picking one, especially when the author has seen all five work. Instead: State the recommendation, give the reason, then give the escape hatch — the specific condition under which the recommendation stops applying. Users invoke a skill for a position, not a survey; anything less than a recommendation they could have found themselves in thirty seconds.

The Steering-File Essay

Mistake: Writing AGENTS.md / CLAUDE.md in paragraphs: "It's really important that you always make sure to…". Why it happens: It is written like documentation for a colleague, and politeness feels harmless. Instead: One imperative line per fact, the situation first, the exact command or path, no filler. A third of the length carries the same instructions and leaves the agent more room for the task.

The Auto-Firing Side Effect

Mistake: A skill that publishes, deploys or opens tickets is left model-invocable, and fires on a loose description match. Why it happens: Model invocation is the default and nobody revisits it. Instead: Mark it disable-model-invocation: true so it runs only when the user asks, and keep a pointer in the steering file so it is not forgotten.

The Cross-Skill Dependency

Mistake: Writing "see the X skill for the scoring model" or importing a helper from ../other-skill/scripts/. Why it happens: Duplication feels wrong to engineers, and DRY is a deeply trained instinct. Instead: Copy the helper. Skills are distributed as individual folders, so a cross-skill import is a broken package the moment someone extracts one directory. A helper module inside the skill's own scripts/ directory is fine — that ships with the folder. standards/ is the only permitted outbound reference, because it applies to every skill everywhere.

Files

FilePurpose
scripts/skill_lint.pyLint a skill folder against all 11 patterns; per-pattern findings; exit 0 pass, 1 error findings (or warnings with --strict), 2 bad --skill path or rules file. --selftest runs the built-in helper/dependency fixtures
scripts/lint_checks.pyHelper library for skill_lint.py — rule set, frontmatter parser, SKILL.md and structure checks. No CLI by design
scripts/skill_scaffold.pyGenerate a compliant package skeleton from a JSON spec, with every required section stubbed; exit 2 on a bad or refused spec
scripts/description_audit.pyScore descriptions on budget and trigger quality; flag colliding skill pairs; exit 0 pass, 1 below bar, 2 bad input
references/authoring-playbook.mdSection-by-section guidance, worked description rewrites, and the content-routing rules
references/writing-for-agents.mdUser-only skills (disable-model-invocation), thin composing skills, and steering-file style with a before/after rewrite
references/pattern-checklist.mdThe 11 patterns as concrete pass/fail criteria with common failure modes and fixes
assets/sample_skill_spec.jsonRunnable scaffold input for Workflow 1
assets/sample_descriptions.jsonRunnable audit input for Workflow 2, including deliberately failing examples
assets/sample_lint_rules.jsonThreshold overrides for Workflow 3
assets/skill-review-checklist.mdReviewer checklist covering the judgement half the linter cannot check

Scope & Limitations

In Scope:

  • Package scaffolding from a JSON spec with skill_scaffold.py, which refuses descriptions over 240 characters or without a Use when clause.
  • Description scoring and collision detection with description_audit.py, from a JSON list or a whole domain directory.
  • Linting a skill folder against the 11 patterns of standards/skill-authoring-standard.md with skill_lint.py, including --strict, rule overrides and --selftest.
  • Content routing, description budget and script shape guidance in references/, and a reviewer checklist in assets/.
  • Writing for an agent reader: when to make a skill user-only, how to write a thin composing skill, and how to write AGENTS.md / CLAUDE.md; the linter validates disable-model-invocation when present.

Out of Scope:

  • Writing the domain knowledge, frameworks or scripts that go inside a new package.
  • Testing how a skill activates or performs in a real assistant session.
  • Security review of third-party skills before installation.
  • Regenerating repository manifests or publishing a skill.

Important Caveats:

  • The linter checks structure, sections, line counts, imports and phrasing rules. A clean lint does not mean the content is correct or useful; assets/skill-review-checklist.md covers that half.
  • Description scores and collision values come from word heuristics, not from real activation data.
  • The thresholds (240 characters, 500 lines, 0.50 overlap) are this repository's standard and can be overridden with a rules file.

Reference Documentation

  • references/authoring-playbook.md — section-by-section authoring guidance and description rewrites.
  • references/pattern-checklist.md — the 11 patterns as pass/fail criteria.
  • references/writing-for-agents.md — invocation choice, composing skills, steering-file style.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall