Contributing

Contributing

Thanks for helping improve the Gaia skill graph.

This page is a contributor guide. Detailed policy, reviewer playbooks, and deep troubleshooting live here in the wiki.

---

1) Pick your workflow

Choose the workflow that matches your objective:

• Submitting a skill you discovered? Use gaia push (A).
• A reviewer expanding or restructuring the registry? Use the gated curation pipeline /gaia-curate-chain (B) — the recommended path for maintainer-run curation.
• Making a one-off correction (a single merge, split, reclassify, or evidence add)? Use the direct CLI meta shifts (C).

A) Submit discovered skills (recommended)

gaia push

Use this when proposing skills via registry-for-review/skill-batches/*.json. Maintainers will review and promote accepted skills into the canonical graph.

B) Curate with gates (Reviewers)

For structured registry expansions, use the prompt-chained /gaia-curate-chain slash command. It runs curation as six gated links (scope, research, design, human review, mutate, ship) ensuring checks pass at every stage before merging.

C) Update the canonical graph directly

Important

All meta shifts MUST be done via CLI commands. Hand-editing individual JSON files in registry/nodes/ is deprecated to ensure programmatic schema integrity and automated timeline logging.

Use gaia dev commands (requires Verifier status or operator override):

# Add a new skill
gaia dev add "Skill Name" --type basic --description "At least 10 chars"

# Merge skills
gaia dev merge target-id source-id-1 source-id-2

# Split a skill
gaia dev split source-id target-id-1 target-id-2

# Reclassify a generic skill (change type)
gaia dev reclassify skill-id ultimate

# Add evidence (G7 dual-axis)
gaia dev evidence skill-id "https://github.com/owner/repo" \
  --type github-stars-own --stars 12500 --skill-count 5 \
  --source-started-at 2024-11-03 --notes "notes"

# Calibrate level
gaia dev calibrate skill-id "3★"

# Link skills (add prerequisites)
gaia dev link target-id prereq-id-1,prereq-id-2

# Rebuild generated docs/projections
gaia dev build

# Validate registry
gaia dev validate

---

2) What files are source-of-truth?

• ✅ registry/nodes/**/*.json (Programmatically managed via CLI)
• ✅ registry-for-review/skill-batches/*.json (intake batches)
• ❌ DO NOT edit registry/nodes/*.json by hand unless correcting minor typos.
• ❌ DO NOT edit registry/gaia.json directly — it is an auto-generated artifact.
• ❌ Do not hand-edit generated docs/graph projections produced by build pipelines.

---

3) Branch naming (copy/paste)

Prefix	Use for	Scope
schema/...	schema + terminology changes	registry/schema/, *.md
cli/...	CLI / package code	src/gaia_cli/, packages/, tests/
docs/...	markdown/docs content	docs/, *.md
design/...	website UI assets	docs/ HTML/CSS/JS
review/gaia-push/...	intake PRs	registry-for-review/
review/meta/...	registry curation	registry/
infra/...	CI/tooling/config	.github/, scripts/

---

4) Naming + evidence minimums

Naming

• Skill IDs: kebab-case (web-scrape, parse-json)
• Display names: Title Case
• Skill types in graph: basic, extra, ultimate

Starless generic references vs. named skills

• Generic references are starless — they hold the shared, capability-level evidence inherited by all named children, but carry no stars of their own.
• Named skills add their own implementation-specific evidence and are rated 2★ to 6★.

Evidence Floors (G7 Trust Taxonomy)

• Evidence quality is measured via Evidence Grade (S/A/B/C) derived from trustNumber (S ≥ 250, A ≥ 100, B ≥ 50, C ≥ 20).
• Level requirements for named implementations:
  • 2★ (Named) requires Grade C+
  • 3★ (Evolved) requires Grade B+
  • 4★ (Hardened) requires Grade B+
  • 5★ (Transcendent) requires Grade B+
  • 6★ (Apex) requires Grade S + G7 Apex gate check
• The Star Bar (Installability): 3★+ skills must have a verified public repository link pointing directly to an implementation file (e.g. .../blob/<branch>/.../SKILL.md). Lacking a link triggers a hard demotion to 1★.
• Demerits: Canonical demerits (broken-evidence, niche-integration, experimental-feature, heavyweight-dependency) reduce effective rank by 1★ per entry (floored at 1★).
• Transparency Mandate: Every rank change must be recorded via a timeline event (e.g. rank_up, demote, fuse). Silent rank changes will fail the build's Transparency Gate check.