Skip to content

FAQ

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

FAQ

Common questions and gotchas.

The Initiate's Rite

Q: Where do I start?

Read Initiates Rite. The short version: pip install gaia-cli, gaia init --user your-username in your project, gaia update, gaia scan, and gaia push.

Q: Do I need to know Python to use Gaia?

No. The CLI wraps everything. You only need Python to install it via pip. You never edit Python files unless you're contributing to the CLI itself. An npm wrapper (npm install -g @gaia-registry/cli) is also available.

Q: I ran gaia and got "command not found". What's wrong?

Your Python scripts directory isn't on your PATH. Solutions:

  1. On Windows, find the Scripts directory (pip show gaia-cli | grep Location) and add it to your PATH.
  2. On macOS/Linux, add ~/.local/bin to your ~/.bashrc or ~/.zshrc.
  3. Use pipx: pipx install gaia-cli.

Skills and the Graph

Q: What's the difference between basic, extra, unique, and ultimate?

See Skill Types. Short version: basic = primitive (no parts), extra = combination of 2+ others, unique = elite graph-isolated basic capability, ultimate = apex emergent capability found in <1% of agents.

Q: What happened to the old type names atomic, composite, legendary?

These were renamed as part of the star-tier nomenclature overhaul. The current schema values are basic, extra, unique, and ultimate. Similarly, stars axis values changed from Roman numerals (I–VI) to star notation (0★–6★). See Stars and Ranks for the full mapping.

Q: Why is my skill proposal being rejected as a "duplicate"?

Search before submitting:

gaia skills search "natural language to SQL"
gaia skills search "crawling"

If a matching skill exists, consider a reclassification PR (to raise the rank) instead of a new skill PR.

Q: Can I submit a skill that uses a specific model (e.g. GPT-4)?

No. All skill definitions must be agent-agnostic. Describe what the agent does, not which model it uses.

Q: Who edits registry/gaia.json — me or the maintainers?

Neither! Under the modular repository design, registry/gaia.json is a generated consolidated graph file. You should never edit it directly.

  • Via gaia push: You push an intake batch; maintainers promote accepted skills into the registry/nodes/ directory.
  • Direct PR: Fork the repo, edit individual skill files under registry/nodes/**/*.json (or named skills under registry/named/), then open a PR. The pre-commit hooks will automatically assemble registry/gaia.json.

Never edit registry/gaia.json, generated docs under docs/, or generated indexes — they are managed by the build pipelines.

Demerits

Q: What is a demerit?

A demerit is a schema-validated flag that demotes a skill's effective rank (the stars axis) by one star. There are three canonical demerit IDs: niche-integration, experimental-feature, and heavyweight-dependency. Demerits are only valid on skills at 2★ and above, and the effective rank is floored at 1★.

Q: How do I see a skill's demerits?

gaia appraise web-search

The skill plaque shows claimed rank, active demerits, and computed effective rank.

Named Skills

Q: What's the difference between a generic skill and a named skill?

A generic skill is an abstract definition (web-scrape in registry/gaia.json). A named skill is a real, attributed implementation (karpathy/autoresearch in registry/named/). You install named skills via gaia skills install. See Named Skills.

Q: I want to publish my implementation. Do I need 1★ in registry/gaia.json first?

Yes. The generic skill must be awakened (1★ in registry/gaia.json) before you can claim a named slot for it.

Q: How do I install a named skill now?

gaia skills install karpathy/autoresearch

The old gaia install command is replaced by the gaia skills subcommand family.

Q: Can two people publish named skills for the same generic skill?

Yes — that's the bucket system. The first person gets origin: true, but there's no limit on the number of implementations per bucket. See Named Skills#Bucket System.

CI / Validation

Q: CI is failing with "generated files differ". What does that mean?

You edited registry/gaia.json but didn't regenerate the derived files. Run:

gaia docs build
git add registry/ docs/
git commit -m "chore: regenerate projections"

The pre-commit hook automates this if you've installed it:

bash scripts/install-git-hooks.sh

MCP Server

Q: Is the MCP server published to npm?

Yes. Install with claude mcp add gaia -- npx @gaia-registry/mcp-server for Claude Code, or add the npx command to your MCP client config. See MCP Server.

Repository Structure

Q: Which files can I edit?

Edit freely Never touch (generated)
registry/nodes/**/*.json registry/gaia.json
registry/named/ registry/named-skills.json
registry-for-review/ docs/tree.md
skill-trees/ docs/index.html (and other generated docs)
registry/schema/ generated-output/

Q: Where did graph/, intake/, users/, and mcp-server/ go?

As part of the repo restructure:

  • graph/gaia.json → registry/gaia.json
  • graph/named/ → registry/named/
  • intake/skill-batches/ → registry-for-review/skill-batches/
  • users/ → skill-trees/
  • mcp-server/ → packages/mcp/
  • plugin/ → packages/cli-npm/
  • .claude/skills/ → .agents/skills/

Clone this wiki locally