Contributing
Three paths to help Gaia: submit a known skill, review external candidates, or apply a maintainer-approved graph change.
Pick your workflow
Choose the smallest path that matches the work. Discovery and intake do not mutate the registry.
gaia dev validate after every change.Path A — gaia push --from-file
Create skills.yml using .github/ISSUE_TEMPLATE/new_skill_intake.yml, then preview it. The CLI and issue form feed the same intake. AI agents landed in this repo can read AGENTS.md at the root for the fast-path intake guide.
Proposed skills are not in the registry until a maintainer promotes them.
# Preview; writes nothing gaia push --from-file skills.yml --dry-run # Submit the reviewed YAML gaia push --from-file skills.yml
Path B — discovery-only curation
Start with one source page and at most five candidates. Fetch a real upstream SKILL.md, normalize it, exact-dedupe it, offer at most three existing generic IDs, make one bounded decision, and stop at L4 review.
/gaia-curate <source-page-url>
Choose the smallest extension
| Need | Skill | Model |
|---|---|---|
| One bounded page | /gaia-curate | GPT-5.6 Luna at minimal reasoning, or equivalent |
| External snapshots | /gaia-curate-trending | Luna for rows; deterministic code for ranking |
| Stop and resume | /gaia-curate-chain | Luna workers with deterministic validation |
| Parallel sweep | /gaia-curate-dynamic | Sol preferred or Terra as orchestrator; Luna workers; Luna High for disputes |
pytest -q tests/test_gaia_curate_discovery_packet.py python3 .agents/skills/gaia-curate/scripts/validate_discovery_packet.py \ .agents/skills/gaia-curate/fixtures/review-ready-packet.json
gaia push --from-file; rows already in intake go to /ev-pipeline and then a maintainer-only CLI change.
Path C — Direct CLI meta shifts
Use for one-off corrections. All meta shifts — adding, merging, splitting, evidence — must go through gaia dev commands, never direct JSON edits. The CLI writes timeline events automatically.
Mutating gaia dev subcommands require Verifier authorization. Run gaia whoami to check your current authorization path.
# List skills — find targets before mutating gaia dev list --generic # Add a new skill gaia dev add "New Skill Name" \ --type basic \ --description "At least 10 chars description" # Merge skills (target inherits from sources) gaia dev merge target-id source-id-1 source-id-2 # Split a skill into two gaia dev split source-id target-id-1 target-id-2 # Add evidence gaia dev evidence skill-id "https://github.com/owner/repo/blob/main/SKILL.md" \ --class B --notes "Reproducible demo" # Calibrate stars gaia dev calibrate skill-id "3★" # Link prerequisites gaia dev link target-id prereq-id-1,prereq-id-2 # Validate after any change gaia dev validate
gaia dev commands accept --no-build. Use this during batch operations to skip expensive documentation/graph regeneration on every step — run gaia dev build once at the end.
Authorization paths
| via | Condition | Who |
|---|---|---|
| verifier | Contributor holds a 4★+ Named Skill in the registry | Human maintainers |
| override | GAIA_OPERATOR_OVERRIDE=1 env var is set |
CI runners, bots, automation |
| bootstrap | No 4★ Verifiers exist in the registry yet | Fresh / empty registries |
| denied | None of the above | Unauthorized |
Source of truth
Know which files you should touch and which you should never edit directly.
| File / directory | Status | Notes |
|---|---|---|
| registry/nodes/**/*.json | ✅ Edit via CLI | Managed programmatically by gaia dev commands |
| registry-for-review/skill-batches/*.json | ✅ Edit via push | Intake batches written by gaia push |
| registry/gaia.json | ❌ Never hand-edit | Auto-generated artifact; assembled by the build pipeline |
| docs/graph/gaia.json | ❌ Never hand-edit | Generated graph projection; regenerated on every build |
| registry/nodes/*.json | ⚠️ Fix typos only | Prefer CLI for all structural changes |
Branch naming
CI enforces scope via .github/workflows/branch-scope.yml. Schema changes (registry/schema/) must use a schema/ branch. Add label skip-scope-check to bypass in emergencies.
| Prefix | Use for | Scope |
|---|---|---|
| schema/… | Nomenclature / terminology changes | registry/schema/, *.md |
| cli/… | CLI source changes | src/, packages/, tests/, *.md |
| docs/… | Documentation | docs/, *.md |
| design/… | Website design | docs/ (HTML/CSS/JS), *.md |
| review/gaia-push/… | Intake layer (gaia push) | registry-for-review/, *.md |
| review/meta/… | Registry curation / promotion | registry/, *.md |
| infra/… | CI / tooling changes | .github/, scripts/, docs/*.html, *.md |
| dev/… claude/… codex/… | Experimental (unrestricted) | any |
git checkout -b review/meta/your-skill-name origin/main
PR checklist
Every registry PR should pass all of these before requesting review.
- Correct branch prefix for scope (see Branch naming above)
- Only source-of-truth files edited — no hand-edits to generated artifacts
gaia dev validatepasses with no errors- Evidence meets the level / type requirements for the proposed star rating
- PR title format:
[type] skill-name — short description - Timeline events written for any rank change (demotion / promotion)
- No rarity references in any copy (deprecated axis)
- Named Skill
links.githubusesblob/branch/subpathURL format — nottree/
PR title examples
[basic] parse-csv — add CSV parsing primitive [extra] autonomous-debug — compose debug workflow [reclassify] web-scrape — promote with new evidence [evidence] karpathy/web-scrape — add Grade B (Silver) source [merge] extract-data ← parse-table + extract-table
Automated maintenance
You don't need to run build scripts manually. CI handles regeneration on every push. The following automations run on every PR and merge.
Auto-Sync
On every push, a GitHub Action runs versioning and regeneration scripts. registry/gaia.json and the docs graph are rebuilt automatically.
Validation
Every PR is automatically validated for schema correctness, DAG integrity, and evidence quality. You can run the same checks locally:
gaia dev validate # full validation pass gaia dev validate --intake # validate intake batch too
Transparency Gate
Enforces the transparency mandate — every rank change must leave a timeline event explaining why. A silent demotion or promotion (rank change with no demote / rank_up event) fails the build.
Reconcile drift with the /gaia-trace-timeline skill, or run scripts/trace_timeline.py --all --apply.
Meta Guard
PRs that mutate registry files from an unauthorized actor are blocked by .github/workflows/meta-guard.yml. Bot actors (*[bot], jules, codex, claude-bot, gemini-bot) are always allowlisted. Add the skip-meta-guard label for maintainer overrides.
Monthly Meta Sweep
On the first Monday of each month, a designated maintainer runs /gaia-meta-sweep to audit the entire registry against META.md. The sweep produces an HTML report at docs/meta/reports/YYYY-MM-DD-meta-audit.html plus machine-readable JSON.
FAQ
I ran gaia push. Are my skills in the registry?
No. Intake batches are review artifacts until a maintainer promotes accepted skills into registry/gaia.json. Watch the GitHub issue created by gaia push for reviewer feedback.
Where does long-form guidance go?
Review standards, curation heuristics, edge cases, and troubleshooting live in the GitHub Wiki. Keep PRs and code comments focused on the specific change.
Can I edit registry/nodes/*.json directly?
Only for typo fixes. All structural changes — adding, merging, splitting, evidence, calibration — must go through gaia dev commands so the CLI can write timeline events automatically. Manual edits bypass timeline logging and risk schema drift.
My PR touches files in two scopes. Which branch prefix do I use?
Use the primary scope prefix. If your changes unavoidably span scopes, add the skip-scope-check label and explain why in the PR description. CI will still validate content; the label only bypasses the file-scope check.