IonBin
All pages
Search
Concept

Agent skills (SKILL.md)

An agent skill packages instructions and optional scripts or references in a folder with SKILL.md. Claude and Codex support the open format, but available tools, installation locations and vendor extensions differ. Test a shared skill in each intended client.

Verified Oct 18, 2026 Review by Apr 16, 2027 3 sources

What it is

A skill is a written procedure packaged for an AI agent. Think of it as an SOP the agent can open on its own: what the task is, when to use it, the steps, and any templates or scripts it needs.

How it works

  1. A folder per skill. It holds a SKILL.md file with YAML front matter (at minimum a name and a description) followed by plain Markdown instructions. The open specification limits name to 64 characters and description to 1,024 (checked 2026-10-18).
  2. Optional extras. Scripts, reference documents and assets sit beside it.
  3. Loaded on demand. The agent sees the short description first and reads the full instructions only when a task calls for them, which keeps the context window light.
  4. Kept in Git. Store skills in a GitHub repo so changes are reviewed, versioned and shared like code.

Benefits

  • Version reusable procedures. Updating the source makes a new version available; installed copies, cached sessions and pinned plugin versions may still need an update or restart.
  • Portable. The open specification is supported by Claude and Codex, so you are not locked into one vendor’s custom-assistant format.
  • A better review question (IonBin’s view). “Which of our repeatable tasks are written down as skills?” is a practical way to audit AI adoption on a team.

Limits and risks

  • Scripts run with the agent’s permissions. Treat third-party skills like any software you install: read them first.
  • Portability needs testing. Standard front matter helps, but scripts, available tools, credentials and vendor extensions can still differ between clients.
  • Instructions drift. A skill nobody owns goes stale. Give each one an owner and a review date.

Checked specs

Snapshot from official sources on Oct 18, 2026.

Required SKILL.md fields (checked 2026-10-18)name (1-64 characters, lowercase letters, numbers and hyphens) and description (1-1024 characters) [1]
LoadingClaude uses progressive disclosure: skill metadata first, full instructions only when relevant [2]
CodexBuilds on the open agent skills standard; the initial skills list uses a default budget of up to 2% of the context window, or 8,000 characters when window size is unknown; configuration can change this [3]

Best-fit stacks

Stack 08

Dev, web & IT

Design, code, host and ship sites and internal tools, with an AI coding agent doing most of the typing.

Agent compatibility

Tool in this entryHow agents connect
Claude Agent platform MCPAPI/CLIFile import
OpenAI Codex Agent platform API/CLIFile import
GitHub MCPAPI/CLIFile import

Levels come from each tool's recorded, sourced compatibility. How the levels work.

Sources

  1. Agent Skills specification · Agent Skillsofficial accessed Oct 18, 2026
  2. Agent Skills overview · Anthropicofficial accessed Oct 18, 2026
  3. Skills in Codex · OpenAIofficial accessed Oct 18, 2026

Practitioner views are restated in our words and labeled as views, not measured results. Product facts come from official sources dated above.

Suggest an edit

IonBin's wiki isn't user-edited. Corrections go to our Directory Curator, who checks them against primary sources before anything changes. Spot something wrong or out of date on “Agent skills (SKILL.md)”? Email us with a link to a primary source.

Suggest an edit by email or write to contact@ionbin.com