Skip to content

Schema Reference

Jump to bottom
mbtiongson1 edited this page Jun 22, 2026 · 5 revisions

Schema Reference

Authoritative field definitions for every JSON and Markdown schema in the repository. Canonical schema files live in registry/schema/.

registry/nodes/ — Modular Skill Definitions (SOURCE OF TRUTH)

The canonical source of truth for all skills. Each skill is stored as an individual JSON file within domain-specific subdirectories (e.g., registry/nodes/basic/).

Skill Node Structure

{
  "id": "web-scrape",                    // kebab-case, camelCase validation pattern
  "name": "Web Scrape",                  // Title Case display name
  "type": "extra",                       // "basic" | "extra" | "unique" | "ultimate"
  "description": "...",                  // clear, agent-agnostic definition (min 10 chars)
  "prerequisites": [                     // IDs of parent skill nodes
    "web-search",
    "parse-html"
  ],
  "derivatives": [                       // IDs of child skill nodes
    "knowledge-harvest"
  ],
  "knownAgents": [],                     // list of adopter/demonstrated agent names
  "status": "validated",                 // "provisional" | "validated" | "disputed" | "deprecated"
  "createdAt": "2026-04-26",             // ISO 8601 date
  "updatedAt": "2026-06-23",             // ISO 8601 date
  "version": "1.0.0",                    // semantic version of this node definition
  
  // Optional and recomputed G7 properties:
  "title": "The Weaver's Shuttle",       // optional lore title
  "summary": "Fast extraction of data",  // optional brief summary
  "useCase": "...",                      // optional description of real usage scenario
  "directives": "...",                   // optional execution constraints
  "conditions": "",                      // optional fusion condition text
  "evidence": [                          // array of graded evidence entries
    {
      "type": "github-stars-own",        // evidence type (provenance) from meta.json
      "grade": "B",                      // recomputed row grade (S|A|B|C), or absent
      "source": "https://github.com/...", // URL to source evidence
      "evaluator": "reviewer-user",      // GitHub username of reviewer
      "date": "2026-06-22",              // ISO date of evaluation
      "sourceStartedAt": "2026-01-15",   // ISO date repo/publication was first started
      "notes": "..."                     // evaluation comments
    }
  ],
  "verification": {
    "tier": "community-verified",        // highest verified tier met (or null)
    "tierEvaluatedAt": "2026-06-23T...", // ISO timestamp of evaluation
    "firstEvidenceAt": "2026-04-26T..."  // tenure baseline timestamp (first evidence)
  },
  "trustMagnitude": 125.4,               // unbounded recomputed G7 Trust Magnitude score
  "overallTrustGrade": "A",              // recomputed grade (S|A|B|C|ungraded)
  "provisional": false,                  // true if using the 6-month G7 diversity grace window
  "provisionalUntil": "2026-12-23"       // date when grace period expires (if provisional)
}

Important

The legacy rarity and level fields are completely deprecated and removed from modular skill definitions. Quality is now expressed via overallTrustGrade (S/A/B/C/ungraded) derived from the evidence-driven trustMagnitude and diversity gates.

registry/gaia.json — Canonical Skill Graph (GENERATED)

This file is an auto-generated artifact compiling the individual modular node definitions into a single contiguous DAG. Do not edit this file directly; changes are overwritten when running compiling scripts.

Top-Level

Field Type Description
version string Consolidated semantic version of the registry schema
generatedAt string ISO timestamp of the compile run
skills Array Flat collection of all consolidated skill nodes
edges Array Prerequisite connections derived from the prerequisites lists

registry/named/{contributor}/{skill}.md — Named Skill

YAML frontmatter defines the named skill metadata; the Markdown body serves as developer-facing implementation documentation.

---
id: karpathy/autoresearch                 # unique ID in contributor/skill-name format
name: AutoResearch                        # display name
contributor: karpathy                     # GitHub username
origin: true                              # true if first contributor to map to this genericSkillRef
genericSkillRef: autonomous-research      # generic skill ID node from registry/nodes/
status: named                             # "awakened" (contributor draft) | "named" (promoted)
level: 4★                                 # implementation level rating (2★–6★; 1★ is demote penalty)
description: Autonomous literature searcher and academic paper synthesizer.
links:
  github: https://github.com/karpathy/autoresearch
  docs: https://...
  canonicalRepo: https://github.com/...   # canonical URL for merging fork-star networks
createdAt: 2026-04-29
updatedAt: 2026-06-23
---

## Overview
A detailed walkthrough of this specific implementation...

Key Validation Rules (registry/schema/namedSkill.schema.json):

  • Contributors must submit as status: awakened.
  • genericSkillRef must point to an awakened (level $\ge$ 1★) generic node.
  • At most one origin: true named skill is permitted per generic skill bucket.
  • The level rating must be within 2★ to 6★.

registry/named-skills.json — Named Skill Index (Generated)

An auto-generated JSON lookup map compiled from named markdown files. It maps generic skill IDs (keys) to arrays of their registered named implementation objects (buckets), ordered with origin: true implementations appearing first. Do not edit directly.

registry-for-review/skill-batches/{id}.json — Skill Batch

Generated when a contributor runs gaia dev push. A batch lists proposed changes (skills, fusions, or evidence additions) for review. It follows the schema in registry/schema/skillBatch.schema.json.

.gaia/config.json — Project Config

Local client configuration file stored in the user's home directory. Tracks project defaults:

  • gaiaUser: The default GitHub username of the developer.
  • registryPath: Local checkout path of the Gaia Skill Tree repository.
  • verifiers: Local verifier configuration.

skill-trees/{username}.json — User Skill Tree

Tracks an individual contributor's unlocked skills. Follows the schema in registry/schema/skillTree.schema.json.

  • username: Contributor's GitHub username.
  • unlockedSkills: Dictionary mapping skill IDs to achievement details (unlocked timestamp, level, current overall trust grade).
  • stats: Consolidated counts of unlocked basic, extra, unique, and ultimate skills.

Edge Schema (Legacy/Generated)

Defined in registry/schema/combination.schema.json. Contains prerequisite mapping details. These edges are derived automatically from node properties and assembled into registry/gaia.json.

Schema Metadata

registry/schema/meta.json is the single source of truth for nomenclature, theming, colors, and validation rules. It defines:

  • Level labels (0★ = Basic, 1★ = Awakened, 2★ = Named, 3★ = Evolved, 4★ = Hardened, 5★ = Transcendent, 6★ = Apex).
  • Minimum prerequisite requirements per skill type (basic = 0, extra = 2, unique = 0, ultimate = 5).
  • Evidence Type definitions, weights, and grade floors used by the G7 trust magnitude recomputation scripts.
  • Trust magnitude grade thresholds (S $\ge$ 250, A $\ge$ 100, B $\ge$ 50, C $\ge$ 20).

Clone this wiki locally