Skip to content

Initiates Rite

Jump to bottom
mbtiongson1 edited this page May 18, 2026 · 2 revisions

The Initiate's Rite

This page takes you from zero to your first skill scan in five steps.

Prerequisites

  • Python 3.10 or newer
  • pip (or pipx / npm)
  • git

Step 1 — Install the CLI

pip install gaia-cli

npm wrapper alternative:

npm install -g @gaia-registry/cli

Verify:

gaia --version
Troubleshooting

If pip fails, try pipx:

brew install pipx        # macOS
pipx install gaia-cli

Windows — if gaia isn't recognized after install:

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

For registry development, clone and install editable:

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

Step 2 — Initialize your project

Run this inside the repository you want Gaia to scan — not inside the registry clone itself.

cd /path/to/your-project
gaia init --user your-github-username

This creates .gaia/config.json. Edit scanPaths to point at the directories that contain your agent's code.

Step 3 — Pull the latest registry

To instantly pull the latest registry data and update the core CLI, use:

gaia update

Note: Semantic search users must manually update embeddings by running pip install gaia-cli[embeddings] --upgrade if required. gaia update alone handles the core tools in seconds.

Step 4 — Scan your repo

gaia scan

Gaia walks your scanPaths, matches code patterns against the canonical skill graph, and prints:

  • Detected canonical skills with rank-colored display
  • Fusion diagrams for combination candidates

Step 5 — Submit a batch

Preview what would be submitted:

gaia push --dry-run

When you're happy:

gaia push

This writes an intake record under registry-for-review/skill-batches/ and opens a draft PR for maintainer review.

What Happens Next

Your batch enters the Ascension Cycle:

gaia push → intake PR (pending) → reviewed → awakened → named

Maintainers triage intake PRs and promote accepted skills into registry/gaia.json.

Common First Commands

What you want to do Command
Keep CLI and registry current gaia update
Render your skill tree gaia tree
Inspect a skill plaque gaia appraise web-search
Promote a scan-approved skill gaia promote
Preview a batch without writing gaia push --dry-run
Browse named skills gaia skills list
Search named skills gaia skills search "autonomous research"
Install a named skill gaia skills install karpathy/autoresearch
Registry health overview gaia stats

→ See CLI Reference for the full command list.

Clone this wiki locally