borghei/Claude-Skills / engineering/write-a-skill
write-a-skill
VerifiedAuthor, 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
- 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.
- Fill in a spec JSON: name, title, description, category, domain, script names, and whether the skill is generative.
- Run the scaffolder with
--dry-runto inspect the file plan, then again to write it. - Fill every
TODOmarker. 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
- Run the auditor across the target domain, or against a JSON list while drafting.
- Fix anything scoring under 70: budget overruns, missing
Use when, filler adjectives. - 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
- Run the linter in
--strictmode so warnings fail too. - Fix errors in pattern order — P2 and P1 findings first, since frontmatter and description problems invalidate everything downstream.
- 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.
- Hand the reviewer
assets/skill-review-checklist.mdfor 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:
- 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 thantrueorfalse. - Whether it is a composing skill that chains other skills by name and passes artifacts by path, holding no domain content of its own.
- 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.
| Content | Destination | Test |
|---|---|---|
| Workflows, decision tables, activation context | SKILL.md | An assistant needs it on every invocation |
| Frameworks, benchmark tables, maturity models, regulatory detail | references/*.md | Needed on some invocations; would blow the 500-line budget |
| Deterministic analysis over user data | scripts/*.py | A human would otherwise do it by hand for 15+ minutes |
| Anything the user fills in and keeps | assets/* | 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:
| Segment | Budget | Contains |
|---|---|---|
| What it does | ~80 chars | One clause, concrete verb, the artifact produced |
Use when triggers | ~140 chars | 3 trigger phrases in the user's own words |
| Slack | ~20 chars | Leave 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?
| Signal | Build it | Do not build it |
|---|---|---|
| Time saved per use | 15+ minutes | Under 5 minutes |
| Repeat frequency | Monthly or more | Once ever |
| Judgement encoded | Real thresholds, named methods | Generic process everyone knows |
| Nearest skill's trigger overlap | Under 0.4 | Over 0.6 — extend that skill instead |
| Scripts | Compute something non-obvious | Reformat 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
| File | Purpose |
|---|---|
scripts/skill_lint.py | Lint 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.py | Helper library for skill_lint.py — rule set, frontmatter parser, SKILL.md and structure checks. No CLI by design |
scripts/skill_scaffold.py | Generate a compliant package skeleton from a JSON spec, with every required section stubbed; exit 2 on a bad or refused spec |
scripts/description_audit.py | Score descriptions on budget and trigger quality; flag colliding skill pairs; exit 0 pass, 1 below bar, 2 bad input |
references/authoring-playbook.md | Section-by-section guidance, worked description rewrites, and the content-routing rules |
references/writing-for-agents.md | User-only skills (disable-model-invocation), thin composing skills, and steering-file style with a before/after rewrite |
references/pattern-checklist.md | The 11 patterns as concrete pass/fail criteria with common failure modes and fixes |
assets/sample_skill_spec.json | Runnable scaffold input for Workflow 1 |
assets/sample_descriptions.json | Runnable audit input for Workflow 2, including deliberately failing examples |
assets/sample_lint_rules.json | Threshold overrides for Workflow 3 |
assets/skill-review-checklist.md | Reviewer 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 aUse whenclause. - 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.mdwithskill_lint.py, including--strict, rule overrides and--selftest. - Content routing, description budget and script shape guidance in
references/, and a reviewer checklist inassets/. - 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 validatesdisable-model-invocationwhen 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.mdcovers 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |