claude-sdk-rs: Skill for Claude Code

Writing markdown in this brain

Paths below are relative to the brain root — the directory containing brain.toml, found by walking up from wherever you are. This skill is synced into every repo, so a repo-relative link would be wrong in most of them.

Three separate obligations, in this order. Most breakages come from doing #1 and skipping #2.

1. Frontmatter — if the file is a corpus member (Step 1 decides).
2. An index.md row — Standing Rule 7. Skipping this is the most common failure.
3. Validation — one flag per invocation; they do not compose.

The schema tables (every field, every controlled vocabulary, per-type examples) live in docs/okf-frontmatter.md, governed by docs/decisions/D27-enriched-okf-frontmatter.md. This skill is the procedure, not the schema — read that doc when you need to pick a type, a layer, or a status.

---

Step 1 — Does this file need frontmatter at all?

Deterministic, from core/mev/src/brain/crawl.rs::is_corpus_member. A file is a corpus member iff, relative to its owning repo root, it is:

• exactly README.md, CLAUDE.md, or index.md at the repo root, or
• anywhere under planning/ or docs/ (any depth).

Those three filenames are matched literally. GEMINI.md and AGENT.md sit beside CLAUDE.md at the same repo roots and are not corpus members — they carry no frontmatter obligation and no index row, and editing one changes nothing a gate can see. Do not "correct" CLAUDE.md to another agent's filename anywhere in this document; the rule is the string, not the tool.

Everything else — src/*.md, a stray root-level .md, anything under an unregistered directory — is out of corpus: no frontmatter obligation, no index row, no validation.

Then subtract the ephemeral names, from crawl.rs::is_ephemeral. These are excluded even inside planning/:

handoff.md · tasks.md · breakdown.md · worklog.md · any filename starting with _

The _ prefix is a debugging trap, not just a convention. A probe named _zz_test.md is invisible to validate-brain. You will conclude detection is broken when it is working exactly as designed. If you are testing whether a check fires, do not name the fixture with a leading _.