Skip to content

FAQ

Jump to bottom
mbtiongson1 edited this page Apr 29, 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: clone the repo, pip install -e ".[embeddings]", run gaia embed, then gaia init in your project, 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 run the CLI (pip install). You never edit Python files unless you're contributing to the CLI itself.

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

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

  1. Use the full path: python -m plugin.cli.main from the registry root.
  2. On Windows, find the Scripts directory (pip show gaia-cli | grep Location) and add it to your PATH in System Environment Variables.
  3. On macOS/Linux, add ~/.local/bin (or the output of python -m site --user-base + /bin) to your ~/.bashrc or ~/.zshrc.

Skills and the Graph

Q: What's the difference between atomic, composite, and legendary?

See Skill Types. Short version: atomic = primitive (no parts), composite = combination of 2+ others, legendary = apex emergent capability found in <1% of agents.

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

Search gaia.json before submitting — many capability names are not obvious:

gaia search "natural language to SQL"   # finds text-to-sql-pipeline
gaia search "crawling"                  # finds web-scrape

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 how it does it or which model it uses. "Generates source code from a specification" is fine. "Uses GPT-4 to generate code" is not.

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

Both, depending on the path:

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

Never edit skills/, registry.md, combinations.md, or tree.md — they are generated and will be overwritten.

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 gaia.json). A named skill is a real, attributed implementation (karpathy/autoresearch in graph/named/). You install named skills like packages. See Named Skills.

Q: I want to publish my implementation. Do I need Level I in gaia.json first?

Yes. The generic skill must be awakened (Level I in gaia.json) before you can claim a named slot for it. If it isn't there yet, submit it via gaia push first.

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.

Semantic Search

Q: gaia search shows a banner instead of results. What do I do?

Run in order:

pip install -e ".[embeddings]"
gaia embed
gaia search "your query"

See Semantic Search for details.

Q: Does gaia search send my code or queries to any external service?

No. The model (all-MiniLM-L6-v2) runs fully locally using sentence-transformers. After the initial model download (~90 MB, cached by Hugging Face), no network calls are made.

CI / Validation

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

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

python3 scripts/generateProjections.py
git add skills/ registry.md combinations.md tree.md graph/named/index.json
git commit -m "chore: regenerate projections"

The pre-push hook automates this if you've installed it (.git/hooks/pre-push).

Q: How do I install the pre-push hook?

The hook is already at .git/hooks/pre-push in your local clone (it's local-only, not committed). It runs generateProjections.py automatically when you push changes to gaia.json.

MCP Server

Q: Is the MCP server published to npm?

Not yet. Run it locally from mcp-server/ (npm install && npm run build). See MCP Server.

Q: The MCP server can't find graph/embeddings.json. What's wrong?

The server reads pre-computed embeddings — it doesn't generate them. Run gaia embed from the registry root first.

Repository Structure

Q: Which files can I edit?

Edit freely Never touch (generated)
graph/gaia.json skills/
graph/named/ registry.md
users/ combinations.md
intake/ tree.md
docs/ graph/named/index.json
schema/ graph/embeddings.json

Q: Where is the tutorial page?

docs/index.html — also served at https://mbtiongson1.github.io/gaia-skill-tree/ via GitHub Pages.

Clone this wiki locally