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.

As of Yggdrasil II, this is not one four-way split — it's two separate axes.

Type (starless skills, before anyone claims them):

• ○ Basic — no prerequisites.
• ◇ Fusion — one or more prerequisites. Replaces the old "Extra" and structural "Ultimate" categories. "Unique" is never a type value.

Branch (Named Skills at 4★ and up), set by whether the Named Skill carries suiteComponents:

• ◉ Unique branch — no suiteComponents. Ranks: Unique (4★), Unique Ultimate (5★), Unique Impossible (6★).
• ◆ Suite branch — carries suiteComponents. Ranks: Extra (4★), Ultimate (5★), Apex (6★).

Branch is computed from evidence at read time — never declared on a node. See Skill Hierarchy for more.

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) — quality tier, auto-derived from a trust number. S ≥ 250; A ≥ 100; B ≥ 50; C ≥ 20. Added via --trust <number> (there is no --grade flag). Paired with an Evidence Type (arxiv, repo-own, github-stars-own, 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.

gaia push --update is an incremental push: it queries open intake issues for this repo, drops skills that are unchanged since the last push, and only submits new or edited ones. If every detected skill is already pending review, there's nothing left to submit.

gaia scan                  # regenerate candidates
gaia push --dry-run       # see the full batch, ignoring pending state

There is no self-promote path — stars and rank are assigned only by canon curation once your proposal is reviewed, never written directly by the CLI.

• gaia push — submits the full batch of skills and fusion candidates detected by your last scan to the canonical registry for review. This opens a GitHub intake issue. Always dry-run first: gaia push --dry-run.
• gaia propose <skillId> — claims one specific, already-canonical skill under your name as a Named Skill (optionally targeting --target contributor/skill-name). Opens a naming PR rather than an intake issue.

The published @gaia-research/mcp package currently provides gaia_search, gaia_inspect, summon, and gaia_status. summon materializes a matching Named Skill in an ephemeral session directory; it is not gaia_summon and does not install into your repository or persistent configuration.

No. The server fetches Gaia's public generic and Named Skill projections directly. Search, inspection, and status need no local Gaia CLI; the summon tool resolves and materializes its temporary session payload independently.

For one-shot command-line summoning, use the separate npx-friendly skill-hell alias.

No. The current package is a public Registry/Bond surface and has no user-identity or GitHub write path. It cannot open pull requests, mutate the Registry, submit Intake proposals, or change persistent user configuration.

For isolated testing only, TREE_URL and TREE_NAMED_URL can override the public projection endpoints.

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).