Gaia - AI Agent Skill Registry

The open, evidence-backed skill graph for AI agents: collect, evolve, and fuse capabilities into something legendary.

The Registry

Every AI agent capability exists somewhere on this graph. Skills start at the foundation tier, awaken through evidence, evolve through use, and fuse into things greater than the sum of their parts.

◆ ruvnet/ruflo  [6★]
  ├─ ◇ ruvnet/flow-nexus  [4★]
  │  ├─ ◇ ruvnet/flow-nexus-swarm  [3★]
  │  │  ├─ ◇ /plan-and-execute  [4★]
  │  ├─ ◇ ruvnet/flow-nexus-platform  [3★]
  │  │  ├─ ○ huggingface/hf-cli  [2★]
  │  │  └─ ○ /tool-use  [1★]
  │  └─ ◇ ruvnet/flow-nexus-neural  [3★]
  │     ├─ ○ /parallel-execution  [2★]
  │     └─ ○ /embed-text  [1★]
  ├─ ◆ ruvnet/agentdb  [5★]
  │  ├─ ◇ ruvnet/agentdb-advanced  [3★]
  │  │  ├─ ○ ruvnet/agentdb-vector-search  [2★]
  │  │  └─ ◇ garrytan/learn  [2★]
  │  │     ├─ ○ garrytan/context-restore  [3★]

◆ ruvnet/agentdb  [5★]
  ├─ ◇ ruvnet/agentdb-advanced  [3★]
  │  ├─ ○ ruvnet/agentdb-vector-search  [2★]
  │  └─ ◇ garrytan/learn  [2★]
  │     ├─ ○ garrytan/context-restore  [3★]
  │     └─ ○ /retrieve  [1★]
  ├─ ◇ ruvnet/agentdb-learning  [3★]
  │  ├─ ○ ruvnet/reasoningbank-intelligence  [2★]
  │  └─ ◇ garrytan/learn  [2★]  (↑ see above)
  ├─ ○ ruvnet/agentdb-memory-patterns  [2★]
  ├─ ○ ruvnet/agentdb-optimization  [2★]
  └─ ○ ruvnet/agentdb-vector-search  [2★]  (↑ see above)

Uniques — graph-isolated Basic Skills that reached elite mastery (4★+) through depth alone, with no fusion path forward.
  ◉ nousresearch/feed-monitoring  [4★ · Hardened]
  ◉ openai/few-shot-learning  [4★ · Hardened]
  ◉ huggingface/huggingface-llm-trainer  [4★ · Hardened]
  ◉ ruvnet/hive-mind-coordination  [4★ · Hardened]
  ◉ openai/self-consistency  [4★ · Hardened]

(192 skills total — see docs/tree.md)

How skills fuse

When two or more Basic skills combine, they can form an Extra. This is what gaia scan and gaia fuse render in your terminal:

  mattpocock/grill-me  ────────────┐
                                   ├──▶  mattpocock/grill-with-docs  ◇
  mattpocock/ubiquitous-language  ─┘

Basics fuse into Extras; Extras can fuse into Ultimates. Evidence powers each ascent.

[!TIP]
New here? The interactive tutorial at gaia.tiongson.co covers everything visually: skill tiers, the stars axis, The Initiate's Rite, and copy-paste commands.

Skill Tiers & Stars

Skills rank up through evidence, not declaration. Basics fuse into Extras or Ultimates; Extras can fuse with other Extras. Each demerit demotes a skill by one star (floored at 1★, valid for 2★+ only).

Quickstart

1. Install the CLI

Current Gaia CLI version: 3.21.3.

Python install:

pip install gaia-cli

npm wrapper alternative:

npm install -g @gaia-registry/cli

npm wrapper:

npm install -g @gaia-registry/cli

pipx (if pip fails):

brew install pipx        # macOS
pipx install gaia-cli

Windows PATH fix (if gaia isn't found after install):

$env:PATH += ";" + (python -c "import sysconfig; print(sysconfig.get_path('scripts', 'nt_user'))")

Registry development (editable install):

git clone https://github.com/mbtiongson1/gaia-skill-tree.git
cd gaia-skill-tree
pip install -e ".[embeddings,dev]"

The dev extra installs packaging/test tools such as build and pytest; without it,
packaging-specific tests are skipped locally with guidance to install developer extras.

2. Initialise & scan

gaia init --user your-username
gaia scan

Detects skills your agent demonstrates.

3. Push for review

gaia push

A GitHub PR opens automatically. Maintainers review; your name attaches at 2★.

4. Bond your agent (optional)

claude mcp add gaia -- npx @gaia-registry/mcp-server

Any MCP-compatible client. See packages/mcp/ for config examples.

Or explore interactively with the Terminal UI (after step 1 → gaia with no args).

Keep up to date: Run gaia update anytime to pull latest registry + CLI.

Terminal UI (experimental)

New. Agent-first interface designed for Claude Code, Codex, and other AI agents.

After step 1, launch with no arguments:

gaia

Navigate your skills:

• Fuzzy search by name, description, or intent
• View tree (^T) and run scan (^G) without leaving the TUI
• Install skills with one keystroke
• Keyboard-native: ↑↓ navigate · Enter install · q quit

Requires textual (included with pip install gaia-cli).

CLI Reference

usage: gaia [-h] [--registry REGISTRY] [--global] [--version]
            {help,init,scan,pull,update,install,uninstall,tree,push,propose,version,mcp,release,graph,stats,appraise,promote,fuse,docs,lookup,dev,validate,test,skills}
            ...

Gaia Registry CLI

positional arguments:
  {help,init,scan,pull,update,install,uninstall,tree,push,propose,version,mcp,release,graph,stats,appraise,promote,fuse,docs,lookup,dev,validate,test,skills}
    help                Show command help
    init                Create or update local Gaia config
    scan                Scan configured paths for skill evidence
    pull                Refresh registry data from origin
    update              Update all installed remote skills
    install             Install a named skill
    uninstall           Uninstall a named skill
    tree                Show your Gaia skill tree
    push                Prepare detected skills for review
    propose             Propose a single canonical skill as a named PR
    version             Print the Gaia CLI version
    mcp                 Run the bundled Gaia MCP server
    release             Bump release version files
    graph               Generate and open the Gaia skill graph
    stats               Show registry health at a glance
    appraise            Inspect a skill card with status and actions
    promote             Promote a skill eligible for level-up
    fuse                Confirm a skill combination or promotion candidate
    docs                Documentation maintenance commands
    lookup              Look up a canonical skill and its named implementations
    dev                 Registry development and maintenance (requires writable registry)
    validate            Validate the Gaia registry
    test                Run self-verification tests
    skills              Browse and manage named skills

options:
  -h, --help            show this help message and exit
  --registry REGISTRY   Path to a local Gaia registry checkout. Defaults to auto-resolved local or
                        global registry.
  --global, -g          Use global GAIA_HOME registry, ignoring any local .gaia/ config.
  --version, -v         Print the Gaia CLI version and exit.
  --canon               Show canonical registry data instead of local-first view.

Quick usage:
  gaia init [--user <name>] [--scan <path>] [--yes]
  gaia scan [--quiet] [--auto-promote]
  gaia pull
  gaia tree [--named] [--title]
  gaia push [--dry-run] [--no-pr]
  gaia propose [<skillId>] [--ultimate] [--target <name>] [--no-pr]
  gaia version
  gaia mcp
  gaia release <patch|minor|major>
  gaia graph [--format html|svg|json] [-o <path>] [--no-open]
  gaia appraise [<skillId>]
  gaia promote [<skillId>] [--all] [--name <name>]
  gaia fuse <skillId> [--name <name>]
  gaia update
  gaia stats
  gaia docs build [--check]
  gaia lookup <skillId>
  gaia list [--generic] [--named] [--description] [--json]
  gaia merge <target> <source1> [source2...] [--named]
  gaia split <source> <target1> <target2>...
  gaia add <name> [--id <id>] [--type <type>] [--description <desc>] [--named] [--contributor <user>]
  gaia evidence <skillId> <source> [--class A|B|C] [--evaluator <user>] [--date <date>] [--notes <notes>]
  gaia validate [--intake] [--meta-sync]
  gaia test <suite>
  gaia skills <list|search|info|install|uninstall>
  gaia skills list [--exclude-pending]
  gaia skills search <query> [--exclude-pending]
  gaia skills info <skill_id> [--exclude-pending]
  gaia skills install <skill> [--global | --local]
  gaia skills uninstall <skill_id>

MCP Server

@gaia-registry/mcp-server connects Gaia to MCP-compatible agents (Claude Code, Cursor, VS Code, etc.).

Set GAIA_USER=your-github-username and optionally GITHUB_TOKEN for PR tools. See packages/mcp/ for full docs and agent-specific config examples.

Repository Structure

registry/                 curated registry data and public generated catalogs
registry-for-review/      pending skill batch intake records
skill-trees/              per-user skill-tree.json files
generated-output/         ignored local scan and render output
docs/                     docs site
src/gaia_cli/             Python CLI package
packages/cli-npm/         npm wrapper package
packages/mcp/             MCP server package
scripts/                  validation, rendering, docs, and release helpers
tests/                    Python test suite

Contributing

Gaia is a shared map of agent capabilities.

Common ways to help:

• Review draft skills for clarity, overlap, and evidence quality.
• Turn accepted reviews into concrete PRs (new skill, fusion, or reclassification).

Contribution steps: CONTRIBUTING.md.
Full policy/reviewer guidance: https://github.com/mbtiongson1/gaia-skill-tree/wiki (repo: https://github.com/mbtiongson1/gaia-skill-tree.wiki.git).

Contributors

Thank you to everyone who has expanded the Gaia registry.

Programmatic Management

The Gaia registry is programmatically managed. All meta shifts (adding, merging, splitting, adding evidence) must be performed via the Gaia CLI. Hand-editing JSON nodes is deprecated to ensure schema integrity and automated timeline logging.

License

MIT: see LICENSE.

Graph is canonical. Everything else is a shadow.