Skip to content

FAQ

Jump to bottom
Marco Tiongson edited this page May 10, 2026 · 5 revisions

FAQ

Common questions and gotchas.

Getting Started

Q: Where do I start if I'm completely new?

Read Getting Started. 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, and ultimate?

See Skill Types. Short version: basic = primitive (no parts), extra = combination of 2+ others, 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, and ultimate. Similarly, level values changed from Roman numerals (I–VI) to star notation (0★–6★). See Rank System 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 level) 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?

Both, depending on the path:

  • Via gaia push: You push an intake batch; maintainers promote accepted skills into registry/gaia.json.
  • Direct PR: Fork the repo, edit registry/gaia.json yourself, open a PR.

Never edit registry/skills/, registry/registry.md, registry/combinations.md — they are generated.

Demerits

Q: What is a demerit?

A demerit is a schema-validated flag that lowers a skill's effective level 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 effective level is floored at 1★.

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

gaia appraise web-search

The skill card shows claimed level, active demerits, and computed effective level.

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/gaia.json registry/skills/
registry/named/ registry/registry.md
registry-for-review/ registry/combinations.md
skill-trees/ registry/named-skills.json
docs/ registry/similarity.json
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