# Schema Author

> Use when adding, renaming, reviewing, or explaining Brain schema tokens, aliases, prefixes, link types, extractability, or expert routing in Open Second Brain vaults.

- Skill: `itechmeat/schema-author` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itechmeat/schema-author`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itechmeat/schema-author/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: itechmeat (https://skillmd.com/u/itechmeat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/itechmeat/schema-author

---


# Schema Author

Use this skill when a task changes the active Brain schema pack in `Brain/_brain.yaml` or reviews content against that schema.

## Workflow

1. Inspect the active schema pack with `schema_inspect` (`view="active_pack"`) or `o2b brain schema --json`.
2. Check current usage and findings with `schema_inspect` views `stats`, `lint`, and `orphans`.
3. Explain candidate tokens with `schema_inspect` (`view="explain_type"`) before renaming or deleting them.
4. Preview the batch first with `schema_apply_mutations` (`dry_run=true`) or `o2b brain schema apply --dry-run --mutation ...`: it returns the pack that would result and its diff and writes nothing at all - no config write, no audit record, no lock file. It runs the same pack validator the apply runs, so a batch that validator rejects raises identically in both. It does not run the two checks that exist only because the apply writes: the vault-identity write guard, and the atomic writer's re-parse of the rendered YAML. A batch that renders to unparseable YAML previews clean and fails on apply, so treat a clean preview as "the mutations are valid", not as "the apply will succeed".
5. Apply schema changes only through `schema_apply_mutations` or `o2b brain schema apply --mutation ...` so writes are locked, atomic, and audited.
6. Re-run lint/stats after mutation and report changed tokens plus any remaining findings.

## Mutation Notes

Supported operations are `add_type`, `remove_type`, `update_type`, `add_alias`, `remove_alias`, `add_prefix`, `remove_prefix`, `add_link_type`, `remove_link_type`, `set_extractable`, and `set_expert_routing`.

Schema tokens must be lowercase normalized tokens accepted by Open Second Brain schema validation. Prefer small, durable tokens over project-specific phrasing unless the schema pack is explicitly project-scoped.