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

description
Write evergreen knowledge to the SecondBrain vault with correct frontmatter and scope

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

Evergreen vs. ephemeral test

Write to vault if: the knowledge is reusable across projects (tool/API behavior, client-specific facts, conventions, cross-project patterns). Vault is for knowledge that survives the current session.

Do NOT write to vault: project-ephemeral state (current task, in-progress decisions, temporary context). These belong in project files or the episodic layer (session journal — handled automatically by SessionEnd hook).

Vault location

The vault root is ~/Documents/SecondBrain — unless the environment variable OS_VAULT_PATH is set, in which case use that path as the vault root instead (rare; tests and evals use it to point at an isolated vault).

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.

Write summary now. Deferring it breaks retrieval.

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.