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.

---
name: write-a-skill
description: >
  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.
license: MIT + Commons Clause
metadata:
  version: 1.1.0
  author: borghei
  category: engineering
  domain: meta-skills
  updated: 2026-11-08
  tags: [authoring, meta-skill, linting, standards, packaging, agents-md]
---

# 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

```bash
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.

```bash
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.

```bash
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.

```bash
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:

```bash
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.

| 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 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: 472kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall