| rule | name | what it checks |
|---|---|---|
| S005 | body-size-budget | SKILL.md body over 500 lines defeats progressive disclosure |
| S006 | referenced-files-exist | Files referenced from SKILL.md must exist in the package |
| S007 | no-orphan-files | Bundled files never mentioned in SKILL.md are dead weight the agent will never use |
| S008 | parseable-frontmatter | SKILL.md must begin with valid YAML frontmatter |
| S009 | trigger-guidance | Description should state when to use the skill, not only what it does |
| S011 | no-markup-in-description | Description must not contain XML/HTML tags (prompt-injection surface) |
| S014 | third-person-description | Description should be written in third person, not first person |
| S016 | no-rigid-command-sequence | Long fixed command sequences over-prescribe execution; state the goal or ship a script |
| S018 | has-example | A substantial skill should include at least one concrete example |
202 203## Related skills204 205- `skills/perplexity-research/SKILL.md` — the actual web-search engine206 this skill routes through (D7/α: pure routing, no new infrastructure)207- `skills/citation-fixer/SKILL.md` — fixes citation FORMATTING; this208 skill checks whether the cited claim is true209- `skills/conventions/quality.md` — citation + back-link rules210 211 212## Contract
222 223## Output Format224 225The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: archive-crawler3version: 0.1.04description: Universal archivist for personal file archives (Dropbox/B2/Gmail-takeout/local-mount/hard-drive-dump). Filters for high-value content (the user's own writing, ideas, relationships) and surfaces it interactively. REFUSES TO RUN without an explicit gbrain.yml `archive-crawler.scan_paths:` allow-list.
54This is a safety fence — the agent will not infer what's safe to read.55```56 57This contract is enforced by `src/core/storage-config.ts` (mirrors the58`db_tracked` / `db_only` allow-list pattern from v0.22.11 storage tiering).59 60## What this is
201 202### `.doc` / `.docx`203 204```bash205# .docx (modern)206python3 -c "207import zipfile, xml.etree.ElementTree as ET
216 217### `.pst` (Outlook archives)218 219```bash220# Validate first; many PSTs are null bytes221python3 -c "222with open('/path/to/file.pst', 'rb') as f:
297 298## Related skills299 300- `skills/voice-note-ingest/SKILL.md` — same exact-phrasing pattern for301 audio capture302- `skills/idea-ingest/SKILL.md` — single-link-or-article ingest with303 the same primary-subject filing rule304- `skills/conventions/quality.md` — citations, back-links, voice305 306 307## Contract
317 318## Output Format319 320The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: article-enrichment3version: 0.1.04description: Transform raw article text dumps in the brain into structured pages with executive summary, verbatim quotes, key insights, why-it-matters, and cross-references. Replaces walls-of-text with quotable, actionable brain pages.
128 129## Related skills130 131- `skills/media-ingest/SKILL.md` — creates the raw article pages this skill enriches132- `skills/idea-ingest/SKILL.md` — link/article ingestion with author people-page enforcement133- `skills/conventions/quality.md` — citation + back-link rules134 135 136## Contract
146 147## Output Format148 149The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: ask-user3version: 1.0.04description: |
1---2name: book-mirror3version: 0.1.04description: Take any book (EPUB/PDF), produce a personalized chapter-by-chapter analysis with two-column tables. Left column preserves the chapter content; right column maps every idea to the reader's actual life using brain context. Output is a single brain page at media/books/<slug>-personalized.md plus an optional PDF via brain-pdf.
94 95### EPUB96 97```bash98SLUG="this-book" # kebab-case99WORK="$(mktemp -d)/$SLUG"100mkdir -p "$WORK/chapters"
144- No HTML tags.145- Paragraphs preserved with `\n\n`.146 147Save a `chapters/INDEX.md` mapping chapter number → title → file → word148count for reference.149 150## 3. Context gathering
155### What to pull156 1571. **Templates: USER.md and SOUL.md** if the user maintains them158 (gbrain ships templates at `templates/USER.md` and `templates/SOUL.md`;159 they live in the brain repo when populated). Read full.1602. **Recent daily memory** — last 14 days of brain pages under161 `wiki/personal/reflections/` or wherever the user files daily notes.
174 175Write everything to a single file the CLI can read:176 177```bash178CONTEXT="$WORK/context.md"179{180 echo "## USER.md (if any)"
272 273- For every person the right column references with a brain page, add a274 back-link from `people/<slug>` to the new `media/books/<slug>-personalized`275 page (per `conventions/quality.md` Iron Law).276 277## Quality bar (the bar)278
323 324## Related skills325 326- `skills/brain-pdf/SKILL.md` — render the personalized page to PDF.327- `skills/strategic-reading/SKILL.md` — read a book through a specific328 problem-lens instead of personalizing to the whole reader.329- `skills/article-enrichment/SKILL.md` — same shape applied to articles330 rather than books.331 332
343 344## Output Format345 346The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).347 348## Anti-Patterns349
1---2name: brain-ops3version: 1.0.04description: |
31The brain is not an archive. It is a live context membrane that every interaction32flows through in both directions.33 34> **Convention:** See `skills/conventions/brain-first.md` for the 5-step lookup protocol.35> **Convention:** See `skills/conventions/quality.md` for citation and back-link rules.36 37## Contract38
1---2name: brain-pdf3version: 0.1.04description: Generate a publication-quality PDF from any brain page via the gstack make-pdf binary. Strips YAML frontmatter, sanitizes emoji, applies running headers and page numbers. Brain page is always the source of truth; PDF is a rendering.
66 67## Invocation68 69```bash70SLUG="path/to/page"71P="$HOME/.claude/skills/gstack/make-pdf/dist/pdf"72
163 164## Related skills165 166- `skills/book-mirror/SKILL.md` — produces a brain page that's a167 natural input to brain-pdf (chapter-by-chapter personalized analysis).168- `skills/strategic-reading/SKILL.md` — same shape, problem-lens variant.169- `skills/publish/SKILL.md` — share brain pages as password-protected170 HTML (different rendering target).171 172
183 184## Output Format185 186The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: brain-taxonomist3version: 1.0.04prompt_version: 1
191- Hardcoded directory table REMOVED. Every decision now reads the active192 schema pack via `gbrain schema show --json`. Single source of truth.193- Book taxonomy moved from skill-text to the `gbrain-recommended` pack's194 media/books/ branch (see `src/core/schema-pack/base/gbrain-recommended.yaml`).195- `--source <id>` propagation documented for multi-brain users (Persona B).
1---2name: briefing3description: Compile daily briefing with meeting context, active deals, and citation tracking4triggers:
19Compile a daily briefing from brain context.20 21> **Filing rule:** When the briefing creates or updates brain pages,22> follow `skills/_brain-filing-rules.md`.23 24## Contract25
1---2name: capture3description: Save any thought or content into the brain via one CLI command. The single human-facing entrypoint that replaces "put_page vs commit-then-sync vs autopilot-wait" with one command that just works.4triggers:
47 48## How to use49 50```bash51gbrain capture "the thought I want to remember"52gbrain capture --file ./notes/today.md53echo "from a pipe" | gbrain capture --stdin
97 98## When NOT to use this skill99 100- Bulk ingestion of many files → `skills/media-ingest/SKILL.md` or `gbrain sync` instead101- Article/link with author + publication metadata → `skills/idea-ingest/SKILL.md` (it knows to build the people page)102- Meeting transcripts → `skills/meeting-ingestion/SKILL.md` (attendee enrichment)103 104This skill is for the simple "I have a thought, save it" case. Specialized105ingestion paths handle their own slugging + cross-referencing.
1---2name: citation-fixer3version: 1.1.04description: |
51 - Citations with wrong format52 - **(v0.25.1)** Tweet references without `x.com` URLs533. **Fix format issues.** Rewrite malformed citations to match54 `conventions/quality.md`.554. **(v0.25.1) Resolve tweet references** via the X API integration.565. **Report results.** Count: pages scanned, citations found, issues57 fixed, tweets resolved, remaining gaps.
129 130### Find candidate pages131 132```bash133# Pages mentioning tweets but with no x.com links134for f in $(find . -name "*.md" -not -path "./node_modules/*"); do135 refs=$(grep -ci "tweet\|posted\|x post\|RT\|retweet\|said on X" "$f")
173- ❌ Removing facts that lack citations (flag them; don't delete).174- ❌ Fixing citations without reading the full page context.175- ❌ Batch-fixing without checking quality on a sample first176 (see `conventions/test-before-bulk.md`).177- ❌ Composing tweet URLs by guessing the tweet id. Always go through178 the X API; deterministic links only.179
205 206## Output Format207 208The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
151 152### Discovery153 154```bash155echo "=== Markdown Repository Discovery ==="156for dir in /data/* ~/git/* ~/Documents/* ~/notes/* ~/obsidian/* 2>/dev/null; do157 if [ -d "$dir" ]; then
1---2name: concept-synthesis3version: 0.1.04description: Deduplicate and synthesize raw concept stubs into a tiered intellectual map (T1 Canon to T4 Riff), tracing idea evolution across sources over time. Transforms thousands of raw concept pages into a curated intellectual fingerprint.
234 235## Related skills236 237- `skills/signal-detector/SKILL.md` — creates raw concept stubs from text channels238- `skills/voice-note-ingest/SKILL.md` — same for audio channels239- `skills/idea-ingest/SKILL.md` — same for links / articles240 241 242## Contract
252 253## Output Format254 255The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: cron-scheduler3version: 1.0.04description: |
18 19# Cron Scheduler20 21> **Convention:** See `skills/conventions/test-before-bulk.md` — test every cron job on 3-5 items first.22 23## Contract24
39 - Override: user-awake flag (if user is active, quiet hours suspended)40 - During quiet hours: save output to held queue41 - Morning contact releases the backlog424. **Register with host scheduler.** OpenClaw cron, Railway cron, crontab, or process manager. **Each registered entry should execute via Minions, not `agentTurn`.** See `skills/conventions/cron-via-minions.md` for the rewrite pattern (PGLite uses `--follow`, Postgres uses fire-and-forget + `--idempotency-key` on the cycle slot). GBrain's v0.11.0 migration auto-rewrites entries for built-in handlers; host-specific handlers need a code-level registration per `docs/guides/plugin-handlers.md`.435. **Write thin prompt.** Job prompt is one line: "Read skills/{name}/SKILL.md and run it."44 45## Idempotency Requirement
1---2name: cross-modal-review3version: 1.1.04description: |
130If the primary review model refuses:131 1321. Switch silently to the next model in the chain (see133 `conventions/cross-modal.yaml`).1342. Don't show the refusal to the user.1353. Don't announce the switch.1364. If ALL models in the chain refuse, escalate to the user.
187- gstack `/codex` — the actual Codex CLI wrapper this skill hands off188 to for diff-review mode. Cross-modal-review knows WHEN to invoke;189 /codex knows HOW.190- `skills/testing/SKILL.md` — runs the project test suite; complementary191 signal for "is this commit safe to land"192- `skills/conventions/cross-modal.yaml` — review pairs + refusal routing193 194 195## Output Format196 197The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: daily-task-manager3version: 1.0.04description: |
23## Contract24 25This skill guarantees:26- Tasks stored as a brain page (`ops/tasks.md`) with structured format27- Task lifecycle: add → in-progress → complete | defer28- Priority levels: P0 (urgent), P1 (today), P2 (this week), P3 (backlog)29- Completed tasks archived with completion date
1---2name: daily-task-prep3version: 1.0.04description: |
1---2name: data-research3version: 1.0.04description: |
135 136## Conventions137 138References `skills/conventions/quality.md` for citation and back-linking rules.
1---2name: eiirp3version: 1.0.04prompt_version: 1
279Confirm:280- [ ] All brain pages have proper frontmatter against active schema pack281- [ ] All entity pages are cross-linked282- [ ] Any new skills have routing entries in `skills/RESOLVER.md`283- [ ] No DRY violations (no duplicated logic across skills)284- [ ] No MECE violations (no ambiguous routing between skills)285- [ ] Active schema pack updated if new content types emerged
387 private fork names per CLAUDE.md privacy rules.388- Phase 3 SCHEMA CHECK rewritten to consume the v0.39 cathedral CLI389 (`detect | suggest | review-candidates`) instead of a private390 `brain/schema.md`.391- Phase 5 SKILL GRAPH AUDIT calls `gbrain check-resolvable` instead of392 upstream `scripts/skill-dry-check.mjs`.393- Phase 6 verification uses `gbrain doctor`'s schema_pack_consistency394 check (T7) for the persistent surface.
39- Tiered enrichment: Tier 1 (full), Tier 2 (medium), Tier 3 (minimal) based on notability40- No stubs: every new page has meaningful content from web search or existing brain context41 42> **Filing rule:** Read `skills/_brain-filing-rules.md` before creating any new page.43 44> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.45 46Every mention of a person or company with a brain page MUST create a back-link47FROM that entity's page TO the page mentioning them. An unlinked mention is a
1---2name: frontmatter-guard3version: 1.0.04description: |
19 20# Frontmatter Guard Skill21 22> **Convention:** see `skills/conventions/quality.md` for citation rules; this skill is structural validation, not citation auditing.23 24## Contract25
123## Chains with124 125- `gbrain doctor` — the `frontmatter_integrity` subcheck reports the same counts as `audit`.126- `skills/maintain/SKILL.md` — broader brain health audit; chain after this skill if other classes of issue are suspected.127- `skills/lint/SKILL.md` (via `gbrain lint`) — overlapping rules for skill-file lint; the `frontmatter-*` rule names in lint output come from this skill's validation surface.128 129## Output Format130
1---2name: functional-area-resolver3version: 1.0.04prompt_version: 1
73The LLM doesn't need one row per sub-skill. It needs:741. **Area recognition** — "this is about brain pages" -> Brain & Knowledge752. **Sub-skill visibility** — the `(dispatcher for: ...)` list shows what's available763. **The skill file itself** — once the LLM reads `brain-ops/SKILL.md`, it has full routing detail77 78This is a **two-layer dispatch**: routing file routes to the area, the area79skill routes to the specific sub-skill. Each layer does one job well.
121 122### Reproduce123 124```bash125cd evals/functional-area-resolver126node harness.mjs --model opus # ~225 LLM calls, ~$1.70 at Opus pricing127node harness.mjs --model sonnet # ~$1.00
174hierarchy at runtime via a second LLM call). Our finding — that the175hierarchy can be inlined into a single-LLM-pass dispatcher list and retain176routing accuracy — is the open contribution. See177`evals/functional-area-resolver/README.md` for methodology details.178 179## How To Compress180
190### Step 2: When to compress which file191 192GBrain workspaces often have TWO routing files merged at runtime (per193`src/core/check-resolvable.ts` v0.31.7): `skills/RESOLVER.md` and a sibling194`../AGENTS.md`. Choose which to compress:195 196- Only one is fat (>12KB): compress that one; leave the small one alone.197- Both are fat: compress them separately, in order: AGENTS.md first
260variants directory, then invoke the harness with `--variants` pointing261at it:262 263```bash264# In your agent workspace, identify the routing file you just compressed.265EDITED=/path/to/your/AGENTS.md # or skills/RESOLVER.md, whichever you edited266
299### Step 7: Review the diff before committing300 301Show the user the proposed edit (or the actual git diff) and wait for302explicit approval before staging. Same convention as `skills/book-mirror/SKILL.md`.303 304## Contract305
1---2name: gbrain-advisor3version: 1.0.04description: |
19 20# gbrain Advisor21 22> **Convention:** See `skills/conventions/brain-first.md`. This skill is the23> proactive voice of the brain — it tells the owner how to run it better.24 25## Contract
1---2name: gbrain-upgrade3description: |4 Keep gbrain current. When a `gbrain` invocation prints an
29 30# Idea Ingest Skill31 32> **Filing rule:** Read `skills/_brain-filing-rules.md` before creating any new page.33 34## Contract35
41- Every fact has an inline `[Source: ...]` citation42- Filing follows primary subject rules (not format-based)43 44> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.45 46Every mention of a person or company with a brain page MUST create a back-link.47Format: `- **YYYY-MM-DD** | Referenced in [page title](path) — brief context`
1---2name: idea-lineage3version: 0.1.04description: |
68This skill guarantees:69 70- A single-idea scope is preserved. Broad corpus or "map my concepts" prompts71 route to `skills/concept-synthesis/SKILL.md` instead.72- Every lineage claim cites existing brain evidence: page slug, source id when73 present, date, and short quote or snippet.74- Missing evidence is labeled as a gap, not patched with plausible narrative.
206## Related Skills and Operations207 208- `skills/concept-synthesis/SKILL.md` - broad mutating concept-map synthesis.209- `skills/query/SKILL.md` - general brain search and cited answers.210- `skills/brain-ops/SKILL.md` - source attribution and brain-first behavior.211- `find_trajectory` - structured typed-fact and event timelines for entities.212- `find_contradictions` - cached suspected contradiction findings.213
1---2name: ingest3description: Route content to specialized ingestion skills. Detects input type and delegates.4triggers:
26 27Ingest meetings, articles, media, documents, and conversations into the brain.28 29> **Filing rule:** Read `skills/_brain-filing-rules.md` before creating any new page.30 31## Contract32
36- State sections are rewritten with current best understanding, never appended to.37- Entity detection fires on every inbound message; notable entities get pages or updates.38 39> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.40 41Every mention of a person or company with a brain page MUST create a back-link42FROM that entity's page TO the page mentioning them. An unlinked mention is a
1# Install GBrain (Deprecated)2 3This skill has been replaced by the **setup** skill. See `skills/setup/SKILL.md`.4 5The setup skill provides:6- Auto-provision Supabase via CLI (< 2 min TTHW)
175```176 177**Invocation patterns:**178```bash179gbrain dream # full cycle180gbrain dream --phase synthesize # just synthesize181gbrain dream --phase patterns # just patterns
222# ship handler registrations in the host repo, then re-run apply-migrations.223```224 225Full troubleshooting guide: `docs/guides/minions-fix.md`.226 227### Back-link enforcement228Check that the back-linking iron law is being followed:
233- Format: `- **YYYY-MM-DD** | Referenced in [page title](path) -- brief context`234 235### Filing rule violations236Check for common misfiling patterns (see `skills/_brain-filing-rules.md`):237- Content with clear primary subjects filed in `sources/` instead of the238 appropriate directory (people/, companies/, concepts/, etc.)239- Use gbrain search to find pages in `sources/` that reference specific
1---2name: media-ingest3version: 1.0.04description: |
37 38Ingest video, audio, PDF, book, screenshot, and GitHub repo content into the brain.39 40> **Filing rule:** Read `skills/_brain-filing-rules.md` before creating any new page.41 42## Contract43
48- Raw source files preserved via `gbrain files upload-raw`49- Filing by primary subject, not by media format50 51> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.52 53Every mention of a person or company with a brain page MUST create a back-link.54
1---2name: meeting-ingestion3version: 1.0.04description: |
27 28# Meeting Ingestion Skill29 30> **Filing rule:** Read `skills/_brain-filing-rules.md` before creating any new page.31 32## Contract33
39- Meeting is NOT fully ingested until enrich runs for every entity40- Back-links created bidirectionally41 42> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.43 44Every attendee and company mentioned MUST get a back-link from their page to45the meeting page. An unlinked mention is a broken brain.
1---2name: migrate3description: Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam4triggers:
53 54When to route to Minions: durable, observable work that must survive restarts,55fan out across many parallel tasks, or persist across sessions. Routing policy56is defined in `skills/conventions/subagent-routing.md` — the project default is57`pain_triggered` (native subagents first, Minions after specific pain signals58fire); Mode A (all-through-Minions) is opt-in.59
88 89- **`GBRAIN_ALLOW_SHELL_JOBS=1` must be set on the worker environment.**90 Without it, the shell handler refuses to register and submissions sit in91 `waiting` silently. Gate lives in `src/core/minions/handlers/shell.ts`.92- **Security:** flipping `GBRAIN_ALLOW_SHELL_JOBS=1` authorizes arbitrary93 command execution on the worker. On a shared queue, this is a remote code94 execution surface. Treat as privileged infrastructure authorization.
97 claims and executes jobs from the queue.98 - **PGLite + --follow:** `gbrain jobs submit ... --follow` runs inline.99 The daemon mode is not available on PGLite (exclusive file lock). See100 `docs/guides/minions-shell-jobs.md`.101- **MCP boundary:** shell-job submission is CLI-only. `submit_job name="shell"`102 over MCP throws an `OperationError` with code `permission_denied` ("'shell'103 jobs cannot be submitted over MCP") because `shell` is in `PROTECTED_JOB_NAMES`.
175```176 177`--tools` accepts a comma-separated subset of `BRAIN_TOOL_ALLOWLIST` (see178`src/core/minions/tools/brain-allowlist.ts`): `query`, `search`, `get_page`,179`list_pages`, `file_list`, `file_url`, `get_backlinks`, `traverse_graph`,180`resolve_slugs`, `get_ingest_log`, `put_page`. Anything outside the allow-list181is rejected at submit time with `allowed_tools references unknown tool`.
188The manifest describes N children + 1 aggregator. Each child runs189`name="subagent"` under the hood; the aggregator runs `name="subagent_aggregator"`190and claims AFTER every child terminates. See191`src/core/minions/handlers/subagent.ts` and192`src/core/minions/handlers/subagent-aggregator.ts`.193 194Flags (from `src/commands/agent.ts`):195- `--subagent-def <name>` — named subagent definition196- `--model <id>` — override model197- `--max-turns <N>` — cap the LLM loop
1---2name: perplexity-research3version: 0.1.04description: Brain-augmented web research. Sends brain context about a topic to Perplexity, which searches the web with citations and returns what is NEW vs what the brain already knows. Use for entity enrichment, current-state checks, deal monitoring, and freshness deltas. NOT for simple URL fetches (use web_fetch) or brain-only queries (use gbrain query).
47| Quick URL content | `web_fetch` |48| Brain-only lookup | `gbrain query` / `gbrain search` |49| Real-time social monitoring | external X / social-media collectors |50| Structured data lookup against a tracker | `skills/data-research/SKILL.md` |51 52## Output structure53
131 132### Entity enrichment133 134Called by `skills/enrich/SKILL.md` when an entity page (person, company)135needs current web context:136 137```bash
175 176## Related skills177 178- `skills/academic-verify/SKILL.md` — wraps perplexity-research for179 citation-verified academic claim checking180- `skills/enrich/SKILL.md` — calls perplexity-research as part of the181 entity-enrichment loop
196 197## Output Format198 199The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: publish3description: Share brain pages as beautiful password-protected HTML with zero LLM calls4triggers:
46 47## Quick Reference48 49```bash50# Basic publish (outputs local HTML file)51gbrain publish brain/companies/acme.md52
72| YAML frontmatter | `title:`, `type:`, `tags:` | Internal metadata |73| `[Source: ...]` citations | All formats | Provenance is internal |74| Confirmation numbers | `ABC123DEF` -> "on file" | PII/booking data |75| Brain cross-links | `[Jane](../people/jane.md)` -> `Jane` | Internal paths |76| Timeline section | Everything below `---` / `## Timeline` | Raw evidence log |77| "See also" lines | Internal references | Brain navigation |78
1---2name: repo-architecture3version: 1.0.04description: |
18 19# Repo Architecture — Filing Rules20 21> **Full filing rules:** See `skills/_brain-filing-rules.md`22 23## Contract24
39 - Media content → `media/{type}/{slug}.md`40 - Raw data import → `sources/{slug}.md`413. **Cross-link.** Link from related directories.424. **Check notability.** See `skills/conventions/quality.md` notability gate.43 44## Output Format45
1---2name: reports3version: 1.0.04description: |
1---2name: schema-author3description: 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.4tools:
62This skill AUTHORS the schema pack (adds page types, link verbs, prefixes,63flags). For these adjacent jobs, route elsewhere:64 65- **Filing one specific page** → `skills/brain-taxonomist/SKILL.md`. Brain-66 taxonomist routes at WRITE TIME ("where does this note go?"). schema-author67 changes the rules at AUTHORING TIME ("what types and prefixes exist?").68- **Schema-check as part of EIIRP iteration** → `skills/eiirp/SKILL.md`69 already has a schema-check phase. Don't duplicate.70- **Just looking up a type's settings** → `gbrain schema explain <type>`71 directly. This skill is for CHANGING the pack, not READING from it.72- **Querying who knows about X** → `skills/expert-routing/SKILL.md` (or73 `gbrain whoknows` directly). schema-author makes a type expert-routable;74 it does not run the query.75
94 95## Tutorial + vision96 97- **Why this matters:** [`docs/what-schemas-unlock.md`](../../docs/what-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.98- **5-minute walkthrough:** [`docs/schema-author-tutorial.md`](../../docs/schema-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.99 100## Workflow101
252## Anti-Patterns253 254- **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`.255- **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/conventions/schema-evolution.md` for the <20-pages-don't-pack-codify heuristic.256- **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.257- **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.258- **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.
288- Stats: total pages, typed %, untyped count, per-type breakdown, dead-prefix list289- Sync: per-prefix `would_apply`/`applied` count + sample slugs in dry-run mode290 291On failure, the error envelope follows the standard `StructuredAgentError` shape from `src/core/errors.ts`: `{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`.292 293## Failure modes294
1---2name: schema-unify3description: Migrate a brain from gbrain-base (or any pack) to gbrain-base-v2's 14-canonical-type taxonomy via gbrain onboard --check + the unify-types Minion handler. Collapses 94 noisy types to 15 canonical with subtypes, alias rows, and link rows. Triggers when an agent notices pack_upgrade_available, type_proliferation, or asks "what is the canonical taxonomy / how do I clean up my page types".4brain_first: exempt
246## Reference247 248- Plan + decisions: `~/.claude/plans/system-instruction-you-are-working-transient-elephant.md`249- Architecture: `docs/architecture/type-taxonomy.md`250- Pack-upgrade mechanism: `docs/architecture/pack-upgrade-mechanism.md`251- Issue: https://github.com/garrytan/gbrain/issues/1479
1---2name: setup3description: Set up GBrain with auto-provision Supabase or PGLite, AGENTS.md injection, first import4triggers:
12 - put_page13mutating: true14---15 16# Setup GBrain17 18Set up GBrain from scratch. Target: working brain in under 5 minutes.
72 73GBrain supports three deployment shapes. Pick the right one before installing,74because picking wrong creates contention or duplicate work that's painful to75unwind. Read `docs/architecture/topologies.md` for the full picture; the short76version:77 78Ask the user this BEFORE running `gbrain init`:
127 failure surfaces an actionable error.128 1294. **Configure your agent's MCP client.** Add a server entry pointing at130 `<mcp_url>` with the bearer token. See `docs/mcp/CLAUDE_DESKTOP.md`,131 `docs/mcp/CLAUDE_CODE.md`, etc. for per-client snippets.132 1335. **Verify with `gbrain doctor`.** Thin-client doctor runs OAuth discovery,134 token round-trip, and MCP smoke against the host. Should report
199 2001. **Discover markdown repos.** Scan the environment for git repos with markdown content.201 202```bash203echo "=== GBrain Environment Discovery ==="204for dir in /data/* ~/git/* ~/Documents/* 2>/dev/null; do205 if [ -d "$dir/.git" ]; then
294- On **ephemeral containers** (Render / Railway / Fly / Docker): writes295 `~/.gbrain/start-autopilot.sh` and prints the one-line your agent's296 bootstrap should source to launch autopilot on every container start.297 Auto-injects into OpenClaw's `hooks/bootstrap/ensure-services.sh` if298 detected (use `--no-inject` to opt out).299- On **Linux without systemd**: installs a crontab entry (every 5 min).300
307 308If `apply-migrations` prints "N host-specific items need your agent's309attention," read `~/.gbrain/migrations/pending-host-work.jsonl` + walk310`skills/migrations/v0.11.0.md` + `docs/guides/plugin-handlers.md` to311register host-specific handlers. Re-run `apply-migrations` after each312batch.313
383 384## Phase E: Load the Production Agent Guide385 386Read `docs/GBRAIN_SKILLPACK.md`. This is the reference architecture for how a387production agent uses gbrain: the brain-agent loop, entity detection, enrichment388pipeline, meeting ingestion, cron schedules, and the five operational disciplines.389
3921. **Brain-agent loop** (Section 2): read before responding, write after learning3932. **Entity detection** (Section 3): spawn on every message, capture people/companies/ideas3943. **Source attribution** (Section 7): every fact needs `[Source: ...]`395> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.396 397Tell the user: "The production agent guide is at docs/GBRAIN_SKILLPACK.md. It covers398the brain-agent loop, entity detection, enrichment, meeting ingestion, and cron
474 475Run the full verification runbook to confirm the entire installation is working.476 4771. Read `docs/GBRAIN_VERIFY.md`4782. Execute each check in order4793. Report results to the user4804. Fix any failures before declaring setup complete
509> **Ready to populate your brain?**"510 511If the user says yes (or anything affirmative):512→ **Load and execute `skills/cold-start/SKILL.md`** immediately. Do not513just print a reference — actually run the cold-start skill.514 515If the user says no or wants to stop:
1---2name: signal-detector3version: 1.0.04description: |
21 - companies/22 - concepts/23---24 25# Signal Detector — Ambient Brain Capture26 27Lightweight sub-agent that fires on every inbound message to capture TWO things
44- Back-links all entity mentions (Iron Law)45- Citations on every fact written46 47> **Convention:** See `skills/conventions/quality.md` for Iron Law back-linking.48 49Every time this skill creates or updates a brain page that mentions a person or company:501. Check if that person/company has a brain page
1---2name: skill-creator3version: 1.0.04description: |
29## Phases30 311. **Identify the gap.** What capability is missing? What user intent has no skill?322. **MECE check.** Review `skills/manifest.json` and `skills/RESOLVER.md`. Does any existing skill already cover this? If so, extend it instead of creating a new one.333. **Create SKILL.md.** Use this template:34 35```yaml
1---2name: skill-optimizer3version: 0.1.04description: Self-evolving skill optimization via SkillOpt-paper-grounded text-space optimizer.
120yourself: read the SKILL.md, write ~15 realistic tasks covering the boring middle,121attach >=2 rule checks each, save to `skills/X/skillopt-benchmark.jsonl`, run with122`--split 1:1:1`. The human walkthrough lives at123`docs/tutorials/improving-skills-with-skillopt.md`.124 125## Decision tree126
185 186- `skillify` — scaffolds a new skill (use BEFORE skillopt)187- `skillpack-check` — audits skill conformance (item 13 surfaces skillopt status)188- `conventions/quality.md` — output quality standards skillopt enforces via judges
1---2name: skillify3version: 1.1.04description: |
67- `gbrain apply-migrations --yes` — A migration is pending or half-finished.68 Run this (it's idempotent). If it exits `status: "partial"`, the host has69 non-builtin cron handlers that need plugin registration — follow70 `skills/migrations/v0.11.0.md`.71- `gbrain embed --stale` — Embeddings are stale.72- `gbrain check-backlinks --fix` — Dead links or missing back-links.73- Free-text action (no `Run:` prefix in the source message) — agent judgment
129- `gbrain apply-migrations --list` — the migration status view.130- `skills/migrations/v0.11.0.md` — the host-agent instruction manual for131 resolving `pending-host-work.jsonl` items.132- `docs/guides/minions-fix.md` — troubleshooting a half-migrated install.
1---2name: skillpack-harvest3version: 0.33.04description: |
1---2name: smoke-test3description: |4 Post-restart smoke tests + auto-fix for gbrain and OpenClaw environments.
84 85## Adding Built-in Tests86 87Edit `scripts/smoke-test.sh`. Follow this pattern:88 89```bash90# ── N. [Service Name] ──────────────────────────────────────91if [test condition]; then92 pass "[Service Name]"
1---2name: soul-audit3version: 1.0.04description: |
1---2name: strategic-reading3version: 0.1.04description: Read a book, article, transcript, or case study through the lens of a specific strategic problem you're facing. Produces an applied playbook that maps the source onto the problem and gives short/medium/long-term recommendations. NOT for general book summaries.
161 162## Related skills163 164- `skills/book-mirror/SKILL.md` — book personalized to whole life (vs165 problem)166- `skills/perplexity-research/SKILL.md` — current-intel cross-reference167 for fresh data168- `skills/conventions/quality.md` — citation + back-link rules169 170 171## Contract
181 182## Output Format183 184The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).185 186## Anti-Patterns187
1---2name: testing3version: 1.1.04description: |
53- Every skill directory has a `SKILL.md` file54- Every `SKILL.md` has valid YAML frontmatter (`name`, `description`)55- Every `SKILL.md` has required sections per56 `test/skills-conformance.test.ts`57- `skills/manifest.json` lists every skill directory58- `skills/RESOLVER.md` references every skill in the manifest59- `openclaw.plugin.json` `skills[]` round-trips with both60- No MECE violations (duplicate triggers across skills)61
1---2name: voice-note-ingest3version: 0.1.04description: Ingest a voice note with exact-phrasing preservation (never paraphrased). Routes content to originals/, concepts/, people/, companies/, ideas/, personal/, or voice-notes/ based on a decision tree. The user's exact words are the signal.
178 179## Related skills180 181- `skills/signal-detector/SKILL.md` — same exact-phrasing pattern for182 text-channel idea capture183- `skills/idea-ingest/SKILL.md` — for typed-text idea ingestion184- `skills/conventions/quality.md` — citation + back-link rules185 186 187## Contract
197 198## Output Format199 200The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test (`test/skills-conformance.test.ts`).
1---2name: webhook-transforms3version: 1.0.04description: |