feat(skills): SKILL.md support — build, load, share agent skills via agentskills.io standard

[kovtcharov-amd]

Why this matters

Before: Building a GAIA agent with reusable capabilities requires writing a full Python class, inheriting from Agent, and wiring tool mixins by hand. There is no way to share a single capability (e.g., "web search" or "git operations") across agents without copy-pasting code. And there is no path to consuming the 800K+ skills already published to community registries.

After: Drop a SKILL.md file into ~/.gaia/skills/, and any GAIA agent can discover and load it at runtime. Skills authored for Claude Code, Codex CLI, Gemini CLI, or GitHub Copilot work in GAIA with zero modification -- and vice versa.

Industry landscape

The agentskills.io open standard (v1.0.0, published Dec 2025) has become the cross-platform skill format:

Platform	How skills work	Skills ecosystem
Claude Code	Origin of the spec. ~/.claude/skills/ auto-discovered at startup. Progressive loading: frontmatter then description match then full body	First-party + community via SkillsMP (800K+ indexed)
Codex CLI	~/.codex/skills/ + repo .codex/skills/. One-command install via $skill-installer. Plugins bundle skills + MCP config	OpenAI curated catalog + SkillsMP
GitHub Copilot	.github/skills/ in repo or ~/.copilot/skills/ personal. Auto-discovery in VS Code + Visual Studio 2026. Forked context for large skills	.NET skills from Microsoft, community repos
smolagents (HuggingFace)	Proposed activate_skill(name) API. CodeAgent reads SKILL.md from mounted filesystem. Tools vs. skills distinction (hands vs. knowledge)	Hub integration for sharing tools; skills feature under discussion
Spring AI	Java @Skill annotation. Skills are modular, reusable agent capabilities with structured I/O	Framework-native, no marketplace

Key insight: The standard is minimal by design -- just a YAML frontmatter (name, description) + Markdown body. GAIA's existing docs/plans/skill-format.mdx spec adds GAIA-specific extensions (permissions, security tiers, hardware hints) on top of this base, which is the right layering.

What GAIA already has

Component	Status	Location
SKILL.md spec (draft)	Planning	docs/plans/skill-format.mdx
agentskills.io adoption decision	Scoped (#888)	--
@tool decorator + registry	Shipped	src/gaia/agents/base/tools.py
KNOWN_TOOLS mixin map	Shipped	src/gaia/agents/registry.py
BuilderAgent (scaffolds agents)	Shipped v0.17.2	src/gaia/agents/builder/
Custom agent hot-reload	Shipped	AgentRegistry.register_from_dir()
Namespaced agent IDs	Shipped	custom:<hash>:<id> in registry

What is missing: No SkillManager, no ~/.gaia/skills/ scanning, no SKILL.md parser, no gaia skill CLI, no runtime skill loading into agents, no UI for managing skills.

Scope

Phase 1 -- Parse + load (v0.20.0)

Goal: A developer can write a SKILL.md, drop it in ~/.gaia/skills/, and agents load it.

1. SKILL.md parser (src/gaia/skills/format.py)

   • Parse agentskills.io-compliant YAML frontmatter + Markdown body into a Skill dataclass
   • Required fields: name, description (per agentskills.io spec)
   • GAIA extensions: permissions, requirements.hardware, security_tier (optional, layered on top)
   • Round-trip: parse then serialize then parse = identical object
   • Validate against upstream agentskills.io fixtures

2. Skill discovery (src/gaia/skills/manager.py)

   • Scan ~/.gaia/skills/*/SKILL.md at startup
   • Progressive loading: read only frontmatter (name + description) into system prompt catalog (~100 tokens/skill)
   • Full body loaded on-demand when agent matches a skill to user input
   • Hot-reload on file change (reuse FileWatcher pattern from agent registry)

3. Runtime loading into agents

   • agent.load_skill("skill-name") API on base Agent class
   • Skill tools registered under <skill-name>/<tool-name> namespace (prevents collisions)
   • Skills with tools.py alongside SKILL.md: auto-import @tool-decorated functions
   • Skills without tools.py (instruction-only): inject Markdown body into agent context

4. CLI basics

   • gaia skill list -- show installed skills with name, description, version
   • gaia skill import <path|url> -- copy a SKILL.md (+ directory) into ~/.gaia/skills/
   • gaia skill create <name> -- scaffold a new skill directory with template SKILL.md

5. Cross-platform compatibility test

   • Import 5 skills from SkillsMP or OpenAI curated catalog and verify they parse + load without modification

Phase 2 -- Author + share (v0.22.0)

6. BuilderAgent skill scaffolding

   • Extend create_agent tool (or add create_skill tool) to scaffold skills, not just agents
   • Generated SKILL.md uses agentskills.io format with GAIA extensions

7. Skill auto-synthesis from memory (ties to Skill auto-synthesis: procedural memory layer extending PR #606 #887)

   • When the memory/procedural layer detects a repeating workflow, auto-extract it as a SKILL.md draft
   • User confirms then persisted to ~/.gaia/skills/

8. Export + publish

   • gaia skill export <name> --to <path> -- package skill directory for sharing
   • gaia skill publish <name> -- publish to a registry (format TBD, could target SkillsMP or GAIA Hub)

Phase 3 -- Marketplace + security (v0.24.0, per #647)

9. Agent UI skills panel (in Configuration Dashboard, Configuration dashboard: personality, skills, MCP servers, tool management #701)

   • Browse installed skills, enable/disable per-agent, view permissions
   • Install from registry with one click
   • Security tier badges (Verified / Community / Experimental)

10. Security tiers (per docs/plans/skill-format.mdx Section 5)

    • AMD Verified: code-signed, auto-approved
    • Community: publisher-signed, user approval for dangerous permissions
    • Experimental: sandboxed, requires --allow-experimental

11. OpenClaw migration (OpenClaw skill compatibility layer with dashboard integration #692)

    • gaia skill migrate converts OpenClaw SKILL.md to GAIA-compatible format

Design decisions

Decision	Choice	Rationale
Base format	agentskills.io v1.0.0	Industry standard, cross-platform, minimal -- do not invent
GAIA extensions	Layered optional fields	permissions, requirements.hardware, security_tier -- agents that do not understand them ignore them
Skill directory	~/.gaia/skills/	Consistent with ~/.gaia/agents/ pattern already shipped
Tool namespacing	<skill>/<tool>	Prevents collision when multiple skills define search or run
Instruction-only skills	Supported	Not all skills need Python -- prompt-only skills (like coding guidelines) are valid
tools.py co-location	Supported	Skills that need executable tools place @tool functions alongside SKILL.md

Non-goals

• Agent format change -- agents stay as Python classes; skills are the composable units
• MCP replacement -- skills complement MCP; an MCP server can be a skill dependency
• Runtime sandboxing -- deferred to Phase 3 security tiers; Phase 1 trusts installed skills

Related issues

• Adopt agentskills.io open standard for skill format compatibility #888 -- Adopt agentskills.io open standard (this issue supersedes as the implementation umbrella)
• SKILL.md format specification with native Agent UI dashboard support #691 -- SKILL.md format spec (this covers the format + implementation)
• Skill marketplace: format spec, security tiers, and AMD Verified seeding #647 -- Skill marketplace (Phase 3 of this issue)
• OpenClaw skill compatibility layer with dashboard integration #692 -- OpenClaw compatibility (Phase 3)
• Starter skill pack: 10 agentskills.io skills demonstrating the platform #893 -- Starter skill pack (depends on Phase 1)
• Skill auto-synthesis: procedural memory layer extending PR #606 #887 -- Skill auto-synthesis (Phase 2)
• Scope skills for gaia agents #285 -- Original skill scoping issue
• Configuration dashboard: personality, skills, MCP servers, tool management #701 -- Configuration dashboard (Phase 3 UI)
• Agent Manifest: declarative metadata system for agent capabilities and requirements #462 -- Agent manifest (consumes skills)

Test plan

• Round-trip parser: parse then write then parse produces identical Skill object
• Import 5 agentskills.io-format skills from external sources -- parse without errors
• agent.load_skill("web-search") registers tools under web-search/ namespace
• Progressive loading: startup with 50 skills adds less than 5K tokens to system prompt
• gaia skill create my-skill scaffolds valid SKILL.md with agentskills.io frontmatter
• Hot-reload: modify SKILL.md on disk then agent picks up changes without restart
• Instruction-only skill (no tools.py) injects body into agent context

[github-actions]

Thanks for the detailed scoping — this is a strong umbrella. A few notes from poking around the repo to flag things worth pinning down before Phase 1 kicks off.

Foundations that already exist — confirmed and well-positioned for this:

• Format spec already drafted at docs/plans/skill-format.mdx (lines 46–96 cover the full schema). The agentskills.io alignment in this issue is a useful reframing of that draft as the base with GAIA fields as optional extensions.
• KNOWN_TOOLS mixin map at src/gaia/agents/registry.py is the natural sibling for skills — same registry pattern, different unit of composition.
• Hot-reload via AgentRegistry.register_from_dir() + FileWatcher (in src/gaia/utils/) gives you the discovery/reload primitives for free; reusing them keeps the patterns symmetric.
• No src/gaia/skills/ directory yet — Phase 1 is genuinely greenfield.

Phase 1 design questions worth resolving up-front:

🟡 Tool namespacing collision with KNOWN_TOOLS. The proposal uses <skill>/<tool> namespacing, but KNOWN_TOOLS keys are bare strings (rag, file_io, shell). If a skill declares name: shell, what wins? Suggest documenting precedence (built-in mixin → installed skill → error on collision) in the parser spec.

🟡 Frontmatter divergence from docs/plans/skill-format.mdx. The current spec marks permissions, version, author, tools, security_tier as required. agentskills.io v1.0.0 only requires name + description. Phase 1 should pick one source of truth — most cleanly, update the plan doc to mark all GAIA-specific fields optional (matching this issue's "layered" framing), so external skills parse without errors out of the box.

🟡 tools.py auto-import safety. Auto-importing @tool-decorated functions from arbitrary ~/.gaia/skills/*/tools.py is effectively arbitrary code execution at agent startup. Even before Phase 3 sandboxing, Phase 1 should at least: (a) require explicit user opt-in on first import (gaia skill import confirms), and (b) log every Python module loaded from a skill to a per-user audit log. The "Phase 1 trusts installed skills" non-goal is reasonable, but the trust boundary needs to be the import command, not silent disk scanning.

🟢 Progressive loading token budget. The "<5K tokens for 50 skills" test plan target implies ~100 tokens/skill for frontmatter — tight but feasible. Worth empirically measuring this on a representative description set early; if descriptions trend longer, the catalog format may need to summarize rather than concatenate verbatim.

🟢 Cross-platform fixture source. The "5 skills from SkillsMP / OpenAI catalog" compatibility test should pin specific commits/SHAs in the test, otherwise the suite breaks when upstream skills change. Vendoring a small fixture set under tests/fixtures/skills/ is probably worth it.

Suggested sequencing inside Phase 1: parser → fixture-based round-trip tests → SkillManager discovery (read-only, no execution) → gaia skill list/import/create CLI → agent.load_skill() runtime wiring → cross-platform compat test. That ordering means each step has a testable boundary before the next layer goes in, and instruction-only skills (no tools.py) become the Phase 1 default with executable skills as a follow-on within Phase 1 once the audit-log story is clear.

cc @kovtcharov-amd for the Phase 1 frontmatter-required-vs-optional decision and the auto-import trust-boundary call — those are the two that lock in API surface across the rest of the phases.