Skip to content

Named Skills

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

Named Skills

Named skills are real contributor implementations of generic skills in the registry. They give identity to abstract capabilities: instead of a generic "web scrape" skill, you get karpathy/autoresearch — a specific, installable, attributable implementation.

Concept

The Gaia registry maintains a two-layer structure:

Layer Location Purpose
Generic registry/nodes/**/*.json Abstract skill definitions — vendor-agnostic, defining prereqs and evidence requirements.
Named registry/named/{contributor}/{skill}.md Concrete, installable implementations authored by a named contributor.

A named skill is always linked to a generic skill via its genericSkillRef property. Multiple named skills can map to the same generic skill — they form a bucket of implementations for that skill.

Bucket System

Each generic skill maintains a bucket of named implementations.

generic: autonomous-debug
  └── bucket:
        ├── devin-ai/autonomous-swe  (origin: true, level: 3★)
        └── your-username/my-debugger (origin: false, level: 2★)

The first contributor to successfully publish a named skill in a given bucket gets origin: true. Subsequent contributions must specify origin: false. The registry compilation scripts automatically compile these definitions into the index file registry/named-skills.json, keyed by the genericSkillRef.

Browsing Named Skills

You can view available named skills using the command line:

  • List all named skills: 
    gaia skills list
  • Search named skills by name/description: 
    gaia skills search "autonomous research"
  • Show metadata for a specific named skill: 
    gaia skills info karpathy/autoresearch

Installing a Named Skill

To install a named skill and make its assets or scripts executable locally or globally:

  • Install to the global directory (~/.gaia/skills/): 
    gaia skills install karpathy/autoresearch --global
  • Install to the local directory (current project .gaia/skills/): 
    gaia skills install karpathy/autoresearch --local

Uninstalling

To remove a previously installed named skill:

gaia skills uninstall karpathy/autoresearch

Publishing Your Own Named Skill

Prerequisite

The generic skill must already be awakened (1★ or above in the registry nodes) before a named skill can map to it. If the generic skill is not yet in the registry, you must first propose it.

Step 1 — Propose from the registry

To draft a new named skill proposal, run the propose command specifying the generic skill and your target ID:

gaia propose web-search --target your-username/my-skill

You can also run it interactively to select from a list of eligible generic skills:

gaia propose

This command creates a new markdown file at registry/named/your-username/my-skill.md pre-populated with YAML frontmatter.

Step 2 — Edit the generated file

Open registry/named/your-username/my-skill.md and edit its YAML block and body content:

---
id: your-username/my-skill
name: My Awesome Searcher
contributor: your-username
origin: true            # true only if you are the first contributor to claim this bucket
genericSkillRef: web-search
status: awakened
level: 2★               # Min level for named implementations is 2★
description: A concrete implementation of X that performs fast local search.
links:
  github: https://github.com/your-username/my-skill-repo
createdAt: 2026-06-23
updatedAt: 2026-06-23
---

## Overview
A detailed overview of how your named skill works, build instructions, and execution details.

Ensure status is set to awakened (reviewers will promote it to named after verification). The level must be 2★ or above.

Tip

You can update this frontmatter programmatically using: gaia dev update-named your-username/my-skill --level 3★ --status awakened

Step 3 — Open a PR

Push your branch to GitHub and create a draft PR. The automated validation workflow compiles the registry and ensures:

  • Markdown frontmatter conforms to registry/schema/namedSkill.schema.json.
  • genericSkillRef resolves to a valid generic skill node ID.
  • At most one origin: true exists in the bucket.
  • The level is set to a valid grade.

Named Skill File Format

The named skill markdown files are validated against the schema defined in registry/schema/namedSkill.schema.json.

Field Required Type Description / Notes
id Yes string Unique named skill identifier in the pattern contributor/skill-name.
name Yes string Title-case display name.
contributor Yes string Contributor's GitHub username.
origin Yes boolean true if this is the first implementation in this generic skill's bucket.
genericSkillRef Yes string The ID of the generic skill node it implements.
status Yes string Must be awakened (under review) or named (accepted and integrated).
level Yes string Level rating (2★ to 6★).
description Yes string Summary of the implementation.
links.github No string URL of the public repository containing the code.
links.docs No string URL of documentation pages.
createdAt Yes string Creation timestamp (YYYY-MM-DD).
updatedAt Yes string Last modification timestamp (YYYY-MM-DD).

Clone this wiki locally