Skip to content

FAQ

Jump to bottom
mbtiongson1 edited this page Jun 22, 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, run gaia init --user your-username in your project, gaia scan to detect capabilities, and gaia push to submit them for review.

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 (capstone suite).

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 adding a new named implementation for it rather than a new generic skill.

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.
  • Review Curation: Reviewers use CLI meta shift commands (like gaia dev add, gaia dev merge, gaia dev split, gaia dev evidence) to make registry updates. These update the modular node files under registry/nodes/ and auto-log timeline events.
  • Pre-commit hooks: Automatically handle gaia.json assembly and doc regeneration at commit time.

Never edit registry/gaia.json, generated docs under docs/, or generated indexes directly — they are managed by 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 four canonical demerit IDs: broken-evidence, niche-integration, experimental-feature, and heavyweight-dependency. Demerits are only valid on skills at 2★ and above, and the effective rank is floored at 0★.

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/nodes/). 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 the registry first?

Yes. The generic skill must be awakened (1★ in the registry nodes) 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 highest-rated named skill implementation in a bucket earns Origin status, 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 source nodes but didn't regenerate the derived Class S site files in docs/. Run:

gaia dev docs
git add docs/graph/
git commit -m "chore: regenerate docs"

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 (via CLI) registry/gaia.json
registry/named/ registry/named-skills.json
registry-for-review/ docs/tree.md
skill-trees/ (via CLI) 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