gaia-cli 1.0.0

Gaia AI Agent Skill Registry CLI

Gaia — AI Agent Skill Registry

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

---

The Tree

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.

The snapshot below shows the upgrade-path structure. Each legendary traces back through its full prerequisite chain.

GAIA SKILL TREE  v1.0.0
═════════════════════════════════════════════════════════════════

◆ Wisdom King: Autonomous Research Agent  [VI · Transcendent ★]
  ├─ ◇ Research  [III · Evolved]  ← Web Search · Summarize · Cite Sources
  │  ├─ ○ Web Search  [I · Awakened]
  │  ├─ ○ Summarize  [I · Awakened]
  │  └─ ○ Cite Sources  [I · Awakened]
  ├─ ◇ Knowledge Harvest  [IV · Transcendent]  ← Web Scrape · Extract Entities · Embed Text
  │  ├─ ◇ Web Scrape  [III · Evolved]  ← Web Search · Parse HTML · Extract Entities
  │  │  ├─ ○ Web Search  [I · Awakened]  (↑ see above)
  │  │  ├─ ○ Parse HTML  [I · Awakened]
  │  │  └─ ○ Extract Entities  [I · Awakened]
  │  ├─ ○ Extract Entities  [I · Awakened]  (↑ see above)
  │  └─ ○ Embed Text  [I · Awakened]
  └─ ◇ Ghostwrite  [IV · Transcendent]  ← Research · Write Report · Audience Model
     ├─ ◇ Research  [III · Evolved]  (↑ see above)
     ├─ ○ Write Report  [I · Awakened]
     └─ ○ Audience Model  [I · Awakened]

→ Full graph: tree.md

---

What This Means for You

• Track your agent's capabilities — every skill your agent demonstrates gets logged to your personal skill tree, tied to your GitHub identity, portable across every repo you own.
• Unlock combinations — when your agent has the prerequisites, a new composite or ultimate skill becomes available to fuse. The CLI detects it automatically.
• Name and share skills — contribute named implementations of generic skills (e.g., karpathy/autoresearch), attributed to your GitHub identity and installable by anyone via gaia install.
• Contribute to the canon — review draft skills, submit evidence, or create new skills from strong reviews. The graph grows with the field.

---

The Hierarchy

Tier	Symbol	Display Name	What it means
atomic	○	Intrinsic Skill	Primitive, indivisible capability — the genome of every agent
composite	◇	Extra Skill	Emerges from combining 2+ intrinsic skills — transcends its parts
legendary	◆	Ultimate Skill	High-complexity emergent capability — strict evidence bar, <1% agent prevalence

Rank System

Skills level up through evidence, not declaration:

Level	Rank	Evidence Floor	What it means
0	Basic	None	Universal LLM primitive — any capable model does this by default
I	Awakened	None	Foundation tier — catalogued agent capability
II	Named	Class C	First confirmed demonstration
III	Evolved	Class B	Reproducible, fully documented
IV	Hardened	Class B or A	Failure modes known; battle-tested
V	Transcendent	Class B or A	Composable and self-improving
VI	Transcendent ★	Class A	Apex — peer-reviewed, named to the agent who unlocked it

---

Tutorial

New here? The interactive tutorial at gaia.tiongson.co covers everything visually — skill tiers, the rank system, and the full get-started workflow with copy-paste commands.

---

Quickstart

git clone https://github.com/mbtiongson1/gaia-skill-tree.git
cd gaia-skill-tree

# 1. Install the gaia CLI
pip install -e .

# 2. Enable semantic search (strongly recommended)
pip install -e ".[embeddings]"
gaia embed                      # ~30 seconds — run once, re-run when the graph changes

# 3. Validate the canonical graph
gaia --registry . scan

# 4. Regenerate all skill pages, registry, tree, and user trees
python3 scripts/generateProjections.py

Why install embeddings? gaia search uses local semantic matching so you can find skills by meaning, not just keywords. gaia push also uses it to suggest matching named-skill buckets for your proposed skills. Without embeddings, both commands will prompt you to set them up. The model runs fully locally — no API key, no network call after the first download.

CLI Usage

Install once from the repo root:

pip install -e .

Then gaia works from any directory — no path prefix needed.

Project setup

Run this inside the project you want Gaia to scan:

gaia init --user your-github-username --scan AGENTS.md --scan scripts

For the previous non-interactive defaults, use:

gaia init --yes

This creates .gaia/config.json:

{
  "gaiaUser": "your-github-username",
  "gaiaRegistryRef": "https://github.com/mbtiongson1/gaia-skill-tree",
  "scanPaths": ["AGENTS.md", "scripts"],
  "autoPromptCombinations": false
}

Use gaia doctor after initialization to check the CLI, registry path, config, skill tree, embeddings, and scan paths.

Commands

Command	What it does
gaia init	Creates .gaia/config.json in the current project. Supports --user, --registry-ref, and repeated --scan flags.
gaia doctor	Checks CLI/config/registry health and reports missing setup pieces.
gaia scan	Scans configured paths and reports detected canonical skills and possible fusions.
gaia push --dry-run	Prints the batch intake JSON without writing files.
gaia push	Writes a batch intake record under intake/skill-batches/ in the registry checkout.
gaia push --no-pr	Writes a batch intake record without trying to open a PR.
gaia name <batch> <index> <contributor/skill>	Promotes an awakened skill from intake to a named skill in graph/named/.
gaia install <contributor/skill>	Downloads a named skill into the repo (global cache + repo reference).
gaia install --list	Lists all installed named skills.
gaia sync	Updates installed named skills from their registry origin.
gaia uninstall <contributor/skill>	Removes an installed named skill.
gaia embed	Pre-computes embeddings for all skills. Strongly recommended — run once after pip install -e ".[embeddings]", re-run when the graph changes.
gaia search <query>	Semantic search across generic and named skills (requires embeddings — see above).
gaia status	Shows the configured user's registered skill-tree summary.
gaia tree	Lists unlocked skills for the configured user.
gaia fuse <skillId>	Adds a pending fusion candidate to the user's skill tree.

Typical workflow

# In the project repo you want to scan
gaia init

# Preview detected skills and proposed intake
gaia scan
gaia push --dry-run

# Submit the batch intake record for review
gaia push

Intake PRs are draft review artifacts. Accepted candidates are promoted later into canonical graph/gaia.json updates.

MCP Server (Agent-Native Integration)

Status: In Development — @gaia-registry/mcp-server is not yet published to npm. See mcp-server/ to run it locally or contribute.

The fastest way to use Gaia — connect it directly to your agent (Claude Code, Cursor, VS Code, etc.) via MCP:

{
  "mcpServers": {
    "gaia": {
      "command": "npx",
      "args": ["@gaia-registry/mcp-server"],
      "env": { "GAIA_USER": "your-github-username" }
    }
  }
}

Once connected, your agent gets these tools:

Tool	What it does
gaia_lookup	Search skills by ID or fuzzy name
gaia_suggest	Get fusion recommendations from your current context
gaia_scan_context	Detect skills from connected tools and project signals
gaia_my_tree	View your skill tree and stats
gaia_propose	Claim a fusion or propose a novel skill (opens PR)

The MCP server also exposes resources at gaia://registry and gaia://tree/{username}.

See mcp-server/ for full documentation.

---

Repository Structure

gaia-skill-tree/
├── graph/gaia.json          ← CANONICAL source (the only file humans edit)
├── graph/named/             ← Named skill implementations ({contributor}/{skill-name}.md)
├── graph/named/index.json   ← GENERATED bucket index
├── graph/embeddings.json    ← GENERATED skill embeddings (sentence-transformers)
├── graph/similarity.json    ← GENERATED pairwise similarity scores
├── intake/                  ← Batch skill proposals submitted by gaia push
├── mcp-server/              ← TypeScript MCP server (agent-native integration)
├── schema/                  ← JSON Schema definitions
├── skills/                  ← GENERATED skill pages (atomic, composite, legendary)
├── users/                   ← Personal skill trees by GitHub username
├── scripts/                 ← Validation, projection, and analysis scripts
├── scripts/crawlers/        ← Bot crawlers (MCP registries, npm, VS Code, HuggingFace)
├── plugin/                  ← CLI + GitHub Action for per-repo integration
├── registry.md              ← GENERATED flat index of all skills
├── combinations.md          ← GENERATED fusion recipe matrix
├── tree.md                  ← GENERATED full ASCII skill graph
├── CONTRIBUTING.md          ← How to contribute
└── docs/                    ← Governance, design spec, examples

---

Contributing

Gaia is meant to be a shared map of agent capabilities, and there are a few good ways to help even if you are not ready to edit the graph directly.

You can contribute by reviewing skill drafts: read a proposed skill, check whether the definition is clear, compare it against existing skills, evaluate the cited evidence, and submit peer review analysis that helps maintainers decide whether the skill should be accepted, renamed, merged, or reclassified.

You can also contribute by creating skills directly from reviews: turn a well-supported review into a concrete Intrinsic Skill, Extra Skill, Ultimate Skill, fusion recipe, or reclassification PR with evidence and rationale.

For full instructions, including evidence requirements, PR templates, naming rules, and reviewer criteria, see CONTRIBUTING.md.

License

MIT — see LICENSE.

---

Graph is canonical. Everything else is a shadow.