[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6N0CHV2H41SSQSDP92BTJGR":3,"skill-same:01M6N0CHV2H41SSQSDP92BTJGR":130},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":51,"linkOnly":52,"markdownContent":53,"markdownBody":54,"frontMatter":55,"refName":107,"commitSha":108,"skillDirectory":109,"forksCount":110,"repositoryHtmlUrl":111,"repositoryHomepageUrl":6,"ownerHtmlUrl":112,"ownerBlogUrl":113,"ownerDescription":114,"updatedAt":115,"install":116,"resources":129},"01M6N0CHV2H41SSQSDP92BTJGR","schema-author",null,"Evolve your brain's schema pack. Add page types, propose new ones from corpus scans, backfill page.type on existing pages, audit pack health. Triggers when an agent notices untyped pages, custom domains needing typed entities (researcher, contract, deposition), or wants to see what types the pack declares.","garrytan\u002Fgbrain","garrytan","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F19957?v=4","01M6DJCCDDG53MTYYRTXAXFG17","Garry Tan","01M6MZQZCEN3RRMD33E1X9ZZR9",32847,"MIT","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fplugin\u002Fskills\u002Fschema-author\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000037","律师与法务","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50],"author","schema author","schema","new","MCP","when","types","domains","false","brain","get","active","expert","remove","evolve","SET","audit","update","create","notes","sync","review","2026-11-10 10:12:30",false,"---\nname: schema-author\ndescription: Evolve your brain's schema pack. Add page types, propose new ones from corpus scans, backfill page.type on existing pages, audit pack health. Triggers when an agent notices untyped pages, custom domains needing typed entities (researcher, contract, deposition), or wants to see what types the pack declares.\ntools:\n  - gbrain schema active\n  - gbrain schema list\n  - gbrain schema stats\n  - gbrain schema review-orphans\n  - gbrain schema detect\n  - gbrain schema suggest\n  - gbrain schema lint\n  - gbrain schema graph\n  - gbrain schema explain\n  - gbrain schema fork\n  - gbrain schema use\n  - gbrain schema add-type\n  - gbrain schema remove-type\n  - gbrain schema update-type\n  - gbrain schema add-alias\n  - gbrain schema remove-alias\n  - gbrain schema add-prefix\n  - gbrain schema remove-prefix\n  - gbrain schema add-link-type\n  - gbrain schema remove-link-type\n  - gbrain schema set-extractable\n  - gbrain schema set-expert-routing\n  - gbrain schema sync\n  - gbrain schema reload\n  - mcp:get_active_schema_pack\n  - mcp:list_schema_packs\n  - mcp:schema_stats\n  - mcp:schema_lint\n  - mcp:schema_graph\n  - mcp:schema_explain_type\n  - mcp:schema_review_orphans\n  - mcp:schema_apply_mutations\n  - mcp:reload_schema_pack\ntriggers:\n  - \"add a page type\"\n  - \"add a type to my schema\"\n  - \"my brain has untyped pages\"\n  - \"schema isn't matching my notes\"\n  - \"propose new types from my corpus\"\n  - \"backfill page types\"\n  - \"evolve my schema\"\n  - \"extend the schema pack\"\n  - \"create a custom type for\"\n  - \"researcher type\"\n  - \"make X an expert type\"\n  - \"schema pack add\"\n  - \"schema mutate\"\n  - \"schema sync\"\n  - \"schema author\"\nbrain_first: exempt\nwrites_pages: false\nwhen_to_use: \"Use when the user asks: \\\"add a page type\\\", \\\"add a type to my schema\\\", \\\"my brain has untyped pages\\\", \\\"schema isn't matching my notes\\\", \\\"propose new types from my corpus\\\".\"\n---\n\n# schema-author — evolve your schema pack\n\n## Non-goals (use these other skills instead)\n\nThis skill AUTHORS the schema pack (adds page types, link verbs, prefixes,\nflags). For these adjacent jobs, route elsewhere:\n\n- **Filing one specific page** → `skills\u002Fbrain-taxonomist\u002FSKILL.md`. Brain-\n  taxonomist routes at WRITE TIME (\"where does this note go?\"). schema-author\n  changes the rules at AUTHORING TIME (\"what types and prefixes exist?\").\n- **Schema-check as part of EIIRP iteration** → `skills\u002Feiirp\u002FSKILL.md`\n  already has a schema-check phase. Don't duplicate.\n- **Just looking up a type's settings** → `gbrain schema explain \u003Ctype>`\n  directly. This skill is for CHANGING the pack, not READING from it.\n- **Querying who knows about X** → `gbrain whoknows \u003Ctopic>` directly.\n  schema-author makes a type expert-routable; it does not run the query.\n\n## Convention\n\n> **Convention:** see [conventions\u002Fbrain-first.md](..\u002Fconventions\u002Fbrain-first.md) for the lookup chain (search → query → get_page → external).\n\n> **Convention:** see [conventions\u002Fschema-evolution.md](..\u002Fconventions\u002Fschema-evolution.md) for \"when to add a type vs alias vs prefix\" — the heuristic.\n\n## When to invoke\n\nInvoke when the user (or a sibling skill) says any of:\n- \"Add a `researcher` type to my schema\"\n- \"I have 4000 untyped pages under `meetings\u002F`\"\n- \"My brain doesn't know that `journal-article` is a type\"\n- \"Set `paper` to be extractable\"\n- \"Propose types from what I've ingested\"\n- \"Sync the new types to backfill existing pages\"\n\nDON'T invoke for \"where does THIS note go\" (use brain-taxonomist) or\n\"who knows about X\" (use expert-routing \u002F `gbrain whoknows`).\n\n## Tutorial + vision\n\n- **Why this matters:** [`docs\u002Fwhat-schemas-unlock.md`](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fwhat-schemas-unlock.md) — 7 killer use cases (4000 invisible meetings made queryable, founder ops brain, research brain, legal brain, team brain, agent-as-co-curator) plus the structural argument for why types matter at query time. Read this before pitching schema authoring to a user — it's the doc that explains the difference between a pile of notes and a brain with structure.\n- **5-minute walkthrough:** [`docs\u002Fschema-author-tutorial.md`](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fschema-author-tutorial.md) — fork the bundled pack, add a researcher type, sync, prove the T1.5 wiring via `gbrain whoknows`. Use placeholder pages so it runs against any brain without affecting real content.\n\n## Workflow\n\n### Phase 1 — Brain (know which pack is active)\n\n```\ngbrain schema active --json\n```\n\nOutput gives you `pack_name`, `version`, `sha8`, `page_types_count`, `source_tier`.\nIf `source_tier === \"default\"`, the user is on bundled `gbrain-base` and any\nmutation will need a fork first (Phase 4).\n\n### Phase 2 — Assess (what does the current pack cover?)\n\n```\ngbrain schema stats --json\n```\n\nReturns per-type page counts, untyped count, and `dead_prefixes` (pack-\ndeclared prefixes with zero matching pages — probable mis-declarations).\nIf coverage \u003C 90%, there's untyped content worth typing.\n\n```\ngbrain schema review-orphans --json\n```\n\nUntyped pages drilldown. Look for shared path prefixes (e.g. \"12 of these\nare under `research\u002Fpapers\u002F`\") — those are candidates for a new type.\n\n### Phase 3 — Propose (what types should the pack add?)\n\n```\ngbrain schema detect --json\n```\n\nClusters pages by `source_path` and proposes candidate types. Heuristic\nonly (no LLM call).\n\n```\ngbrain schema suggest --json\n```\n\nLLM-refined candidates with confidence scores. Use the top-3 hit rate as\nthe signal for which to promote.\n\n### Phase 4 — Apply (mutate the pack)\n\nIf the active pack is bundled (`gbrain-base` or `gbrain-recommended`),\nfork it first:\n\n```\ngbrain schema fork gbrain-base mine\ngbrain schema use mine\n```\n\nThen add the types one at a time:\n\n```\ngbrain schema add-type researcher \\\n  --primitive entity \\\n  --prefix people\u002Fresearchers\u002F \\\n  --extractable \\\n  --expert\n```\n\nFor complex multi-mutation refactors (e.g. add a type AND the link verb\nthat points to it), agents reaching this surface over MCP can use the\nbatched `schema_apply_mutations` op:\n\n```jsonl\n{\"op\": \"add_type\", \"name\": \"researcher\", \"primitive\": \"entity\", \"prefix\": \"people\u002Fresearchers\u002F\", \"extractable\": true, \"expert_routing\": true}\n{\"op\": \"add_type\", \"name\": \"paper\", \"primitive\": \"annotation\", \"prefix\": \"research\u002Fpapers\u002F\", \"extractable\": true}\n{\"op\": \"add_link_type\", \"name\": \"authored\", \"inference\": {\"page_type\": \"researcher\", \"target_type\": \"paper\"}}\n```\n\nValidate before sync:\n\n```\ngbrain schema lint --with-db\n```\n\nThe `--with-db` flag opts into the 4 DB-aware rules\n(`extractable_empty_corpus`, `mutation_count_anomaly`,\n`stored_type_is_alias`, `stored_type_undeclared`) that detect\nmis-declared types you'd otherwise discover only at runtime.\n\n### Phase 5 — Sync (backfill existing pages with the new types)\n\nDry-run first:\n\n```\ngbrain schema sync --json\n```\n\nReturns per-prefix `would_apply` counts + sample slugs. If the numbers\nlook right:\n\n```\ngbrain schema sync --apply\n```\n\nChunked UPDATE in 1000-row batches; never wedges concurrent writers.\nIdempotent on re-run (second `--apply` finds nothing to backfill).\n\n### Phase 6 — Verify\n\n```\ngbrain schema stats --json\n```\n\nCoverage should be ≥95% now. Spot-check the new type:\n\n```\ngbrain whoknows \"machine learning\"\n```\n\nIf `researcher` was declared `--expert`, results should include\nresearcher-typed pages. (The pack-aware wiring at the query path was\nadded in v0.40.6.0 — pre-v0.40.6 brains silently ignored custom\nexpert-routed types.)\n\n### Phase 7 — Commit (preserve the change)\n\nIf the pack is in source control, commit and push only the pack file:\n\n```\ncd ~\u002F.gbrain\u002Fschema-packs\u002Fmine\ngbrain git commit-push -m \"schema: add researcher + paper types + authored link\" -- pack.json\n```\n\nIt takes the checkout's writer lock and merges a rejected push without\nrebasing, so it is safe when other agents share the checkout. On a non-zero\nexit: retry once on `commit_lock_busy`; on `integrate_conflict` stop and ask\nthe user which version of `pack.json` wins; on `git_push_unavailable` the\nremote is unreachable (the commit is saved; rerun with `--push-only` later) or,\nwhen the pack repo has no remote at all, nothing was committed: commit just the\npack locally with `git add pack.json && git commit -m \"\u003Cmsg>\" -- pack.json`. Never fall back to\nstash, `pull --rebase` or a plain push ([outcomes](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fguides\u002Fshared-checkout-git.md#outcomes)).\n\nIf the brain daemon is running (`gbrain serve --http`), other processes\npick up the change within 1 second (stat-mtime TTL gate in\nloadActivePack — v0.40.6.0 closed the cross-process invalidation gap).\n\n## Outputs\n\n- Mutated pack file at `~\u002F.gbrain\u002Fschema-packs\u002F\u003Cname>\u002Fpack.{json,yaml}`.\n- Audit row in `~\u002F.gbrain\u002Faudit\u002Fschema-mutations-YYYY-Www.jsonl` per mutation.\n- `pages.type` backfilled on matching rows after `sync --apply`.\n- Query paths (`whoknows`, `find_experts`) now route through the new\n  expert types.\n\n## Contract\n\n- **Inputs:** a natural-language request that names a type \u002F prefix \u002F link verb \u002F flag change, OR the result of `gbrain schema review-orphans` showing untyped pages that need a new type.\n- **Outputs:** mutated pack file at `~\u002F.gbrain\u002Fschema-packs\u002F\u003Cname>\u002Fpack.{json,yaml}` + an audit row in `~\u002F.gbrain\u002Faudit\u002Fschema-mutations-YYYY-Www.jsonl` + (if `sync --apply` ran) backfilled `pages.type` on matching rows.\n- **Side effects:** invalidates the in-process pack cache + the query cache for the source. Other processes pick up the change within 1 second (stat-mtime TTL).\n- **Idempotency:** every primitive is idempotent. `add-alias`\u002F`add-prefix` no-op on duplicate; `sync --apply` finds nothing to update on second run.\n- **Trust:** CLI = local trust (no scope check). MCP = OAuth `admin` scope (write ops). Audit log captures `actor: mcp:\u003CclientId8>` per mutation.\n- **Atomicity:** every mutation is wrapped in `withMutation`'s atomic write (`.tmp + fsync + rename`) + per-pack `O_CREAT|O_EXCL` lock. Crash mid-write leaves the original file untouched.\n\n## When it fails\n\nFollow the [agent operator protocol](..\u002Fconventions\u002Fagent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill:\n\n- Mutation codes: `PACK_READONLY` → fork first (`gbrain schema fork gbrain-base mine`); `STILL_REFERENCED` → remove the named references first; `LOCK_BUSY` → wait about 30 seconds and retry.\n- Over MCP, a mutation returns `insufficient_scope`: schema writes need the `admin` scope, which only the brain host's operator grants; tell the user.\n- The pre-write lint gate rejects a change: read the error, fix the named prefix or alias collision, and re-run; never bypass lint.\n\n## Anti-Patterns\n\n- **Don't mutate `gbrain-base` or `gbrain-recommended`.** Fork first (`gbrain schema fork gbrain-base mine`). These are bundled packs; edits would be lost on upgrade. The mutation primitives refuse with `PACK_READONLY`.\n- **Don't add a type for a directory you imported once for triage.** Pack types are permanent decisions; one-time imports are not. See `skills\u002Fconventions\u002Fschema-evolution.md` for the \u003C20-pages-don't-pack-codify heuristic.\n- **Don't add `--expert` to a type with no `path_prefixes`.** The `expert_routing_without_prefix` lint warns about this — expert-routed types with no prefix never match a put_page inference, so `whoknows` silently never surfaces them.\n- **Don't promote a `schema suggest` candidate without verifying the prefix matches real content.** Run `lint --with-db` before `add-type` to catch prefix collisions pre-write.\n- **Don't conflate \"filing one page\" with \"evolving the schema.\"** Filing routes via `brain-taxonomist`; schema-author is for authoring the type taxonomy itself. The Non-goals section above names the boundary.\n- **Don't skip the dry-run before `sync --apply`.** Always run `sync` first to see `would_apply` counts + sample slugs. A pack prefix that matches 50,000 pages is recoverable but slow; verifying first is cheap.\n- **Don't remove a type without checking references.** `remove-type` refuses with `STILL_REFERENCED` if another type's `aliases` \u002F `enrichable_types` \u002F `link_types` \u002F `frontmatter_links` references it. Break the references first; don't add `--force`.\n\n## Output Format\n\nWhen invoked, this skill produces structured output suitable for both human + JSON consumption:\n\n**Per-mutation result (JSON):**\n```json\n{\"schema_version\": 1, \"pack\": \"mine\", \"path\": \"~\u002F.gbrain\u002Fschema-packs\u002Fmine\u002Fpack.json\", \"format\": \"json\", \"prev_sha8\": \"a1b2c3d4\", \"new_sha8\": \"e5f6g7h8\"}\n```\n\n**Per-batch result (from `schema_apply_mutations` MCP op):**\n```json\n{\"schema_version\": 1, \"pack\": \"mine\", \"batch_id\": \"batch-1716491400-abc123\", \"mutations_applied\": 3, \"results\": [{...}, {...}, {...}]}\n```\n\n**Stats JSON (per-source + aggregate + dead-prefix hints):**\n```json\n{\"schema_version\": 1, \"pack_identity\": \"mine@1.0.0+abc12345\", \"aggregate\": {\"total_pages\": 4823, \"typed_pages\": 4710, \"untyped_pages\": 113, \"coverage\": 0.9766, \"by_type\": [{\"type\": \"person\", \"count\": 2104}, ...]}, \"per_source\": [...], \"dead_prefixes\": [{\"type\": \"researcher\", \"prefix\": \"people\u002Fresearchers\u002F\"}]}\n```\n\n**Sync dry-run JSON:**\n```json\n{\"schema_version\": 1, \"apply\": false, \"pack_identity\": \"mine@1.0.0+abc12345\", \"per_prefix\": [{\"type\": \"meeting\", \"prefix\": \"meetings\u002F\", \"would_apply\": 4000, \"sample_slugs\": [\"meetings\u002F2026-01-01-foo\", ...], \"dead_prefix\": false, \"applied\": 0}], \"total_would_apply\": 4000, \"total_applied\": 0}\n```\n\n**Human output (the agent's final summary):**\n- One line per mutation: `Pack: \u003Cname> (\u003Cformat>)` and `Sha8: \u003Cprev> → \u003Cnew>`\n- Stats: total pages, typed %, untyped count, per-type breakdown, dead-prefix list\n- Sync: per-prefix `would_apply`\u002F`applied` count + sample slugs in dry-run mode\n\nOn failure, the error envelope follows the standard `StructuredAgentError` shape: `{error, code, message, details?}`. Codes from the mutation primitives: `PACK_NOT_FOUND`, `PACK_READONLY`, `PACK_CORRUPT`, `TYPE_EXISTS`, `TYPE_NOT_FOUND`, `INVALID_PRIMITIVE`, `INVALID_RESULT`, `IO_ERROR`, `STILL_REFERENCED`, `LOCK_BUSY`.\n\n## Failure modes\n\n- `PACK_READONLY` → you tried to mutate `gbrain-base` or `gbrain-recommended`. Fork first.\n- `INVALID_RESULT` → the mutation would create a dangling reference or\n  prefix collision. The pre-write lint gate caught it. Read the error\n  message; the lint rule name names the problem.\n- `STILL_REFERENCED` → you tried to remove a type that another type's\n  `aliases` \u002F `enrichable_types` \u002F `link_types` \u002F `frontmatter_links`\n  references. The error names every reference. Remove those first.\n- `LOCK_BUSY` → another process is mid-mutation. Wait 30s and retry, or\n  pass `--force` if you know the holder is wedged.\n- `permission_denied` (MCP only) → your OAuth client doesn't have `admin`\n  scope. Re-register with `gbrain auth register-client --scopes admin`.\n","# schema-author — evolve your schema pack\n\n## Non-goals (use these other skills instead)\n\nThis skill AUTHORS the schema pack (adds page types, link verbs, prefixes,\nflags). For these adjacent jobs, route elsewhere:\n\n- **Filing one specific page** → `skills\u002Fbrain-taxonomist\u002FSKILL.md`. Brain-\n  taxonomist routes at WRITE TIME (\"where does this note go?\"). schema-author\n  changes the rules at AUTHORING TIME (\"what types and prefixes exist?\").\n- **Schema-check as part of EIIRP iteration** → `skills\u002Feiirp\u002FSKILL.md`\n  already has a schema-check phase. Don't duplicate.\n- **Just looking up a type's settings** → `gbrain schema explain \u003Ctype>`\n  directly. This skill is for CHANGING the pack, not READING from it.\n- **Querying who knows about X** → `gbrain whoknows \u003Ctopic>` directly.\n  schema-author makes a type expert-routable; it does not run the query.\n\n## Convention\n\n> **Convention:** see [conventions\u002Fbrain-first.md](..\u002Fconventions\u002Fbrain-first.md) for the lookup chain (search → query → get_page → external).\n\n> **Convention:** see [conventions\u002Fschema-evolution.md](..\u002Fconventions\u002Fschema-evolution.md) for \"when to add a type vs alias vs prefix\" — the heuristic.\n\n## When to invoke\n\nInvoke when the user (or a sibling skill) says any of:\n- \"Add a `researcher` type to my schema\"\n- \"I have 4000 untyped pages under `meetings\u002F`\"\n- \"My brain doesn't know that `journal-article` is a type\"\n- \"Set `paper` to be extractable\"\n- \"Propose types from what I've ingested\"\n- \"Sync the new types to backfill existing pages\"\n\nDON'T invoke for \"where does THIS note go\" (use brain-taxonomist) or\n\"who knows about X\" (use expert-routing \u002F `gbrain whoknows`).\n\n## Tutorial + vision\n\n- **Why this matters:** [`docs\u002Fwhat-schemas-unlock.md`](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fwhat-schemas-unlock.md) — 7 killer use cases (4000 invisible meetings made queryable, founder ops brain, research brain, legal brain, team brain, agent-as-co-curator) plus the structural argument for why types matter at query time. Read this before pitching schema authoring to a user — it's the doc that explains the difference between a pile of notes and a brain with structure.\n- **5-minute walkthrough:** [`docs\u002Fschema-author-tutorial.md`](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fschema-author-tutorial.md) — fork the bundled pack, add a researcher type, sync, prove the T1.5 wiring via `gbrain whoknows`. Use placeholder pages so it runs against any brain without affecting real content.\n\n## Workflow\n\n### Phase 1 — Brain (know which pack is active)\n\n```\ngbrain schema active --json\n```\n\nOutput gives you `pack_name`, `version`, `sha8`, `page_types_count`, `source_tier`.\nIf `source_tier === \"default\"`, the user is on bundled `gbrain-base` and any\nmutation will need a fork first (Phase 4).\n\n### Phase 2 — Assess (what does the current pack cover?)\n\n```\ngbrain schema stats --json\n```\n\nReturns per-type page counts, untyped count, and `dead_prefixes` (pack-\ndeclared prefixes with zero matching pages — probable mis-declarations).\nIf coverage \u003C 90%, there's untyped content worth typing.\n\n```\ngbrain schema review-orphans --json\n```\n\nUntyped pages drilldown. Look for shared path prefixes (e.g. \"12 of these\nare under `research\u002Fpapers\u002F`\") — those are candidates for a new type.\n\n### Phase 3 — Propose (what types should the pack add?)\n\n```\ngbrain schema detect --json\n```\n\nClusters pages by `source_path` and proposes candidate types. Heuristic\nonly (no LLM call).\n\n```\ngbrain schema suggest --json\n```\n\nLLM-refined candidates with confidence scores. Use the top-3 hit rate as\nthe signal for which to promote.\n\n### Phase 4 — Apply (mutate the pack)\n\nIf the active pack is bundled (`gbrain-base` or `gbrain-recommended`),\nfork it first:\n\n```\ngbrain schema fork gbrain-base mine\ngbrain schema use mine\n```\n\nThen add the types one at a time:\n\n```\ngbrain schema add-type researcher \\\n  --primitive entity \\\n  --prefix people\u002Fresearchers\u002F \\\n  --extractable \\\n  --expert\n```\n\nFor complex multi-mutation refactors (e.g. add a type AND the link verb\nthat points to it), agents reaching this surface over MCP can use the\nbatched `schema_apply_mutations` op:\n\n```jsonl\n{\"op\": \"add_type\", \"name\": \"researcher\", \"primitive\": \"entity\", \"prefix\": \"people\u002Fresearchers\u002F\", \"extractable\": true, \"expert_routing\": true}\n{\"op\": \"add_type\", \"name\": \"paper\", \"primitive\": \"annotation\", \"prefix\": \"research\u002Fpapers\u002F\", \"extractable\": true}\n{\"op\": \"add_link_type\", \"name\": \"authored\", \"inference\": {\"page_type\": \"researcher\", \"target_type\": \"paper\"}}\n```\n\nValidate before sync:\n\n```\ngbrain schema lint --with-db\n```\n\nThe `--with-db` flag opts into the 4 DB-aware rules\n(`extractable_empty_corpus`, `mutation_count_anomaly`,\n`stored_type_is_alias`, `stored_type_undeclared`) that detect\nmis-declared types you'd otherwise discover only at runtime.\n\n### Phase 5 — Sync (backfill existing pages with the new types)\n\nDry-run first:\n\n```\ngbrain schema sync --json\n```\n\nReturns per-prefix `would_apply` counts + sample slugs. If the numbers\nlook right:\n\n```\ngbrain schema sync --apply\n```\n\nChunked UPDATE in 1000-row batches; never wedges concurrent writers.\nIdempotent on re-run (second `--apply` finds nothing to backfill).\n\n### Phase 6 — Verify\n\n```\ngbrain schema stats --json\n```\n\nCoverage should be ≥95% now. Spot-check the new type:\n\n```\ngbrain whoknows \"machine learning\"\n```\n\nIf `researcher` was declared `--expert`, results should include\nresearcher-typed pages. (The pack-aware wiring at the query path was\nadded in v0.40.6.0 — pre-v0.40.6 brains silently ignored custom\nexpert-routed types.)\n\n### Phase 7 — Commit (preserve the change)\n\nIf the pack is in source control, commit and push only the pack file:\n\n```\ncd ~\u002F.gbrain\u002Fschema-packs\u002Fmine\ngbrain git commit-push -m \"schema: add researcher + paper types + authored link\" -- pack.json\n```\n\nIt takes the checkout's writer lock and merges a rejected push without\nrebasing, so it is safe when other agents share the checkout. On a non-zero\nexit: retry once on `commit_lock_busy`; on `integrate_conflict` stop and ask\nthe user which version of `pack.json` wins; on `git_push_unavailable` the\nremote is unreachable (the commit is saved; rerun with `--push-only` later) or,\nwhen the pack repo has no remote at all, nothing was committed: commit just the\npack locally with `git add pack.json && git commit -m \"\u003Cmsg>\" -- pack.json`. Never fall back to\nstash, `pull --rebase` or a plain push ([outcomes](https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fdocs\u002Fguides\u002Fshared-checkout-git.md#outcomes)).\n\nIf the brain daemon is running (`gbrain serve --http`), other processes\npick up the change within 1 second (stat-mtime TTL gate in\nloadActivePack — v0.40.6.0 closed the cross-process invalidation gap).\n\n## Outputs\n\n- Mutated pack file at `~\u002F.gbrain\u002Fschema-packs\u002F\u003Cname>\u002Fpack.{json,yaml}`.\n- Audit row in `~\u002F.gbrain\u002Faudit\u002Fschema-mutations-YYYY-Www.jsonl` per mutation.\n- `pages.type` backfilled on matching rows after `sync --apply`.\n- Query paths (`whoknows`, `find_experts`) now route through the new\n  expert types.\n\n## Contract\n\n- **Inputs:** a natural-language request that names a type \u002F prefix \u002F link verb \u002F flag change, OR the result of `gbrain schema review-orphans` showing untyped pages that need a new type.\n- **Outputs:** mutated pack file at `~\u002F.gbrain\u002Fschema-packs\u002F\u003Cname>\u002Fpack.{json,yaml}` + an audit row in `~\u002F.gbrain\u002Faudit\u002Fschema-mutations-YYYY-Www.jsonl` + (if `sync --apply` ran) backfilled `pages.type` on matching rows.\n- **Side effects:** invalidates the in-process pack cache + the query cache for the source. Other processes pick up the change within 1 second (stat-mtime TTL).\n- **Idempotency:** every primitive is idempotent. `add-alias`\u002F`add-prefix` no-op on duplicate; `sync --apply` finds nothing to update on second run.\n- **Trust:** CLI = local trust (no scope check). MCP = OAuth `admin` scope (write ops). Audit log captures `actor: mcp:\u003CclientId8>` per mutation.\n- **Atomicity:** every mutation is wrapped in `withMutation`'s atomic write (`.tmp + fsync + rename`) + per-pack `O_CREAT|O_EXCL` lock. Crash mid-write leaves the original file untouched.\n\n## When it fails\n\nFollow the [agent operator protocol](..\u002Fconventions\u002Fagent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill:\n\n- Mutation codes: `PACK_READONLY` → fork first (`gbrain schema fork gbrain-base mine`); `STILL_REFERENCED` → remove the named references first; `LOCK_BUSY` → wait about 30 seconds and retry.\n- Over MCP, a mutation returns `insufficient_scope`: schema writes need the `admin` scope, which only the brain host's operator grants; tell the user.\n- The pre-write lint gate rejects a change: read the error, fix the named prefix or alias collision, and re-run; never bypass lint.\n\n## Anti-Patterns\n\n- **Don't mutate `gbrain-base` or `gbrain-recommended`.** Fork first (`gbrain schema fork gbrain-base mine`). These are bundled packs; edits would be lost on upgrade. The mutation primitives refuse with `PACK_READONLY`.\n- **Don't add a type for a directory you imported once for triage.** Pack types are permanent decisions; one-time imports are not. See `skills\u002Fconventions\u002Fschema-evolution.md` for the \u003C20-pages-don't-pack-codify heuristic.\n- **Don't add `--expert` to a type with no `path_prefixes`.** The `expert_routing_without_prefix` lint warns about this — expert-routed types with no prefix never match a put_page inference, so `whoknows` silently never surfaces them.\n- **Don't promote a `schema suggest` candidate without verifying the prefix matches real content.** Run `lint --with-db` before `add-type` to catch prefix collisions pre-write.\n- **Don't conflate \"filing one page\" with \"evolving the schema.\"** Filing routes via `brain-taxonomist`; schema-author is for authoring the type taxonomy itself. The Non-goals section above names the boundary.\n- **Don't skip the dry-run before `sync --apply`.** Always run `sync` first to see `would_apply` counts + sample slugs. A pack prefix that matches 50,000 pages is recoverable but slow; verifying first is cheap.\n- **Don't remove a type without checking references.** `remove-type` refuses with `STILL_REFERENCED` if another type's `aliases` \u002F `enrichable_types` \u002F `link_types` \u002F `frontmatter_links` references it. Break the references first; don't add `--force`.\n\n## Output Format\n\nWhen invoked, this skill produces structured output suitable for both human + JSON consumption:\n\n**Per-mutation result (JSON):**\n```json\n{\"schema_version\": 1, \"pack\": \"mine\", \"path\": \"~\u002F.gbrain\u002Fschema-packs\u002Fmine\u002Fpack.json\", \"format\": \"json\", \"prev_sha8\": \"a1b2c3d4\", \"new_sha8\": \"e5f6g7h8\"}\n```\n\n**Per-batch result (from `schema_apply_mutations` MCP op):**\n```json\n{\"schema_version\": 1, \"pack\": \"mine\", \"batch_id\": \"batch-1716491400-abc123\", \"mutations_applied\": 3, \"results\": [{...}, {...}, {...}]}\n```\n\n**Stats JSON (per-source + aggregate + dead-prefix hints):**\n```json\n{\"schema_version\": 1, \"pack_identity\": \"mine@1.0.0+abc12345\", \"aggregate\": {\"total_pages\": 4823, \"typed_pages\": 4710, \"untyped_pages\": 113, \"coverage\": 0.9766, \"by_type\": [{\"type\": \"person\", \"count\": 2104}, ...]}, \"per_source\": [...], \"dead_prefixes\": [{\"type\": \"researcher\", \"prefix\": \"people\u002Fresearchers\u002F\"}]}\n```\n\n**Sync dry-run JSON:**\n```json\n{\"schema_version\": 1, \"apply\": false, \"pack_identity\": \"mine@1.0.0+abc12345\", \"per_prefix\": [{\"type\": \"meeting\", \"prefix\": \"meetings\u002F\", \"would_apply\": 4000, \"sample_slugs\": [\"meetings\u002F2026-01-01-foo\", ...], \"dead_prefix\": false, \"applied\": 0}], \"total_would_apply\": 4000, \"total_applied\": 0}\n```\n\n**Human output (the agent's final summary):**\n- One line per mutation: `Pack: \u003Cname> (\u003Cformat>)` and `Sha8: \u003Cprev> → \u003Cnew>`\n- Stats: total pages, typed %, untyped count, per-type breakdown, dead-prefix list\n- Sync: per-prefix `would_apply`\u002F`applied` count + sample slugs in dry-run mode\n\nOn failure, the error envelope follows the standard `StructuredAgentError` shape: `{error, code, message, details?}`. Codes from the mutation primitives: `PACK_NOT_FOUND`, `PACK_READONLY`, `PACK_CORRUPT`, `TYPE_EXISTS`, `TYPE_NOT_FOUND`, `INVALID_PRIMITIVE`, `INVALID_RESULT`, `IO_ERROR`, `STILL_REFERENCED`, `LOCK_BUSY`.\n\n## Failure modes\n\n- `PACK_READONLY` → you tried to mutate `gbrain-base` or `gbrain-recommended`. Fork first.\n- `INVALID_RESULT` → the mutation would create a dangling reference or\n  prefix collision. The pre-write lint gate caught it. Read the error\n  message; the lint rule name names the problem.\n- `STILL_REFERENCED` → you tried to remove a type that another type's\n  `aliases` \u002F `enrichable_types` \u002F `link_types` \u002F `frontmatter_links`\n  references. The error names every reference. Remove those first.\n- `LOCK_BUSY` → another process is mid-mutation. Wait 30s and retry, or\n  pass `--force` if you know the holder is wedged.\n- `permission_denied` (MCP only) → your OAuth client doesn't have `admin`\n  scope. Re-register with `gbrain auth register-client --scopes admin`.\n",{"name":5,"tools":56,"triggers":90,"brain_first":105,"description":7,"when_to_use":106,"writes_pages":52},[57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89],"gbrain schema active","gbrain schema list","gbrain schema stats","gbrain schema review-orphans","gbrain schema detect","gbrain schema suggest","gbrain schema lint","gbrain schema graph","gbrain schema explain","gbrain schema fork","gbrain schema use","gbrain schema add-type","gbrain schema remove-type","gbrain schema update-type","gbrain schema add-alias","gbrain schema remove-alias","gbrain schema add-prefix","gbrain schema remove-prefix","gbrain schema add-link-type","gbrain schema remove-link-type","gbrain schema set-extractable","gbrain schema set-expert-routing","gbrain schema sync","gbrain schema reload","mcp:get_active_schema_pack","mcp:list_schema_packs","mcp:schema_stats","mcp:schema_lint","mcp:schema_graph","mcp:schema_explain_type","mcp:schema_review_orphans","mcp:schema_apply_mutations","mcp:reload_schema_pack",[91,92,93,94,95,96,97,98,99,100,101,102,103,104,30],"add a page type","add a type to my schema","my brain has untyped pages","schema isn't matching my notes","propose new types from my corpus","backfill page types","evolve my schema","extend the schema pack","create a custom type for","researcher type","make X an expert type","schema pack add","schema mutate","schema sync","exempt","Use when the user asks: \"add a page type\", \"add a type to my schema\", \"my brain has untyped pages\", \"schema isn't matching my notes\", \"propose new types from my corpus\".","master","074ec301549ded4930f04d2c3b22d709a6c095cc","plugin\u002Fskills\u002Fschema-author",4902,"https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain","https:\u002F\u002Fgithub.com\u002Fgarrytan","https:\u002F\u002Fblog.garrytan.com","Writes software, dreams. ","2026-11-14 04:11:30",{"source":8,"skillName":5,"commands":117,"prompt":127,"zipAvailable":128},[118,121,124],{"tool":119,"command":120},"npx","npx skills add garrytan\u002Fgbrain --skill schema-author",{"tool":122,"command":123},"bunx","bunx skills add garrytan\u002Fgbrain --skill schema-author",{"tool":125,"command":126},"pnpm","pnpm dlx skills add garrytan\u002Fgbrain --skill schema-author","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Fplugin\u002Fskills\u002Fschema-author\u002FSKILL.md",true,[],[131,143,149,171,196,210],{"skillNo":132,"name":133,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":136,"publishedAt":51},"01M6N109FNGH1PK49T734PZXGB","query-helper","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog\u002Fskills\u002Fquery-helper\u002FSKILL.md",[],[137,138,139,140,141,142,37],"query helper","helper","query","search","page","find",{"skillNo":144,"name":145,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":146,"categories":147,"keywords":148,"publishedAt":51},"01M6N108A23GW6NGQEQ0E7GV0A","broken","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog\u002Fskills\u002Fbroken\u002FSKILL.md",[],[145],{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":51},"01M6N105E88C5K2H03H0CC79G1","brain-ops","Read, enrich, and write brain pages with source attribution.","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog\u002Fskills\u002Fbrain-ops\u002FSKILL.md",[],[156,38,157,158,159,141,160,161,162,163,139,164,165,166,167,168,169,170,140],"brain ops","ops","true","attribution","read","write","up","look","pages","people","with","enrich","web","path","source",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":180,"publishedAt":51},"01M6N102GRMF22TVCNT6RK5MRD","meeting-prep","Build a briefing before you meet someone, from their recent threads, open loops and what they care about.","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog-query\u002Fskills\u002Fmeeting-prep\u002FSKILL.md",[177],{"categoryNo":178,"categoryName":179,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000034","行政与办公人员",[181,182,183,184,185,140,186,187,188,139,37,189,190,191,192,193,194,195],"meeting","prep","meeting prep","me","prepare","brief","open","build","loops","about","you","briefing","threads","for","Meet",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":202,"publishedAt":51},"01M6N1005QK7REHX5KGMNR5PF0","inbox-zero","Triage the inbox into replies, delegations and archives.","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog-query\u002Fskills\u002Finbox-zero\u002FSKILL.md",[],[203,204,205,140,206,37,207,208,209],"inbox zero","ZeRO","inbox","clear","replies","my","triage",{"skillNo":211,"name":212,"nameZh":6,"description":213,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":214,"categories":215,"keywords":216,"publishedAt":51},"01M6N0ZXQ8RRRW71PNV61T57GP","deal-memo","Draft an investment memo from the deal pages and the founder history already in the brain.","https:\u002F\u002Fgithub.com\u002Fgarrytan\u002Fgbrain\u002Fblob\u002Fmaster\u002Ftest\u002Ffixtures\u002Fskill-catalog-query\u002Fskills\u002Fdeal-memo\u002FSKILL.md",[],[217,218,219,164,38,220,221,161,222,158,140,223],"deal memo","deal","memo","draft","investment","history","founder"]