Skill Fusion — Gaia Docs

Overview

The Gaia skill graph has a Type axis, a Branch axis, and a stars axis. Fusion moves a skill along the Type axis only — from Basic (no prerequisites) to Fusion (one or more prerequisites). It does not by itself change stars or Branch. A fusion result only earns a rank name like Extra or Ultimate later, when it's claimed as a Named Skill and climbs stars through evidence — a separate step from fusion itself (see Type vs. Branch).

Fusion happens at two levels that are entirely separate:

Player-level fusion — gaia fuse lets you fuse skills you own in your personal skill tree.
Registry-level fusion — gaia dev merge (Verifier-gated) proposes that two canonical nodes should become one.

Running gaia fuse does not add a new node to the public registry — it records the fusion in your skill-trees/<username>/skill-tree.json and writes a timeline event. Registry merges are separate, PR-driven operations.

Ascension Cycle — Fuse is step 5

📥

Register

🔍

Scan

⬆

Rank up

★

Name

◇

Fuse

◆

Apex

Fusion Paths

Fusion is not restricted to a fixed recipe list — the registry models which skill IDs are valid inputs for a given Fusion output, and gaia fuse validates against that model at runtime. Every fusion output carries Type fusion, whether it combines two Basic skills or two skills that are themselves Fusions.

○ Basic Skill A + ○ Basic Skill B → ◇ Fusion Path 1

◇ Fusion A + ◇ Fusion B → ◇ Fusion (deeper) Path 2

◉ Unique branch — not a fusion output

Unique is a Branch, not a Type. It applies to a Named Skill (2★+) that carries no suiteComponents and climbs to 4★+ through depth alone — Unique (4★), Unique Ultimate (5★), Unique Impossible (6★). Fusion never produces a Unique-branch result directly: a Unique-branch skill can be Type basic or Type fusion underneath, since Type and Branch are independent axes.

Path 1: Basic + Basic → Fusion

The most common fusion. Two or more Basic skills (○) whose capabilities combine into a qualitatively new emergent capability produce a Fusion skill (◇). The target must be defined in the registry beforehand — gaia fuse matches your unlocked skill set against known fusion recipes.

Path 2: Fusion + Fusion → Fusion

A Fusion skill can fuse with another Fusion (or a Basic) to produce a deeper, compositionally richer Fusion. The Type axis doesn't have a further step to climb to — however many layers of prerequisites a skill carries, its Type stays fusion. Common in reasoning and multi-step planning chains.

Ranks come later, not from fusion

Fusion only moves a skill along the Type axis. A fusion result earns a rank name — Extra (4★), Ultimate (5★), Apex (6★) on the Suite branch, or Unique / Unique Ultimate / Unique Impossible on the Unique branch — only after it's claimed as a Named Skill via gaia push or gaia propose and climbs stars through evidence. Which Branch it lands in depends on whether the Named Skill carries suiteComponents, not on how many times it was fused.

Prerequisites

Before running gaia fuse, three conditions must hold:

Condition	What it means	How to check
Input skills unlocked	All source skills are in your `skill-tree.json` at ≥ 1★	`gaia tree`
Fusion recipe exists	The registry defines a Fusion-type skill that lists those inputs as `components`	`gaia dev list --generic`
Fresh scan (optional but recommended)	Running `gaia scan` first surfaces all fusion candidates that match your repo's evidence	`gaia scan` then check promotion-candidates.json

💡 Stale candidates

gaia scan writes promotion-candidates.json fresh on every run — it does not expire on a timer. Re-run gaia scan whenever your skill tree or repo evidence changes, so gaia fuse is matching against current candidates.

gaia fuse Walkthrough

gaia fuse <skillId> opens an interactive terminal flow. It checks your unlocked skills against every known fusion recipe and presents only the ones you qualify for. Select the target fusion, confirm, and the CLI writes both the fused skill entry and a timeline event to your skill tree.

shell

# Scan first to surface current candidates (recommended)
gaia scan

# Fuse by target skill ID (the Fusion-type skill you want to unlock)
gaia fuse multi-step-tool-orchestration

# Or launch the interactive menu (no argument = pick from all eligible fusions)
gaia fuse

What the CLI does under the hood

1. Loads registry/gaia.json to find skills with a prerequisites list (fusion recipes).
2. Cross-references that list against skill-trees/<you>/skill-tree.json to filter down to fusions where you own all inputs.
3. Presents eligible fusions in an interactive selector.
4. On confirmation: appends an entry to unlockedSkills and writes a fuse timeline event with current UTC timestamp.

skill-tree.json — after fusion

{
  "unlockedSkills": [
    {
      "skillId": "multi-step-tool-orchestration",
      "level": "2★",
      "unlockedAt": "2026-06-11T17:30:00Z",
      "unlockedIn": "you/your-repo",
      "combinedFrom": ["tool-call-chaining", "context-window-management"]
    }
  ],
  "timeline": [
    {
      "skillId": "multi-step-tool-orchestration",
      "action": "fuse",
      "timestamp": "2026-06-11T17:30:00Z",
      "details": "Fused from: tool-call-chaining + context-window-management"
    }
  ]
}

💡 View your tree after fusing

Run gaia tree immediately after fusion to confirm the new Fusion-type skill appears with its ◇ glyph and combined-from attribution.

Proposing a New Fusion

If no fusion recipe exists for the combination you believe is real, you can propose one to the registry. A proposal requires:

A clearly named target skill (Type fusion) that does not yet exist in the registry.
At least two source skill IDs already present in the registry.
An argument for why the combination produces a qualitatively new emergent capability.
At least one piece of Grade C (Bronze) evidence or better attached to the proposed target.

The workflow is a gaia push with a new skill batch, followed by a PR against the intake layer. A Verifier then runs gaia dev merge to promote the proposal into the canonical registry.

shell — proposing a new Fusion-type skill

# Step 1: Dry-run to see what gaia push would submit
gaia push --dry-run

# Step 2: Push the batch to the intake layer (opens a PR)
gaia push

# In your push batch, include a skill with type: "fusion"
# and a prerequisites[] list referencing the source skill IDs

Batch format for a Fusion-type skill

YAML — gaia push batch snippet

name: Multi-Step Tool Orchestration
type: fusion
description: >
  Chains multiple tool calls across context turns while maintaining
  state — an emergent capability not reducible to either component.
prerequisites:
  - tool-call-chaining
  - context-window-management
evidence:
  - url: "https://github.com/you/agent-demo"
    class: C

⚠ Always dry-run first

Run gaia push --dry-run before a real push. The dry run validates your batch schema and shows you exactly which skills would be submitted without touching the intake layer.

Registry-Level Fusion

Registry-level fusion merges two canonical nodes into one. This is a Verifier-only operation that requires gaia whoami to return verifier or override authorization. It is the mechanism Verifiers use when approving a fusion proposal from the intake layer.

shell — Verifier-only

# Check authorization first
gaia whoami

# Merge source nodes into a target node
# target-id must already exist in the registry (or be the new node)
gaia dev merge target-id source-id-1 source-id-2

# Example: promote a fusion proposal from intake
gaia dev merge multi-step-tool-orchestration \
  tool-call-chaining context-window-management

⚠ Programmatic-first policy

All registry mutations — including fusion — must go through gaia dev merge. Direct edits to registry/nodes/ are deprecated and will fail the Meta Guard CI check.

Player vs Registry Fusion

The two fusion surfaces are independent — knowing when to use each prevents confusion:

Dimension	Player fusion (`gaia fuse`)	Registry fusion (`gaia dev merge`)
Who	Any registered contributor	Verifier (4★) or CI with GAIA_OPERATOR_OVERRIDE
What changes	`skill-trees/<username>/skill-tree.json`	`registry/nodes/` and `registry/gaia.json`
Requires PR	✗ local-only	✓ always a PR
Visible to others	Only if you push your skill tree branch	✓ public after merge
Timeline event	✓ written automatically	✓ written by the merge command
Recipe must exist first	✓ registry must already have the Extra/Ultimate node	✗ the merge can create it

💡 The typical flow

A contributor proposes a new fusion via gaia push → a Verifier reviews the intake PR → Verifier runs gaia dev merge to add it to the canonical registry → any contributor can now run gaia fuse to claim it in their personal tree.