Skip to content
GigaBrain

For agents

Skill workflows

The eight default skills, their triggers, and what each one outputs.

GigaBrain ships eight default skills as embedded markdown files. Each one is a workflow — a documented decision procedure that you, an agent, follow when the trigger conditions are met.

This page is the agent-facing index. For the design philosophy, see The skills system. For overriding skills, see Customize skills.

Resolution order

Section titled “Resolution order”

When you load a skill, the binary resolves it in this order:

  1. Working directory SKILL.md (project-scoped).
  2. ~/.gbrain/skills/<name>/SKILL.md (user-scoped).
  3. Embedded default.

Always check gbrain skills doctor if you’re unsure what’s in effect. The same name can have different content in different repos.

The eight skills

Section titled “The eight skills”

ingest

Section titled “ingest”

Process source documents into structured brain pages.

Trigger. New material to add — meeting notes, articles, conversations, documents. Surfaces. gbrain import, gbrain ingest, brain_put. Idempotency. SHA-256 deduplication via ingest_log. Re-running on the same file content is a no-op unless --force. Output. New or updated pages rows; new timeline_entries; enqueued embedding jobs.

query

Section titled “query”

Answer questions using the four-layer search strategy.

Trigger. A question to answer, with or without an obvious target page. Surfaces. brain_query, brain_search, brain_graph, brain_backlinks. Strategy. Try SMS short-circuit (slug/title match) → FTS5 → vector → graph traversal. Return cited results. Output. A ranked list with provenance. Cite sources by slug.

maintain

Section titled “maintain”

Keep the brain healthy: contradictions, orphans, stale assertions.

Trigger. Periodic (daily / weekly), or after a large ingest. Surfaces. gbrain validate, brain_check, manual orphan review. Output. A list of issues with proposed resolutions. Don’t fix automatically — surface to the user.

enrich

Section titled “enrich”

Add external data while preserving compiled truth.

Trigger. A page with thin compiled truth and a clear external source. Surfaces. brain_raw (store raw JSON), brain_put (extract facts), brain_link (relate to other pages). Rule. Never overwrite compiled_truth directly with raw external content. Always extract facts first, flag conflicts as contradictions. Output. A new raw_data row + extracted assertions in compiled_truth. Sensitivity. External API calls are governed by the sensitivity contract.

briefing

Section titled “briefing”

Daily “what shifted” report.

Trigger. Scheduled (typically morning), or on demand. Surfaces. brain_stats, brain_check, brain_gaps, brain_timeline (recent entries). Default lookback. 1 day. Configurable. Output. Structured report — changed pages, new pages, unresolved contradictions, open gaps, upcoming timeline entries. JSON when called from automation; markdown when called for human consumption.

alerts

Section titled “alerts”

Interrupt-driven notifications.

Trigger. Brain state changes — new contradictions, stale pages, resolved gaps, embedding drift. Surfaces. brain_check, brain_gaps, brain_stats. Output. Structured JSON to stdout, one alert object per line. Designed to be piped to a logger, dashboard, or downstream MCP client. Cadence. Cron-driven, or after significant write batches.

research

Section titled “research”

Resolve knowledge gaps with sensitivity guardrails.

Trigger. An unresolved gap from brain_gaps. Surfaces. brain_gaps, sensitivity escalation, external research, gbrain ingest, brain_put. Critical. Default sensitivity is internal (hash-only). Escalating to external requires explicit approval — see Sensitivity contract. Never bypass. Output. A new page resolving the gap, plus a resolved_at + resolved_by_slug update.

upgrade

Section titled “upgrade”

Safe binary and skill upgrades with rollback.

Trigger. A new GigaBrain release tag, or a user request. Surfaces. gbrain version, the shell installer, gbrain validate, gbrain skills doctor. Procedure. Stop serve → download new binary → SHA-256 verify → atomic replace → run validation → on failure, restore from .bak. Output. New binary in place; skills re-extracted; validation report.

Cross-cutting rules

Section titled “Cross-cutting rules”

These apply to every skill:

  • Read before you write. Always brain_get before brain_put when updating an existing page. Pass expected_version.
  • Cite sources. When the user asked a question, point to slugs and timeline dates. Don’t synthesize without provenance.
  • Honor write-gates. A restoring or needs_full_sync = 1 collection rejects writes with CollectionRestoringError. Don’t retry; surface and wait.
  • Hash-only by default. Anything written to knowledge_gaps defaults to sensitivity: internal and stores only query_hash. Don’t escalate without approval.
  • Don’t auto-resolve contradictions. Surface them. Resolution is editorial; agents propose, humans decide.

When to author a custom skill

Section titled “When to author a custom skill”

Reach for a custom skill when you have a workflow that:

  • Calls only existing CLI/MCP surface (no new tools needed).
  • Repeats often enough that the user would rather you pick it up than re-prompt every time.
  • Has decision rules a human can read in under a few minutes.

Drop your SKILL.md in the project directory or ~/.gbrain/skills/<name>/. Run gbrain skills doctor to confirm shadowing is correct.

What skills don’t do

Section titled “What skills don’t do”
  • They don’t run code. Real work happens through CLI/MCP calls.
  • They don’t bypass the binary’s safety surface (write-gates, OCC, sensitivity).
  • They don’t carry brain content. Pages live in the brain; skills are workflow.