FAQ

gaia init and gaia scan run successfully in any directory, but gaia push requires a Git repository root because it needs to detect your project's skill signals and associate the batch with a source repo URL. Running outside a repo creates the impression that push will work — it won't, and the CLI will exit with an error when it tries to resolve the repo origin.

Workaround: Run Gaia inside a Git-tracked project directory. If your environment (Hermes, OpenClaw, a cloud shell) isn't backed by a repo, gaia scan and gaia tree are still useful for local introspection — just don't expect push to open a GitHub PR.

Several commands — gaia tree, gaia graph, gaia stats, gaia lookup — default to canonical registry data rather than your local or custom skills. This is a known design gap; the intended local-first behavior hasn't been fully implemented yet.

For now: pass --custom to gaia tree and gaia graph to narrow output to project-local skill files. For a view of your personal progression, gaia tree shows your skill-tree.json slots, not arbitrary local skill files.

gaia tree --custom      # local custom skills only
gaia graph --custom    # graph of local custom skills
gaia tree              # your personal skill-tree.json
gaia tree --canon      # full canonical registry

Run gaia whoami. It prints your configured username and the authorization path in effect: verifier, override, bootstrap, or denied.

gaia whoami
# → user: yourname | via: verifier
# → user: yourname | via: denied  (need a 4★ named skill)

Mutating gaia dev subcommands (add, merge, split, evidence, etc.) require the verifier or override path. In CI, set GAIA_OPERATOR_OVERRIDE=1 to bypass the check.

gaia push scans your repo and creates a new intake batch every time it runs. It doesn't yet check for existing open issues from the same source repo, so re-running after adding new skills creates a second batch containing all skills — including ones already pending review.

Workaround: Before re-running, check for open issues tagged draft-skills with your repo in the title. Close the stale batch manually, then push again. A future --update flag (issue #611) will filter already-pushed skills automatically.

The tier axis describes the structural role of a skill in the registry graph:

• ○ Basic — a standalone atomic capability (web scraping, code generation). No prerequisites. Can fuse with other Basics to produce an Extra.
• ◇ Extra — a composite skill produced by fusing two or more Basic Skills (or Extra Skills). Qualitatively richer than any single input.
• ◉ Unique — a depth-only Basic that reached elite mastery without a fusion path. Does not fuse into an Extra or Ultimate. Reserved for narrow-but-deep specializations.
• ◆ Ultimate — a top-of-tree composite that crosses the full-autonomy threshold. Cannot fuse further. Highest tier in the graph.

Tier and stars (0★–6★) are independent axes. A Basic can reach 6★; an Ultimate can sit at 0★. See Skill Hierarchy for the full two-axis model.

Each star level has a named rank on the progression axis:

A generic skill (starless / 0★) is a registry node that captures the abstract capability — web-scrape, rag-pipeline — without being tied to any specific contributor or implementation.

A Named Skill is a concrete implementation of that generic, authored by a real contributor (e.g. karpathy/web-scrape). It lives in registry/named/, carries its own star level based on evidence, and can be installed into a project via gaia skills install karpathy/web-scrape.

A generic can have multiple Named Skills in its "bucket" — one is the origin (earliest or highest-starred), others are variants. See Named Skills for the full lifecycle.

• Evidence Class (legacy) — provenance tier. C = first sighting; B = reproducible; A = battle-tested, peer-reviewed. Added via --class C|B|A.
• Evidence Grade (new) — trust score tier. S ≥ 90; A ≥ 80; B ≥ 60; C ≥ 40. Added via --grade S|A|B|C. Paired with a Grade Type (arxiv, repo, github-stars, etc.) added via --type.

The overall Trust Grade per skill is aggregated from all grade entries at build time. It is never stored on the node itself — you read it from the generated catalog. See Evidence Classes for the full breakdown.

The scanner walks your project tree looking for SKILL.md files (in .claude/skills/, .cursor/skills/, .agents/skills/, and similar standard paths). It also checks package.json, lock files, config files, and source patterns to infer capabilities.

Each detected signal is matched against the canonical registry using a word-set similarity function. Matches above a confidence threshold are written to generated-output/promotion-candidates.json.

The match function caches word-set computations per canonical skill — on large registries (2 000+ skills) this cache reduces scan time from ~3.5 s to ~0.6 s.

Promotion candidates expire 24 hours after the scan that produced them. If your candidate file is stale, gaia promote rejects it.

gaia scan               # regenerate candidates
gaia promote <skillId>  # promote within 24 h

The promote command also only accepts skill IDs listed in the most recent candidate file — you can't promote arbitrary skill IDs by hand.

• gaia promote <skillId> — writes a rank-up to your local skill-tree.json. This is a personal progression action; it doesn't touch the shared registry. Always run gaia scan first.
• gaia push — submits a batch of detected skills to the canonical registry for Verifier review. This opens a GitHub issue tagged draft-skills. Always dry-run first: gaia push --dry-run.

The MCP server resolves identity relative to process.cwd(), not the script's own directory. When an MCP host (Claude Code, Cursor, VS Code) spawns the server, the working directory may not be your project root — so .gaia/config.json is never found.

Fix: Set GAIA_USER in the server's env block. It is checked before any file-based resolution and is unaffected by CWD.

"env": {
  "GAIA_USER": "your-github-username"
}

No — for the core tools (gaia_lookup, gaia_suggest, gaia_my_tree, gaia_propose), the server is self-contained. It fetches registry data directly from GitHub.

The one exception: gaia_scan_context with deepScan: true invokes the local gaia CLI binary for a full source-code scan. If the CLI isn't installed, deepScan will fail; the default (signal-based) scan mode still works without it.

Only gaia_propose requires GITHUB_TOKEN. It opens a pull request on mbtiongson1/gaia-skill-tree to claim a fusion or propose a new skill. All read-only tools work without a token.

Create a personal access token with repo scope and set it as GITHUB_TOKEN or GH_TOKEN in the server's env block.

1. Create a SKILL.md in your repo at a stable path (e.g. .claude/skills/web-scrape/SKILL.md).
2. Run gaia push --dry-run to verify the skill is detected.
3. Run gaia push to open a draft intake issue.
4. A Verifier reviews and promotes it. Once promoted to 2★+, your named skill appears in registry/named/.

The installed path must use blob/<branch>/<subpath> format in links.github — the installer rejects bare repo URLs and tree/ paths. See Named Skills for the full flow.

Manual edits to registry files are deprecated. All meta changes must go through the CLI:

gaia dev add "Skill Name" --type basic --description "..."
gaia dev merge target-id source-id1 source-id2
gaia dev evidence skill-id "url" --class B
gaia dev split source-id target-id1 target-id2

CLI commands write proper timeline entries and maintain schema integrity. Direct file edits skip these checks and will fail CI validation. If you discover a CLI gap that forces a direct edit, document it in the PR description.

Use gaia skills install with the contributor/skill-name format:

# Install a known named skill from the registry
gaia skills install karpathy/web-scrape

# Browse available named skills first
gaia skills list
gaia skills search "web scraping"

# Install from a share bundle (URL or .json path)
gaia install path/to/bundle.json

The installer resolves the links.github URL from the named skill's metadata and symlinks it into your project's skill directory. Suite skills (those with suiteComponents) install all components; they don't need their own links.github.

CI enforces branch scope via .github/workflows/branch-scope.yml. Use the right prefix or CI will block your PR:

Add the skip-scope-check label to bypass in emergencies (maintainer only).