cc-os/plugins/os-vault/skills/write/SKILL.md

description

Write evergreen cross-project knowledge to the SecondBrain vault with correct frontmatter and scope. Use unprompted WHEN a durable fact surfaces mid-task — tool/API behavior discovered, a client convention, a methodology that worked — anything that would change how you act in a DIFFERENT repo. The vault, NOT auto-memory, is the destination for knowledge that generalizes beyond this repo; auto-memory is only for facts about this repo itself.

Use this skill when you have knowledge that should persist across projects and sessions.

Where knowledge goes — ask in order

1. Does the repo already record it (code, ADR, CLAUDE.md, git history)? → write it there or nowhere; never duplicate into memory.
2. Would this change how you act in a different repo, next year? → the SecondBrain vault via this skill — NOT auto-memory. Facts about the world: tool behavior, client conventions, API quirks, methodology that worked. The repo is where you learned it, not what it's about.
3. Only useful in future sessions of this repo (where things live here, what we tried here)? → auto-memory.
4. Task status, session state, in-flight progress → nothing (the session journal is handled automatically by the SessionEnd hook).

Tiebreaker: what is the fact about? About a tool/client/API → vault. About this repo → auto-memory. When a durable fact surfaces mid-task — even with no one saying "remember" — run the ladder before moving on.

Vault location — resolve it FIRST, mechanically

Before writing anything, resolve the vault root with one command and use ONLY the path it prints for every read and write in this skill:

echo "${OS_VAULT_PATH:-$HOME/Documents/SecondBrain}"

Do not assume ~/Documents/SecondBrain — OS_VAULT_PATH overrides it (tests and evals point it at an isolated vault, and writing to the default path there contaminates the user's real vault). Never write a vault note to a hardcoded path.

Frontmatter contract — read vault-conventions.md first

Before writing any note, read vault-conventions.md at the vault root. It is the single source of truth for the frontmatter schema, note types, and tag taxonomy — do not rely on a remembered or summarized version, and do not duplicate its schema here. This file will go stale if the contract is ever reconciled again and this summary isn't updated with it.

Brief summary, correct as of the last time this skill was edited (verify against vault-conventions.md, not this list, if anything looks off):

• scope is a frontmatter field (global/project/client), not a tag.
• type is both a frontmatter field and a type/<...> tag (kept in sync); valid values are listed in vault-conventions.md's Note Types table (e.g. howto, reference, convention, eval-results, hub, adr, log — the table is authoritative, this list is illustrative).
• Tags are flat and namespaced across six facets — type/, client/, project/, domain/, tool/, convention/. type/ is required; at least one other facet tag is recommended so the note routes to the right context.
• Filenames are slug-only lowercase-kebab-case (no date prefix).
• Write summary at creation time — it is the primary router hint for graph traversal and memsearch. Never defer it.
• Frontmatter must be parseable YAML: quote any scalar value that contains a colon (title: "Chartkit segfaults without streaming: true" — unquoted, that line breaks the whole frontmatter block and the note drops out of retrieval).

Write summary now. Deferring it breaks retrieval.

Update before create

Write is query-first: before creating a note, check for existing notes on the same subject (grep the vault or use /os-vault:query). If the new fact contradicts, extends, or refines an existing note → update that note and bump last_updated. Only a genuinely new subject gets a new note.

Content that fits no existing type

Do NOT invent a note type, and do not force a bad fit silently. Write the note under the closest existing type with a visible ## Type-fit note line saying what didn't fit — or, if the shape is clearly recurring, propose a new type via /os-vault:design-template. Misfits get reviewed in /os-vault:reorganize; three misfits of the same shape justify a new type.

Vault-not-repo rule

Write ONLY to the vault root (see Vault location above). Never silently write to a project repository what belongs in the vault. If in doubt, write to the vault.

PostToolUse hook is automatic

When you write or edit a .md file in the vault, the PostToolUse hook records the vault write and invalidates the rebuild stamp — the graph refreshes incrementally (via graphify extract --update) at the next session start, not immediately. You do not need to run graphify manually.