skill-authoring git:20260627.a92d132A

Immutable. This exact content is served forever at /api/v1/blob/8e519d4b5e580271.

---
name: skill-authoring
description: "Methodology for authoring scaffolding-compatible skills: frontmatter contract, body structure, validation. TRIGGER when: running /create-skill, writing or reviewing a SKILL.md file, or deciding if a procedure deserves its own skill. SKIP: distilling a conversation into candidates (use distill); 3-tier memory writes (use agent-memory)."
---

# Skill Authoring Skill

## Purpose

Methodology for authoring scaffolding-compatible skills. A skill is a single
`SKILL.md` file under `skills/<name>/` that encodes a reusable methodology Claude
Code can auto-invoke. This skill defines the frontmatter contract, the recommended
body structure, the description-writing rules, and the quality bar every authored
skill must meet before it ships.

## When to Apply

Apply this skill when:

- Running the `/create-skill` command to scaffold a new skill
- Hand-writing or editing a `skills/<name>/SKILL.md` file
- Reviewing a skill for frontmatter correctness or auto-invocation quality
- Deciding whether a repeatable procedure deserves promotion into its own skill

Do NOT apply this skill for:

- Distilling a conversation into knowledge candidates — use `distill`
- Writing into the 3-tier file memory — use `agent-memory`

---

## Frontmatter Contract

Every `SKILL.md` MUST begin with a YAML frontmatter block delimited by `---`:

| Field | Rule |
|-------|------|
| `name` | Required. Kebab-case `^[a-z][a-z0-9-]*$`. MUST equal the parent directory name. |
| `description` | Required. Non-empty, 1–340 characters. Follows the Description Contract below. |

No other frontmatter fields are used by scaffolding skills. The `name` /
directory-name match is mechanically enforced by `validators/validate-skill.sh`.

---

## Description Contract

The `description` field drives Claude Code's automatic skill invocation. A vague
or overbroad description either fails to trigger or triggers on the wrong tasks.
Every scaffolding skill `description` MUST follow this template:

```
"<one-line capability summary>. TRIGGER when: <2-4 concrete observable situations>. SKIP: <1-2 cases handled by a named neighbour skill or out of scope>."
```

Rules:

| Rule | Detail |
|------|--------|
| Length cap | Keep the whole string under ~340 characters. Trim the summary first. |
| Observable triggers | Use observable verbs/nouns ("writing a migration"), not adjectives ("complex DB work"). |
| 2–4 triggers | Fewer than 2 under-triggers; more than 4 dilutes the match. |
| Named `SKIP` | Name the competing neighbour skill — e.g. `SKIP: ... (use python-patterns)`. |
| Mutual `SKIP` | If skill A's `SKIP` names skill B, skill B's `SKIP` SHOULD name skill A. No two skills' `TRIGGER` clauses may overlap without a mutual disambiguating `SKIP`. |
| Under-trigger bias | For borderline cases, prefer under-triggering over false activations. |

When a skill has no overlapping neighbour, the `SKIP` clause may instead name an
explicitly out-of-scope case. The `/create-skill` command composes this string
automatically from the collected inputs.

---

## Recommended Body Structure

A skill body should read top-to-bottom as a methodology, not as prose. Use this
section order:

| Order | Section | Content |
|-------|---------|---------|
| 1 | `## Purpose` | One short paragraph: what the skill encodes and the outcome. |
| 2 | `## When to Apply` | Bulleted TRIGGER situations, then explicit SKIP cases. |
| 3 | Methodology section(s) | The repeatable procedure — prefer decision tables. |
| 4 | `## Anti-Patterns` | Table of common mistakes and their corrections. |
| 5 | `## Quality Checklist` | Verifiable completion criteria. |

Guidelines:

- Prefer tables for decision matrices and checklists; keep prose minimal.
- Each section earns its place — delete empty scaffolding.
- Scaffold new skills from `templates/skill-template.md`.

---

## Preloaded vs Invoked (orchestration contract)

A skill reaches an agent in one of two ways, and the author should decide which
on purpose:

| Mode | Mechanism | Use when |
|------|-----------|----------|
| **Preloaded** | Listed in an agent's `skills:` frontmatter — in context from turn one. | The agent needs the skill on **nearly every task** it runs. |
| **Invoked** | Auto-loaded on demand when the task matches the skill's `description:` `TRIGGER`/`SKIP`. | The skill is **situational**. |

Decision rule: *preload* a skill when an agent needs it almost every task;
otherwise leave it *invoked* and rely on a precise `description:`. Preloading is a
context-budget decision (skills < 300 tokens each) — prefer invoked when in
doubt. The full Command → Agent → Skill responsibility split lives in
`docs/orchestration-pattern.md`.

## The 500-Line Rule

A `SKILL.md` file MUST stay **under 500 lines**. Auto-injected skill context is
bounded; an oversized skill is silently truncated and loses its tail content. If a
skill approaches the limit, split it into two narrower skills with distinct
`TRIGGER`/`SKIP` clauses rather than letting one file sprawl.

---

## Quality Checklist

Before a new or edited skill ships:

- [ ] Frontmatter block present and delimited by `---`
- [ ] `name` is kebab-case and equals the parent directory name
- [ ] `description` follows the Description Contract and is under 340 chars
- [ ] Body has `## Purpose`, `## When to Apply`, a methodology section, and `## Anti-Patterns`
- [ ] File is under 500 lines
- [ ] Every neighbour skill that overlaps is named in a mutual `SKIP` clause
- [ ] `bash validators/validate-skill.sh skills/<name>/SKILL.md` exits 0
- [ ] tech-writer task queued to add the skill to `README.md` / `CHANGELOG.md` and bump `plugin.json` counts