skills: five process-domain skills + check_skills.py

The four existing skills cover the product; nothing covered how work is
reported. Two rules this project has paid for — check the artifact rather
than the report, and do not state a claim more firmly than the evidence
allows — lived only in the operator's head and in chat, where Claude Code
never read them.

- felhom-evidence      five confidence tiers, artifact-over-report
- felhom-diagnosis     no hypothesis until a command has been seen red
- felhom-plain-language ASD-STE100, two options, the re-pitch
- felhom-handoff       the note goes to a FILE, not the conversation
- felhom-doc-authoring the pointer decides whether material is reached

scripts/check_skills.py asserts what decides whether a skill is EVER
reached: frontmatter parses, name == directory, description and body
non-empty, under 150 lines, installed copy still samefile()s into the
repo. install_skills.py globs and never reads the file, so a missing
description installs perfectly and then silently never loads.

It convicted on its first run: felhom-build-deploy is 179 lines. NOT
trimmed here (pre-existing skills are out of scope, and trimming a
deploy skill without exercising its commands is how a wrong command
reaches a live host) — a named single-entry GRANDFATHERED exception,
WARNed every run, R-394. A new skill over the limit is convicted.

Red-proof run and seen failing: description removed from
felhom-evidence -> exit 1, "frontmatter field 'description' is missing
or empty". Restored, tree clean.

skills/SOURCES.md records both MIT upstreams, that these are adaptations
not copies, and the six pieces deliberately EXCLUDED with reasons.

Register: R-392 (no architecture doc covers the two-AI workflow),
R-393 (decision-log skill deferred, with the reason), R-394.

skills/felhom-doc-authoring/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: felhom-doc-authoring
+description: How to write a document that an AI agent consumes — a SKILL.md, a CLAUDE.md, a .claude/rules/ file, or a TASK spec. Triggers - creating or editing any SKILL.md; editing a CLAUDE.md or anything under .claude/rules/; writing or revising a TASK-*.md; and the phrases "write a skill", "update the instructions", "add a rule". Contains the pointer rule, the two costs, where material sits, completion criteria, sprawl, and the one-rule-one-home rule.
+---
+
+# Authoring documents an agent reads
+
+A document a person reads can be skimmed and re-read. A document an agent reads is either reached or
+it is not, and if it is reached it is read once. That difference drives everything below.
+
+## 1. The pointer decides everything
+
+A skill's `description`, or a line in a `CLAUDE.md` naming a document, is a **pointer**. Its
+**wording**, not its target, decides whether the agent reaches the material and how reliably.
+
+A must-have document behind a vaguely worded pointer is a **reliability defect**, not a
+documentation preference. Sharpen the wording first. Inline the material only if sharpening fails.
+
+A pointer does two jobs:
+
+1. **Say what the material is** — the domain, in the reader's terms.
+2. **List the distinct cases that should trigger reaching it** — one trigger per case. Two synonyms
+   for the same case are one case written twice, and they buy nothing.
+
+House shape for a Felhom skill, taken from `skills/felhom-testing/SKILL.md`: a `description` that
+states the domain, then `Triggers - <comma list>`, then one sentence naming what the skill contains.
+
+## 2. The two costs
+
+- **Always-loaded material costs context on every turn**, whether it fires or not. A `CLAUDE.md`
+  line is paid for in every session that opens the repo.
+- **Material behind a pointer costs only the pointer's own line** until it fires.
+- **The second cost is the human's**: knowing which documents exist and when to reach for each. Ten
+  well-scoped documents nobody can name are worse than four that are known.
+
+## 3. Where a piece of material sits
+
+Three rungs, ordered by how immediately the material is needed:
+
+1. **Inline, in the ordered steps the agent performs** — what every path through the task needs.
+2. **Reference in the same file, consulted on demand** — what most paths need, but not at step 1.
+3. **Reference in a separate file, behind a pointer** — what only some paths reach.
+
+Inline what every path needs. Push out what only some paths reach. Getting this wrong in either
+direction is a cost: rung 1 material on rung 3 gets missed; rung 3 material on rung 1 is paid for
+every time and dilutes the steps around it.
+
+## 4. Completion criteria
+
+**Every step ends on a condition that says it is done.** "Investigate the failure" has no bound;
+"name one command that reproduces it, and show its output" does.
+
+A vague bound invites stopping early, and stopping early looks identical to finishing. When a step
+feels too large, **sharpen the bound before you consider splitting the step** — most oversized steps
+are underspecified, not overloaded.
+
+## 5. Sprawl and co-location
+
+A document can be too long even when every line in it is live. Attention thins across the excess,
+and the lines that matter most are not the ones that survive.
+
+**Felhom's limit: a `SKILL.md` is under 150 lines.** If one will not fit, say so and stop — do not
+silently split it into two documents nobody knows how to choose between.
+
+**Co-locate.** Keep a concept's definition, its rules and its caveats under one heading. A concept
+scattered across four sections is four chances to read three of them.
+
+## 6. One rule, one home
+
+If a rule already lives in another skill, or in `documentation/runbooks/workspace-CLAUDE.md`, **point
+at it by name and give only your additional material.**
+
+Two copies of a rule drift. When they do, the reader cannot tell which is current, and the safest
+reading — obey both — is not always possible. This is why `felhom-diagnosis` points at
+`felhom-testing` for the red-proof instead of restating it, and why `felhom-evidence` cites standing
+rules 2 and 3 in one line each rather than lifting them across.
+
+## 7. Validate it
+
+`python3 scripts/check_skills.py` (in `felhom.eu`) checks every `skills/*/SKILL.md`: the frontmatter
+parses, `name` matches the directory, `description` and the body are non-empty, the file is under
+150 lines, and any installed copy under `~/.claude/skills/` still resolves back into the repo.
+
+Installation is `python3 scripts/install_skills.py`. It discovers skills by globbing
+`skills/*/SKILL.md`, so **a new directory needs no registration** — the glob is the registry. Do not
+add a manifest or an index.