agentskills/agentskills — Summary

agentskills.io is the official open standard specification repository for the Agent Skills format — a cross-platform, cross-vendor standard for giving AI agents portable, loadable capability packages. Originally developed by Anthropic and released as an open standard, the repo now functions as the specification governance hub with documentation at agentskills.io.

Problem it solves: AI agents from different vendors (Claude Code, Gemini CLI, Codex, etc.) have incompatible capability extension formats; Agent Skills defines a single portable format (a folder with a SKILL.md file) that works across all compliant agents via progressive disclosure (discovery → activation → execution).

Distinctive trait: The only framework in the corpus that is a standard specification rather than a framework implementation — its value is defining the format that every other skill repository (including anthropics/skills, google/agents-cli, MicrosoftDocs/mcp) implements. It ships a SessionStart hook for the reference implementation (agentskills/agentskills) plus skills-ref content as a Python library for development tooling.

Target audience: AI tool developers who want to implement skills support in their agent; skill authors who want to publish portable skills; enterprises building cross-platform AI workflows.

Scope: 19,405 GitHub stars, Apache-2.0 (code) + CC-BY-4.0 (docs), 30 contributors, 1,190 forks, active since early 2025.

Differs from seeds: Unlike superpowers (Archetype 1 — behavioral enforcement framework for Claude Code), agentskills.io is the open standard that superpowers and other skill packs implement. It is above the implementation layer — it defines what a skill is, not how to use skills to enforce behaviors. Closest to how the W3C or OpenAPI Spec relates to individual implementations.

agentskills/agentskills — Overview

Origin

The Agent Skills format was originally developed by Anthropic and shipped as the anthropics/skills repo. It was then extracted as an open standard and placed under the agentskills GitHub organization. The spec repo (this repo) hosts the specification, docs, and governance; anthropics/skills remains the reference gallery.

Philosophy

"A standardized way to give AI agents new capabilities and expertise." "Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand."

Three core tenets:

1. Portability: A skill built for Claude Code works in Gemini CLI, Codex, or any compliant agent
2. Progressive disclosure: Agents load skill descriptions first (light), full instructions only when matched (heavy) — minimizing idle context cost
3. Procedural knowledge packaging: Skills encode how to do something, not just what to do — they are repeatable, auditable procedures

The Three Stages of Skill Loading

1. DISCOVERY   → agent loads name + description only (low context cost)
2. ACTIVATION  → task matches skill description → full SKILL.md loaded
3. EXECUTION   → agent follows instructions, runs bundled scripts/references

Open Development

"The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products."

The repo accepts external contributions via CONTRIBUTING.md. A Discord server (discord.gg/MKPE9g8aUy) serves as the community hub.

Adoption

The Client Showcase at agentskills.io/clients lists all compliant agent products. By 2026-05-26, adopters include Claude Code, Gemini CLI, Codex, Microsoft Learn MCP, and others.

agentskills/agentskills — Architecture

Distribution

• Type: methodology-doc + reference specification
• Install: No install — spec consumed by reading docs at agentskills.io
• Skills tooling (skills-ref/): Python package with pyproject.toml, installable via uv
• License: Apache-2.0 (code), CC-BY-4.0 (docs)

Repository Structure

agentskills/agentskills/
├── .claude/
│   ├── hooks/
│   │   └── session-start.sh    # SessionStart hook for internal dev use
│   └── settings.json           # Registers SessionStart hook
├── skills-ref/                  # Python reference implementation library
│   ├── CLAUDE.md               # Development guidance
│   ├── src/                    # Python source
│   ├── tests/                  # Test suite
│   ├── pyproject.toml          # Package config
│   └── uv.lock
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── package.json               # Mintlify docs dev script

Skill Format Specification

The canonical skill format is:

my-skill/
├── SKILL.md          # REQUIRED: metadata (YAML front-matter) + instructions
├── scripts/          # OPTIONAL: executable code
├── references/       # OPTIONAL: documentation files
├── assets/           # OPTIONAL: templates, resources
└── ...               # Any additional files

SKILL.md Required Fields

---
name: my-skill-name           # lowercase, hyphens for spaces
description: "..."            # When to activate this skill (critical for discovery)
---

SKILL.md Optional Fields

metadata:
  author: ...
  license: ...
  version: ...
  requires:
    bins: [...]
    install: "..."
context: fork                 # Used by MicrosoftDocs/mcp to indicate context mode
compatibility: "..."          # Fallback instructions

Target AI Tools

Any skills-compatible agent. See agentskills.io/clients for the full list.

Required Runtime

• uv (for skills-ref Python development)
• node / mint (for Mintlify documentation)
• No runtime for consuming/using skills — just a compatible agent

agentskills/agentskills — Components

This Repo's Own Components

The repo ships minimal tooling for its own development:

Hooks (1)

Purpose: Checks if Mintlify CLI is installed (used for docs development, not for skill delivery).

#!/usr/bin/env bash
# Session start hook for agentskills documentation project
echo '{"async":true,"asyncTimeout":15000}'

# Check if Mintlify CLI is installed
if ! command -v mint &> /dev/null; then
  echo "Mintlify CLI not installed. Install with: npm i -g mint"
fi

Python Library (skills-ref/)

A Python reference library for skill-related tooling. The repo contains:

• src/ — Python source code for skills reference implementation
• tests/ — pytest test suite
• pyproject.toml — uv-based package config with ruff for formatting/linting

Documentation Site

• package.json with "dev": "cd docs && npx mint dev" — Mintlify-powered documentation at agentskills.io

The Specification Itself

The spec lives at agentskills.io/specification and defines:

• Required SKILL.md structure (name + description mandatory fields)
• Progressive disclosure loading model (discovery → activation → execution)
• Optional metadata fields (author, license, version, requires.bins)
• Directory conventions (scripts/, references/, assets/)
• Cross-compatibility expectations

Skills Registry / Gallery

The repo does NOT itself ship skill examples — it delegates to anthropics/skills for reference examples and links to them from the README.

agentskills/agentskills — Uniqueness & Positioning

Differs from Seeds

This repo is categorically different from all 11 seed frameworks: it is a standard specification, not a framework implementation. The seeds (superpowers, spec-kit, claude-flow, BMAD, taskmaster-ai, etc.) are implementations — they make choices about how to use agents. agentskills.io defines the vocabulary those implementations use.

The closest analogy in tech: agentskills.io is to skill packs what the JSON Schema spec is to JSON validators — it defines correctness, not behavior.

Within the seeds, no analog exists. The closest pattern is how kiro defines its own IDE-native spec format — but kiro's format is proprietary and IDE-locked, while agentskills.io is explicitly cross-platform.

Distinctive Properties

1. Standard vs implementation: Only repo in the corpus whose primary value is defining the format, not implementing functionality
2. Progressive disclosure architecture: The three-stage load model (discovery → activation → execution) is a novel context-management contribution to the agent skill ecosystem
3. Anthropic origin → open governance: The format was released by Anthropic but is now community-governed, giving it vendor-neutral credibility
4. Multi-vendor adoption: Claude Code, Gemini CLI, Codex, and Microsoft Learn MCP all implement the standard — verified cross-vendor portability
5. Activation trigger as prompt engineering: The description field in SKILL.md IS a prompt — it's the retrieval query that determines when skills activate

Observable Failure Modes

• Spec fragmentation: Downstream implementations (Google agents-cli adds metadata.requires.bins, MicrosoftDocs adds context: fork) extend the spec in ways that reduce cross-tool portability
• Description quality as activation bottleneck: Poorly written descriptions cause wrong-skill activation or no activation; the spec provides no guidance on description quality
• No verification: No conformance test suite to verify agent implementations comply

Cross-References in Batch

• anthropics/skills implements this spec (reference gallery)
• google/agents-cli extends and implements this spec (adds metadata.requires + multi-skill packaging)
• MicrosoftDocs/mcp implements this spec (adds context: fork extension)
• ccplugins-awesome plugins may implement this spec (via .claude-plugin format)