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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| assets/sample_descriptions.json | config | 1.3 KB |
| assets/sample_lint_rules.json | config | 318 B |
| assets/sample_skill_spec.json | config | 1.2 KB |
| assets/skill-review-checklist.md | markdown | 2.7 KB |
| references/authoring-playbook.md | markdown | 13.3 KB |
| references/pattern-checklist.md | markdown | 10.4 KB |
| references/writing-for-agents.md | markdown | 8.1 KB |
| scripts/description_audit.py | script | 9.7 KB |
| scripts/lint_checks.py | script | 8.8 KB |
| scripts/skill_lint.py | script | 10.3 KB |
| scripts/skill_scaffold.py | script | 9.0 KB |
SKILL.md
View on GitHub---
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.
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: 472k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |