writing-skills git:20260703.7e660b7A

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

---
name: writing-skills
description: >-
  /writing-skills — the house discipline for authoring SKILL.md skills that
  behave predictably. Loads the rules; the skill_writer subagent applies them.
user_only: true
slash: writing-skills
---

# Writing Skills

A skill exists to wrangle determinism out of a stochastic system.
**Predictability** — the agent taking the same *process* every run, not
producing the same output — is the root virtue; every rule below serves it.

A protoAgent skill is a folder holding one `SKILL.md`: YAML frontmatter
(`name` + `description` required, description ≤ 1024 chars) over a markdown
body that becomes the agent's working instructions when the skill loads.
Deep docs: `docs/guides/skills.md`, `docs/guides/add-a-skill.md` (ADR 0052,
ADR 0060).

## Invocation classes — choose deliberately

- **Retrievable (default)** — indexed in the always-on `<available_skills>`
  list; the agent loads it with `load_skill`. Its description is scanned
  every turn, so the description is a real cost: write it as **triggers, not
  identity** — "Use when the user …, mentions …", one trigger per genuinely
  distinct branch, synonyms collapsed.
- **`user_facing: true` + `slash: <token>`** — additionally invokable as
  `/<token>` in chat.
- **`user_only: true`** — withheld from agent retrieval entirely; the slash
  is the only way in. Zero context cost; the *user* becomes the index that
  must remember it exists. The description turns human-facing: one plain
  sentence for the palette. Use this for rituals only ever fired by hand.

**Token collision check, every time:** slash precedence is goal > plugin
command > workflow > subagent > skill — a same-token workflow or subagent
silently shadows the skill (this is why `web-research` isn't `/research`).

## Body discipline

- **Steps end on a checkable completion criterion** — the agent must be able
  to tell done from not-done ("every modified surface accounted for", not
  "produce a list"). A fuzzy criterion invites premature completion.
- **Prefer a leading word** — a compact concept the model already holds
  (*tracer bullet*, *tight*, *red*) — over a restated triad; it anchors a
  region of behavior in one token, in the body (execution) and the
  description (invocation) alike.
- **Reference the docs, don't inline them.** Material only some runs need
  belongs in repo docs the body points at; the body carries what every run
  needs.

## Failure modes (diagnose with these)

- **Premature completion** — a step ends before it's done; sharpen the
  criterion first, split the sequence only if that fails.
- **Duplication** — one meaning in two places; costs tokens and maintenance.
- **Sediment** — stale layers that settle because adding feels safe and
  removing feels risky; the default fate of an unpruned skill.
- **Sprawl** — too long even when every line is live; push reference out.
- **No-op** — a line the model already obeys ("be thorough"); delete the
  sentence, don't trim it — or replace the weak word with a stronger one
  (*relentless*).

## Placement & workflow

Operator-authored skills live at `~/.protoagent/skills/<slug>/SKILL.md`
(create/edit via the console Skills surface — it round-trips the same
loader). Plugin-bundled skills live in the plugin's `skills/` dir; repo
examples in `config/skills/`. To draft or tighten one, delegate to the
**skill_writer** subagent — it returns the complete SKILL.md, its placement,
and the token to collision-check.

*(Discipline adapted from mattpocock/skills `writing-great-skills`, MIT.)*