holocron/plugins/kyberforge/docs/research/docs/agentskillsio/overview.md

topic, source_keys

topic	source_keys
agentskills-overview	agentskills-home agentskills-spec agentskills-quickstart agentskills-best-practices

What Agent Skills is

Agent Skills is a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. A skill is a folder containing a SKILL.md file — metadata plus instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, reference materials, templates, and other resources.

The format was originally developed by Anthropic, released as an open standard, and has been adopted by a large and growing number of agent products: Claude Code, GitHub Copilot, OpenAI Codex, Google Gemini CLI, VS Code, Cursor, JetBrains Junie, Block Goose, OpenHands, Roo Code, Spring AI, Databricks Genie, Snowflake Cortex, and many others — 35+ confirmed implementations as of June 2026.

Why Agent Skills exist

Agents are increasingly capable but often lack the context to do real work reliably. Skills solve this by packaging procedural knowledge and project-specific context into portable, version-controlled folders that agents load on demand:

• Domain expertise: capture specialized knowledge — legal review processes, data pipelines, presentation formats — as reusable instructions and resources.
• Repeatable workflows: turn multi-step tasks into consistent, auditable procedures.
• Cross-product reuse: build a skill once and use it across any skills-compatible agent.

Progressive disclosure

Agents load skills in three stages:

1. Discovery — at startup, agents load only the name and description of each available skill (~100 tokens per skill). Just enough to know when one might be relevant.
2. Activation — when a task matches a skill's description, the agent reads the full SKILL.md body into context (<5000 tokens recommended).
3. Execution — the agent follows the instructions, optionally executing bundled scripts or loading referenced files on demand.

Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint.

Scope: no concept of "agent"

The spec is runtime-agnostic and defines only the skill format — it does not define "agent," "subagent," or any delegation/orchestration concept, and neither the specification nor the best-practices guide contains criteria for choosing a skill over a separate agent process. Skill-vs-agent selection is a decision made by whichever runtime consumes the skill (see the Claude Code and GitHub Copilot decision-criteria docs for their respective answers), not something the Agent Skills format itself addresses.

Canonical directory

The canonical location for skills is .agents/skills/ at the project root. Tool-specific locations (.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex) are thin adapters that map to this canonical path. Putting skills at .agents/skills/ maximizes cross-tool portability.

File structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

The SKILL.md file must contain YAML frontmatter followed by Markdown content. There are no format restrictions on the body.