Named Skills

A Named Skill is a canonical skill attached to a real contributor. This page explains the distinction from generic references, the five-step lifecycle from scan to 4★ Verifier, and how to claim origin.

What is a Named Skill?

A Named Skill is a canonical registry skill that has been claimed by a real contributor with at least Class C evidence (first sighting). At the moment of naming, the skill ranks up to 2★ (Named) and the contributor becomes its Origin Contributor — a permanent, auditable record in the graph.

Named Skills display in honor red in the CLI and the Atlas. The Origin Contributor field is one-per-skill and immutable after the naming PR merges — re-attribution requires a maintainer decision with a timeline event.

Not to be confused with "unlocked skills." A player's skill-tree.json tracks which skills a user has unlocked in their own tree. Named Skills are a registry concept — they live in registry/named/ and describe public, contributor-attributed implementations of canonical skill IDs.

Generic references vs Named Skills

The registry uses two distinct concepts that developers sometimes conflate. Understanding the difference matters for curation and for reading CLI output.

Generic (starless) reference
web-scrape
  • A taxonomy node — a slot in the capability graph
  • Carries no stars of its own; stars live only on its named children
  • Effective rank = highest star among named implementations
  • Holds capability-level (Class A / academic) evidence that all named children inherit
  • Renders as generic, italic, greyed-out in the UI
  • Created via gaia dev add, no contributor required
Named Skill
★ karpathy/web-scrape
  • An implementation of a generic reference, attributed to a contributor
  • Has its own stars (2★ minimum on claiming)
  • Carries implementation-specific evidence on top of the inherited base
  • Has a SKILL.md at a public GitHub URL (links.github)
  • Renders with contributor name in honor red
  • Created via naming PR — contributor must have Class C evidence or better
Key rule: never assign stars directly to a generic reference. Stars belong to named implementations. Leave ranking to the named children.

Origin & variants

Each generic reference can have multiple Named Skill implementations — this is the "bucket." Within a bucket, one implementation carries the origin: true flag — it is the Origin, the first and most canonical implementation of that capability. All others are variants.

An Origin implementation typically has the strongest evidence and the highest stars in the bucket. The CLI and the UI both surface the role distinction.

Example bucket — generic: web-scrape
web-scrape   (starless, generic)
★ origin karpathy/web-scrape 3★ · Firecrawl-backed deep scraper
variant johndoe/web-scrape-stealth 2★ · Stealth-mode scraper with rotation
CLI command (when implemented): gaia lookup web-scrape lists all bucket entries with role labels. See issue #71 for the full spec.

Frontmatter fields

registry/named/karpathy/web-scrape.md
---
id: karpathy/web-scrape
name: Web Scrape
contributor: karpathy
origin: true                   # this implementation is the bucket origin
genericSkillRef: web-scrape    # parent generic node
status: named
level: "3★"
links:
  github: https://github.com/karpathy/myagent/blob/main/skills/web-scrape/SKILL.md
---

Lifecycle

A Named Skill moves through five states from first detection to Verifier status. Each transition requires evidence — stars are never declared, only derived.

1
0★ — Unawakened (generic)
Detected by scanner
gaia scan finds a SKILL.md in a project. A promotion candidate is written to generated-output/promotion-candidates.json. No registry entry exists yet — the skill is visible only in the local context.
2
1★ — Awakened
Promoted to the canonical graph
A reviewer runs gaia dev add (or a curation pipeline) to create a generic registry entry. The skill is now in the public graph at 1★, starless. No contributor is attributed yet.
3
2★ — Named
Claimed with Class C evidence
A contributor opens a naming PR with at least Class C evidence (first sighting — a SKILL.md at a public URL). The PR creates or updates registry/named/<contributor>/<skill-name>.md with origin: true and level: "2★". The contributor becomes the Origin Contributor permanently.
4
3★ — Evolved
Reproducible evidence added
The contributor adds Class B evidence — a reproducible, documented demonstration. The PR runs gaia dev evidence skill-id "url" --class B and calibrates to 3★. A links.github URL pointing to a public repository is mandatory at this level.
5
4★ — Hardened (Verifier threshold)
Battle-tested, peer-reviewed
Reaching 4★ requires Class A evidence — peer review or battle-tested production use. At this rank the contributor becomes a Verifier, authorized to review and approve other contributors' naming PRs via gaia whoami → verifier path.

Evidence system

The evidence system is being upgraded from a single axis (Evidence Class) to a two-axis model (Evidence Type + Evidence Grade). Both coexist in the schema during the transition.

Legacy: Evidence Class (deprecated)

The original single axis conflated provenance and quality into one letter. It remains valid in the schema until the next major release but should not be used for new evidence entries.

ClassMeaningExample
A Battle-tested, peer-reviewed Academic paper, public benchmark, production audit
B Reproducible, documented Public SKILL.md with a working implementation
C First sighting — minimum for naming A SKILL.md file found in a contributor's repository
Class ≠ Grade. Evidence Class letters (A/B/C) are not the same as the new Evidence Grade letters (S/A/B/C). Never read one axis as the other. The Grade axis runs S (Platinum) → A (Gold) → B (Silver) → C (Bronze).

Current: Evidence Type + Grade

New evidence should carry a Type (where a demonstration comes from) and a Grade (how strong it is), derived from an underlying trust number. An Overall Trust Grade accumulates all evidence for a skill to establish confidence beyond reasonable doubt.

GradeLabelTrust number threshold
SPlatinum≥ 90
AGold≥ 80
BSilver≥ 60
CBronze≥ 40
ungraded Below threshold < 40 — on the record but counts toward no gate

Evidence types currently supported: arxiv, repo, github-stars. New types extend the list in meta.json without a schema change. GitHub stars are treated as proxy (secondary) evidence — they supplement, never replace, primary evidence.

Adding evidence via CLI

bash
# Add evidence — still accepted for Class B/A if transitional
gaia dev evidence skill-id "https://github.com/owner/repo/blob/main/SKILL.md" \
  --class B \
  --notes "Reproducible demo with tool-call trace"

# Verify an evidence entry (requires Verifier authorization)
# Sets evidence.verified: true in the node
gaia dev verify skill-id 0   # index of the evidence entry

Claiming a Named Skill

Claiming attaches your GitHub identity to a canonical skill as its Origin Contributor. The claim is permanent — re-attribution requires a maintainer decision. Do not claim skills you did not originate.

What you need

  • ✓ A SKILL.md file in a public GitHub repository (minimum Class C evidence)
  • ✓ A links.github URL using the blob/branch/subpath format — never tree/
  • ✓ A review/meta/ branch (schema changes require schema/)
  • ✓ gaia dev validate passing with no errors

Step-by-step

bash — naming PR workflow
# 1. Create your branch
git checkout -b review/meta/karpathy-web-scrape origin/main

# 2. Ensure the generic node exists (creates it at 1★ if not)
gaia dev list --generic | grep web-scrape
# If missing:
gaia dev add "Web Scrape" --type basic \
  --description "Drives a browser to scrape structured data from web pages" \
  --no-build

# 3. Add the Named Skill frontmatter
# Create: registry/named/karpathy/web-scrape.md
# (See the frontmatter example above — manually create this file)

# 4. Add Class C evidence (first sighting)
gaia dev evidence web-scrape \
  "https://github.com/karpathy/myagent/blob/main/skills/web-scrape/SKILL.md" \
  --class C --notes "Origin SKILL.md, first documented implementation" \
  --no-build

# 5. Set level and regenerate index
gaia dev calibrate web-scrape "2★" --no-build
python3 scripts/generateNamedIndex.py

# 6. Final build + validate
gaia dev build
gaia dev validate

# 7. Commit and push
git add registry/named/karpathy/ registry/named-skills.json
git commit -m "[named] karpathy/web-scrape — claim origin, Class C evidence"
git push -u origin review/meta/karpathy-web-scrape
Never run gaia push without --dry-run first. The push command opens a public GitHub issue. Dry-run lets you review the proposed batch before committing.

Verifier threshold

A contributor who holds any Named Skill at 4★ or above becomes a Verifier — they are authorized to run mutating gaia dev subcommands and to approve other contributors' naming PRs.

Verifier status is checked at runtime by reading registry/named-skills.json. It is automatic — no manual assignment needed. Run gaia whoami to see which authorization path applies to you.

bash
gaia whoami

# Example output:
# contributor: karpathy
# via: verifier
# 4★+ named skills: [web-scrape (4★), autoresearch (5★)]
Bootstrap mode: a registry with zero Verifiers auto-allows all actors. Gating activates automatically once the first 4★ Named Skill lands. Set GAIA_OPERATOR_OVERRIDE=1 in CI pipelines that must mutate the registry after gating is active.

Installability

Named Skills are installable if they have a valid links.github field pointing to a public repository with a SKILL.md. The install pipeline reads only links.github — other link keys are ignored.

StarsNo links.githubAction
0★ – 2★ Allowed Tag installable: false in frontmatter — registry-only
3★+ Not allowed Demote to 2★ until a verified link is confirmed

URL format

yaml frontmatter
# ✅ Correct — installer extracts subpath
links:
  github: https://github.com/owner/repo/blob/main/.agents/skills/my-skill

# ❌ Broken — bare repo root, skill is undiscoverable
links:
  github: https://github.com/owner/repo

# ❌ Broken — tree/ not recognised by _parse_github_url
links:
  github: https://github.com/owner/repo/tree/main/.agents/skills/my-skill

Wrong key names

Wrong keyFix
links.repoRename to links.github
links.docsRename to links.github (strip any #fragment)
links.arxivAdd links.github alongside — keep arxiv
origin: https://…Move URL to links.github, set origin: false

Suites are always exempt

Skills with a suiteComponents list (e.g. garrytan/gstack) install by iterating their components. They do not need links.github at the suite level. Never flag suites as uninstallable.