Skip to content
Skills Library
AI & agents · Building & coding

write-a-skill

/write-a-skill

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.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/description_audit.py, scripts/lint_checks.py, scripts/skill_lint.py, scripts/skill_scaffold.py

What it does and when to use it

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.

Original author 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.

How it works

  1. When to use this skill
  2. Inputs the skill expects
  3. Clarify First
  4. Workflows
  5. Decision frameworks
  6. Anti-Patterns
  7. Files
  8. Scope & Limitations
Original SKILL.md headings · 223 lines, 2,131 words
SKILL.md preview
---
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.0.0
  author: borghei
  category: engineering
  domain: meta-skills
  updated: 2026-07-21
  tags: [authoring, meta-skill, linting, standards, packaging]
---

# 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, 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.

## 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 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.

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

## 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? [RECOMMENDED]

| 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
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 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 1 on error. `--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 |
| `scripts/description_audit.py` | Score descriptions on budget and trigger quality; flag colliding skill pairs |
| `references/authoring-playbook.md` | Section-by-section guidance, worked description rewrites, and the content-routing rules |
| `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/`.

**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.
Files in this package (11)
  • SKILL.md 14 KB
  • assets/sample_descriptions.json 1 KB
  • assets/sample_lint_rules.json 1 KB
  • assets/sample_skill_spec.json 1 KB
  • assets/skill-review-checklist.md 3 KB
  • references/authoring-playbook.md 13 KB
  • references/pattern-checklist.md 10 KB
  • scripts/description_audit.py 9 KB
  • scripts/lint_checks.py 9 KB
  • scripts/skill_lint.py 10 KB
  • scripts/skill_scaffold.py 9 KB

Versions

RepositoryScoreLicence
This page · borghei/Claude-Skills100MIT
alirezarezvani/claude-skills100MIT
redpanda-data/ui-harness100MIT
RubenGlez/rubstack100MIT
holl4ndtv/skills100MIT
yamcodes/arkenv100MIT
mkurman/zorai100MIT
AmirAzy/HoNspot100MIT
slogsdon/skills-meta-utils100MIT

Database snapshot: 13.11.2026 · package version 77c86f8cfc04 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100create-skill
    Create or update Claude Code skills following Anthropic's official skill standard. Use when user says "create a skill", "new skill", "write a skill", "update a skill", "skill standard", or any time a new SKILL.md file needs to be created. Also use when reviewing existing skills…
  • 98skill-creator
    Authors the CONTENT of a brand-new agent skill for any stack or agent runtime - turns a vague capability request into a routable SKILL.md with a trigger-rich description, hard rules, and a verification loop, and repairs a skill that never activates. Activates when the user says…
  • 100writing-skills
    Author and pressure-test agent skills—triggers, thin SKILL.md, references, validation. Use when creating or revising skills in this repo. Triggers: "write a skill", "new skill", "skill authoring", "improve skill triggers".
  • 100hvs-skill-buddy
    HVS Skill Buddy is the meta-skill for the entire HVS skill ecosystem. It keeps skills current with the latest Anthropic patterns, audits the skill library for drift and inconsistency, and creates new skills that fit the HVS system standard. ALWAYS trigger when the user mentions…
  • 100skill-lint
    Builds, audits and scores portable Agent Skills (SKILL.md plus scripts) for Claude Code, Codex and Cursor. Use when the user asks to write a skill, convert a workflow into a reusable skill, fix a skill that never triggers, or review a SKILL.md before publishing.
  • 100skill-authoring
    Authors, reviews and evaluates Agent Skills and their SKILL.md files. Use when creating or rewriting a skill, fixing a skill description that never triggers, splitting an overgrown SKILL.md into references/, writing evals for a skill, or publishing a skill repository.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.