skill-authoring

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.
context	Optional. Only value: fork — run the skill in an isolated forked subagent. See "Context: fork".
agent	Optional. Sub-agent for a forked skill: Explore, Plan, or general-purpose.
effort	Optional. Reasoning-effort hint: low, medium, or high.

name and description are the only required fields. context, agent, and effort are optional delivery-tuning fields. All five are value-checked by validators/validate-skill.sh; any other frontmatter key is left untouched.

---

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.

Context: fork (delivery mode)

context: fork runs a skill in an isolated forked subagent so its large body and working notes never pollute the main thread's context. It is a third delivery mode alongside preloaded and invoked.

When to fork	When NOT to fork
Skill is heavy (large reference catalog) AND one-shot (consulted once to produce an artifact, no interleaving with main reasoning).	Skill is iterative — it must see the current main-thread code/decisions on every step (e.g. testing-strategy, pattern-recognition).

Pair context: fork with an agent: to pick the fork's sub-agent:

agent:	Loads	Use for
Explore	lighter (skips CLAUDE.md + git)	read-only investigation; the fork produces advice only, writes nothing.
Plan	lighter (skips CLAUDE.md + git)	planning passes.
general-purpose	CLAUDE.md + history	reference skills that read context AND may need to write/apply guidance.

Reference skills that apply guidance (and may write) should use agent: general-purpose. Never fork an iterative skill — it would lose the live context it depends on. Reverting is trivial: delete the two lines.

Dynamic injection (!command)

A skill body may inject live shell output at load time. Claude Code executes a bang-prefixed command (the bang at line start or after whitespace) and inlines its stdout when the skill loads. Use this only for cheap, read-only, secret-free context.

The syntax is a bang immediately followed by a backtick-wrapped command. Shown here in a fenced block (NOT inline) so this doc itself does not execute anything on load:

Current branch: !`git branch --show-current 2>/dev/null || true`

Rules:

Rule	Detail
Cheap only	Instant commands (git branch, git worktree list). No network, no test runs, no find /. It runs on every skill load.
No secrets	NEVER inject printenv, env dumps, tokens, or cat .env. Read-only git/status only.
Fail quietly	Append `2>/dev/null
Portable	Use universally available commands (git). No project-specific binaries.
Doc examples	In documentation, always wrap bang-command examples in fenced code blocks, never inline backticks — inline backticked bang-commands in docs can be wrongly executed by the parser.

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