Skill Format

​

Why this exists

• #887 (skill auto-synthesis) and #553 (self-improving agent) will emit SKILL.md files via skill extraction. The field names they write must be the field names this spec defines.
• #1451 (tool-loader Part 3) reads the tools_required field to union a recipe’s tools into per-turn tool selection — a hard cross-spec dependency already written down in tool-loader.mdx.
• #647 (marketplace) and #648 (OEM bundling) need a stable definition of “a skill” and its trust tiers to publish and pre-bundle.

​

Prior art (credit before contribution)

​

Decided design

​

Adopted base (Agent Skills standard)

​

The metadata.gaia namespace

metadata:
  gaia:
    security_tier: verified        # verified | community | experimental (default: experimental)
    permissions:                   # <domain>:<level>[:scope] — see Permission model
      - network:read:*.brave.com
    requirements:                  # all optional; defaults = no constraint
      model: ">=7B"                # minimum parameter count (advisory)
      context: ">=8K"              # minimum context window
      python: ">=3.10"
      dependencies: [requests>=2.31]
      node_dependencies: ["@brave/brave-search-mcp-server"]
      env_vars: [BRAVE_API_KEY]
      hardware: { npu: optional, gpu_vram: ">=0GB" }
    tools:                         # tools this skill PROVIDES (its own @tool fns)
      - name: search_web
        description: Search the web for current information
        parameters:
          query: { type: string, required: true }
          max_results: { type: integer, required: false, default: 5 }
        returns: { type: object }
        atomic: false              # maps to @tool(atomic=...)
    tools_required: []             # registry tools this skill CONSUMES (recipe contract)

​

tools vs tools_required — never conflate them

​

Field reference

​

Naming

​

Permission model

​

Bridge to the connector grant model — no parallel ledger

• network:* and mcp:connect resolve, at scope-time, to a ConnectorRequirement(connector_id, scopes, reason) (connectors/providers/base.py:23) — the same frozen primitive agents already declare via REQUIRED_CONNECTORS (agent.py:295). The skill’s permissions become the agent’s connector requirements when the skill is scoped in.
• filesystem:*, shell:*, database:*, desktop:*, env:* are new local-capability domains with no connector equivalent. They are enforced by the skill sandbox (PROPOSED — see Phased build).

​

Security tiers

​

Tool registration

# web-research/tools.py
from gaia.agents.base.tools import tool

@tool
def search_web(query: str, max_results: int = 5) -> dict:
    """Search the web for current information."""
    ...

​

CLI

gaia skill list                       # acceptance #5
gaia skill install web-research        # acceptance #5
gaia skill install some-skill --allow-experimental
gaia skill remove web-research         # acceptance #5
gaia skill info web-research
gaia skill search "web search"
gaia skill update web-research
gaia skill migrate ./hermes-skill/ --from auto   # see Compatibility
gaia skill publish ./my-skill/         # marketplace (#647)

​

Agent UI dashboard support

GET    /api/skills                 # list installed skills (+ tier, version)   PROPOSED
GET    /api/skills/{name}          # skill detail (manifest, permissions)      PROPOSED
POST   /api/skills/install         # install from registry/path                PROPOSED
DELETE /api/skills/{name}          # remove                                    PROPOSED

​

Cross-format compatibility & migration

​

Relationship to neighbors

• Agent Skills — owns the architecture and integration surface (discovery roots, progressive disclosure, scoping, the skill/tool/agent distinction). This doc owns the field grammar. Where they overlap, that spec is canonical for the compatibility surface and this one for the schema; the two are reconciled (see Correcting the prior spec).
• Agent Manifest (#462) — a gaia-agent.yaml references skills by name + version range; SKILL.md is the skill-level complement. The skills: block and its resolution live in Agent Skills → Agent Hub integration.
• Agent bundles — skill packaging relates to the existing agent bundle format (.zip + bundle.json, BUNDLE_FORMAT_VERSION = 1, export_import.py:40).
• Builder template — scaffolds agent.py today (builder/template.py); emitting SKILL.md is a future extension, not current behavior.
• OEM bundling (#648) — needs a stable definition of “a skill” to pre-configure hardware SKUs. A SKU pre-bundles skills as verified-tier entries in a discovery root; the directory anatomy and tier defaults this doc fixes are that definition.

​

Example skills

---
name: incident-review
description: Walk through a production incident postmortem. Use when the user mentions an outage, incident, or postmortem.
---

# Incident Review

1. Establish the timeline from first alert to resolution.
2. Separate root cause from contributing factors.
3. Draft action items with owners — never "the team".

---
name: web-search
description: Search the web via the Brave Search API. Use when the user asks about current events or external facts.
license: MIT
version: 1.0.0
metadata:
  gaia:
    security_tier: verified
    permissions:
      - network:read:*.brave.com
    requirements:
      python: ">=3.10"
      dependencies:
        - requests>=2.31
      env_vars:
        - BRAVE_API_KEY
    tools:
      - name: search_web
        description: Search the web for current information
        parameters:
          query: { type: string, required: true }
          max_results: { type: integer, required: false, default: 5 }
        returns: { type: object }
        atomic: false
---

# Web Search

A self-contained Brave Search wrapper — `search_web` is this skill's own
`@tool`, backed by the skill's `tools.py`.

---
name: triage-support-ticket
description: Triage an inbound support ticket end to end. Use when the user pastes a support ticket or asks to triage one.
version: 0.2.0
metadata:
  gaia:
    security_tier: experimental
    tools_required:
      - query_documents
      - read_file
      - remember
---

# Triage a Support Ticket

1. Pull matching policy docs with `query_documents`.
2. Read any attached log with `read_file`.
3. Record the disposition with `remember` for follow-up.

---
name: rag-search
description: Search and answer over indexed documents. Use when the user asks about the contents of uploaded files.
version: 1.0.0
metadata:
  gaia:
    security_tier: verified
    permissions:
      - filesystem:read
    tools:
      - name: query_documents
        description: Answer a question over all indexed documents
        parameters:
          query: { type: string, required: true }
        returns: { type: object }
      - name: search_indexed_chunks
        description: Return the top matching chunks for a pattern
        parameters:
          pattern: { type: string, required: true }
        returns: { type: object }
      - name: list_indexed_documents
        description: List documents currently in the index
        parameters: {}
        returns: { type: object }
---

# RAG Search

Use `query_documents` for direct answers; `search_indexed_chunks` to inspect
evidence; `list_indexed_documents` to see what is available.

---
name: web-research
description: Research the open web. Use when the user asks about current events or facts not in the documents.
version: 1.0.0
metadata:
  gaia:
    security_tier: verified
    permissions:
      - network:read
    tools:
      - name: search_web
        description: Search the web for current information
        parameters:
          query: { type: string, required: true }
        returns: { type: object }
      - name: fetch_page
        description: Fetch and extract the readable text of a URL
        parameters:
          url: { type: string, required: true }
        returns: { type: object }
      - name: download_file
        description: Download a file from a URL to local disk
        parameters:
          url: { type: string, required: true }
        returns: { type: object }
---

# Web Research

Search first, then fetch the best results; download only when the user asks for
the file itself.

---
name: file-operations
description: Read, write, and edit files on the local workspace. Use when the user asks to inspect or modify files.
version: 1.0.0
metadata:
  gaia:
    security_tier: community
    permissions:
      - filesystem:read
      - filesystem:write:./**
    tools:
      - name: read_file
        description: Read the contents of a file
        parameters:
          file_path: { type: string, required: true }
        returns: { type: object }
      - name: write_file
        description: Write content to a file
        parameters:
          file_path: { type: string, required: true }
          content: { type: string, required: true }
        returns: { type: object }
      - name: edit_file
        description: Replace a span of text in an existing file
        parameters:
          file_path: { type: string, required: true }
          old_content: { type: string, required: true }
          new_content: { type: string, required: true }
        returns: { type: object }
---

# File Operations

Read before you write; prefer `edit_file` for in-place changes over rewriting a
whole file with `write_file`.

# BEFORE — Hermes
---
name: pdf-extract
description: Extract structured data from a PDF.
version: 1.0.0
metadata:
  hermes:
    category: documents
    requires:
      tools: [read_file]
---

# Extract from PDF
...

# AFTER — gaia skill migrate --from hermes
---
name: pdf-extract
description: Extract structured data from a PDF.
version: 1.0.0
metadata:
  gaia:
    security_tier: experimental
    tools_required:
      - read_file
---

# Extract from PDF
...

# BEFORE — OpenClaw
---
name: git-status
description: Summarize the working tree status.
version: 0.3.0
metadata:
  openclaw:
    requires:
      bins: [git]
---

# Git Status
...

# AFTER — gaia skill migrate --from openclaw
---
name: git-status
description: Summarize the working tree status.
version: 0.3.0
metadata:
  gaia:
    security_tier: experimental
    permissions:
      - shell:execute:git
---

# Git Status
...

​

Off-states (safe floors)

​

Correcting the prior spec

The base standard is Agent Skills (agentskills.io), not OpenClaw. The prior draft framed “OpenClaw / ClawHub” as the external standard to be compatible with. In fact agentskills.io (as used by Claude Code) is the base GAIA adopts; OpenClaw is just one of several compatible third-party formats, alongside Hermes. This reconciles skill-format.mdx with Agent Skills, which had already flagged “OpenClaw/ClawHub” as a placeholder from an earlier draft.

​

KPIs

​

Phased build

​

Phase 0 — Format contract (this revision)

• Schema decided: adopted base + metadata.gaia; tools vs tools_required separated; compatibility/allowed-tools excluded.
• Agent Skills reconciled — mapping table nests metadata.gaia.*, the placeholder Note becomes a Division-of-authority Note, and allowed-tools/compatibility are marked excluded.
• All example skills parse; the three acceptance-#6 skills use only real registry tool names.
• Traceability covers 100% of #691 acceptance criteria.

​

Phase 1 — Loader, validator, CLI core (PROPOSED)

• A tool skill loads and its tools register and call.
• A bare standard skill loads instruction-only.
• Validation fails loudly on a tools/tools.py mismatch or a permission that exceeds the tier ceiling — no partial load.

​

Phase 2 — Permission enforcement + tier ceilings + connector bridge (PROPOSED)

• A skill requesting a permission above its tier ceiling fails to load.
• A network:* / mcp:connect permission produces the matching connector grant requirement; filesystem/shell/database/desktop route to the sandbox.

​

Phase 3 — Agent UI dashboard + migration (PROPOSED)

• The panel lists installed skills with tier + version and supports install/remove (acceptance #4).
• migrate output validates and lands experimental for Hermes and OpenClaw inputs.

​

Phase 4 — Marketplace + consumer wiring (PROPOSED; #647 / #887 / #1451)

• #887-synthesized files validate against this schema unchanged.
• #1451 unions a matched skill’s tools_required ahead of semantic results (the contract in tool-loader.mdx).

​

Open questions

1. tools_required validation timing. Fail-vs-skip is not open — GAIA’s fail-loudly policy settles it: a name unknown to the framework is a manifest defect and fails loudly; a name valid but inactive in the current agent’s registry is scoping (omitted + logged, not an error). The genuine open nuance is when the unknown-name check runs — at install against a static tool catalog, or deferred — since the active registry is assembled dynamically from mixins and other skills, so the full tool universe may not be known at install time. Affects #1451 robustness.
2. Skill→skill dependencies. The prior draft allowed a skill to depend on other skills (requirements.skills). Keep it under metadata.gaia.requirements, or defer dependency resolution to the marketplace (#647)?
3. /api/skills install sources. Registry-only, or also local path / URL? The latter widens the install-time security surface.
4. Body-injection scanning. Static scanning of instruction bodies for injection patterns at import — required for community+, advisory for experimental? (Also open in Agent Skills → Open questions; resolve in one place.)
5. docs/spec/ relocation. #691 acceptance says “documented in docs/spec/”; this doc stays in docs/plans/ until the loader ships. Does the move to docs/spec/ (and the docs.json update) happen with Phase 1, or earlier?

​

Current state of the code

​

Dependencies

​

Acceptance-criteria traceability