Skill Craft

---
name: skill-craft
description: Use it when you write, change, review, or retire a skill in a Manence MOS (`.claude/skills/`): deciding where each sentence lives (against AGENTS.md, the Spec, and the hard boundary), keeping the stops, testing that the description routes on its own, comparing the installed copy with the version the framework ships, and leaving a trace. Not for generic prompt craft, nor for a skill outside a MOS.
---

# skill-craft, writing and maintaining a skill

## Purpose
A skill gives the agent that loads it **the purpose of the gesture, the context it needs to decide, and a way to know it is done**, and nothing that already lives elsewhere. A skill is the instructions for a repeated gesture (the rule of three, `AGENTS.md`); it is soft: it suggests. Whatever must be impossible lives in the guard, not here (`AGENTS.md` "Security, hard vs soft", Spec §12).

## Read before you write
- **The hard boundary**: `.claude/hooks/guard.sh` (and the MOS's `guard.local.sh`), the `permissions.deny` rules in `.claude/settings.json`, and what `lint.sh` checks. Prose that restates a deny rule is a repetition, and if the two drift apart, the agent is briefed with something false that the hard boundary will overrule without the agent ever seeing why.
- **The homes**: `AGENTS.md` (routing table, harnesses, security, conventions), the Spec, the KB. What lives there gets linked, not rewritten (L2): a copied rule has to be fixed twice. **Settled exception**: for the *procedure* of a gesture, the skill is canonical; the Spec sets the contract (what must be true: files, statuses, invariants) and points to the skill for the step-by-step. If the Spec still spells out a step-by-step, it is the Spec you trim at the next version, not the skill you empty.
- **The installed copy against the shipped version**: for a base skill, compare `.claude/skills/<name>/SKILL.md` with the version the framework ships (`upgrade.sh <core-dir>` without `--apply` shows the diff) before you touch anything. Drift runs both ways (a copy that has fallen behind, a local adaptation that was never contributed back); a local adaptation that holds for every MOS is something to upstream (the framework's CONTRIBUTING), not a difference to keep.
- **The existing skills**: the MOS's own and the framework's base skills. If a gesture is already covered, you extend that skill.
- **The template** `templates/SKILL.template.md`: it is the skeleton; the method is here.

## Writing
0. **A skill is written in English; what it produces speaks the MOS's working language** (declared in `AGENTS.md` under Language: log entries, About fields, replies to the user). Never hard-code a language into a skill's outputs. A quoted marker a skill makes the agent write ("waiting for a GO", a section name) is a meaning, written in the working language; it is a **key**, kept verbatim, only when another reader matches it (a lint, a `proof_marker`, a log prefix such as `review |`, a contract value of the Spec). A skill that writes to the journal says where in one clause: at the top of `log.md`, under its H1 (Spec §4).
1. **The description is the scarce text.** It is read on its own, all the time, to decide whether to load the skill; the body loads only when the skill is used (Spec §9), and even then it isn't free. The description says *when* to load the skill and what it produces, not how to do the work, and **it doesn't quote an everyday phrase** that belongs to another gesture ("look at the inbox" in a skill that processes instructions pulls inbox triage away from the review). It gets tested (see "Done").
2. **The body**: the purpose in one line; the context as links; **what must be true** at each step rather than how to get there (the model knows how to click; a criterion carries over from one harness to another, a script for reasoning carries over poorly); the inputs and outputs; what "done" means for the gesture.
3. **"Done" for the gesture**: an observable state, verifiable from outside (a script, a lint, a judge in a fresh context, never self-assessment: L4); at least one **reading criterion** (the term every skill and the template use) that no machine can tick, replayable identically; the trace the gesture leaves (About, log, KB: L8). A gesture that leaves no trace is not done. Two different runs can leave the same state on disk: that state is what counts, not whether a procedure was followed.
4. **Every prescriptive sentence has one of four fates**, decided when you write it just as when you remove it:
   - **Contract**: a reader other than the executing model reads **a specific field, format, or location** that the sentence fixes (the lint, the Manence UI reader, `mos.json`, a script, another harness). "The next session will read the result" doesn't count: otherwise everything becomes a contract. A contract lives in its reader's home; the skill keeps the link.
   - **Stop**: a destructive or irreversible action, a change of scope, information only the human holds, a write to a third party (GO, dry run, before/after, draft first: Spec §12). A stop is never pruned. If the hard boundary enforces it, the skill keeps only the link; **if the hard boundary doesn't** (the case of the golden rule, as long as nothing blocks sending or publishing), the skill keeps it **in one line that points to `AGENTS.md`**, and the gap becomes a hardening proposal in the log, not a restatement in every skill.
   - **Criterion**: what an audit or review skill checks (the items of `kb-lint`, the checks of the `weekly-review`). Neither contract nor guidance: it is the gesture itself. A criterion is removed when what it checks has disappeared, not because it lacks a reason.
   - **Guidance**: shapes how the model goes about the work. It gets in only with **its reason in one clause and its named failure**: a dated reference in the sentence ("incident of YYYY-MM-DD") and the matching entry in the log (type `incident |`, or `framework |` if the lesson is framework-level; the log sieve applies: an incident that changed no rule isn't written down). For a base skill, the matching entry is in the framework's `CHANGELOG.md` or log, not in the installed MOS's: the reference is checked there. With no reason and no failure, the sentence goes. A checker who can't find the reference reports "not cited", and that is enough to remove it.
   The substitution test, for the last three fates: if a lint, a schema, or a fresh context can observe the result after the fact, keep the criterion and drop the instructions.
5. **Don't write**: how much thinking is expected (the model sets that itself); an account of the reasoning in the answer (the answer doesn't retrace the path, the trace keeps the evidence); steps the model would take on its own; a number to hit with no reader behind it (a numeric constraint with no way out makes an agent loop: incident of 2026-09-27, a model called in headless mode rewrote its answer twelve times to stay within a word range); a model name (wrong on the other harnesses, and quickly outdated; the harness resolves a capability, not a product). **A bound on form for a human reader** ("five lines", "three actions") is guidance like any other: it gets in with its named failure (an unreadable report), otherwise it goes.
6. **A third-party system**: a link to its page (the map in `AGENTS.md`, or `CLAUDE.local.md` for a confidential adapter); the system describes itself (Spec §15), so you don't write one skill per system. "Look at how things are organized before you act" lives in `AGENTS.md` "Conventions"; the skill says *what there is to look at* and how far to go.
7. **A delegation**: the role is written where the actor is the mechanism of the step, and only there (verify in a fresh context; delegate to a subagent; wait for the human GO). No "actor" field per step: it would be filled in with "the session" and become the next repetition. The parent gives the subagent: the resolved absolute path if there is a workstream (Spec §18), otherwise **the scope, the window, and whether it may write**; the role; the success condition. The subagent's instructions have a single home.
8. **Run the skill once on a real case before you commit it**, under the skill's own stops: a write to a third party runs as a dry run or a draft, after the GO (`AGENTS.md` "Security, hard vs soft"). It is the only proof that a piece of guidance is missing or unnecessary.

## Reviewing, pruning, retiring
- **When**: the `weekly-review` (the skill's age in git, installed copy against shipped version, a change in the substrate flagged by the outward watch), or an incident recorded in the log. A review can end in **retirement**: a skill that no longer triggers still costs its description in every session.
- **Order**: write the success condition first (without it you can't tell a risk from a preference); remove **one class of guidance at a time** (bounds on form, step orderings, prohibitions with no incident behind them); the real runs that follow are the test, and a sentence comes back, minimal and with its named failure, if one of the harnesses misses the condition. Remove, observe, and reintroduce on failure, rather than replaying every sentence before you remove it.
- **Trace of the edit**: what changed, why, which cases were run, on which harnesses; in the log for a substantive change (tagged `framework |` if the lesson is framework-level), and the commit message carries it. A failure that stays in a conversation grounds no rule.

## Base skills (upstreaming to the framework)
- A base skill is fixed at the source, in the framework's repository, and then comes back to every MOS through `upgrade`. Never the other way around: you don't fix an installed copy in place. A local adaptation that is useful to every MOS gets upstreamed (CONTRIBUTING).
- A skill born in a MOS and harvested into the framework goes home as the shipped file: when the version that ships it is published, the MOS of origin replaces its prototype with it (the framework's `Implementation.md` §10).
- Upstreaming is **refused** if the skill carries a path specific to one MOS, a workaround specific to one operator, **a person's name or handle**, or an example that only exists in one language.
- A requirement that holds for every MOS, and has survived a review cycle, moves up into the Spec as a contract; the skill keeps the procedure (see "Read before you write").

## Done (for this skill)
- **Routing**: the description loads the skill on two requests aimed at it, and doesn't load it on two neighboring requests aimed at another **framework skill**. The test is played against the framework's skills, not against the tooling of one workstation: that is what makes it replayable from one operator to the next.
- **Homes**: no sentence restates a rule from the hard boundary, `AGENTS.md`, the Spec, or another skill; every piece of guidance carries its reason and its dated failure.
- **Copy and source**: for a base skill, the installed copy and the shipped version differ only by what upstreaming refuses.
- **Proof**: run once on a real case, judged by a context other than the author's; lint clean.
- **If it is a base skill**: a log entry, at the top of `log.md`, under its H1 (Spec §4); a commit message that carries the trace of the edit.