85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Tool explainer

What are Agent Skills (SKILL.md)?

Agent Skills are an open format in which a folder holding a SKILL.md file, plus optional scripts, references and assets, teaches an AI agent a specific task and loads into context only when that task comes up.

Checked

A skill is the unit of reusable know-how for an agent: how to fill a particular form, run a release, review a contract against a house checklist, or build a slide deck in a company template. Instead of putting every procedure in one long system prompt, each lives in its own folder and the agent reads it only when a task matches.

Anthropic introduced Skills on 16 October 2025, published the format as an open standard on 18 December 2025, and donated it to the Linux Foundation's Agentic AI Foundation on 22 October 2026. OpenAI's Codex and ChatGPT, Microsoft Agent Framework, LangChain's Deep Agents and the Claude Agent SDK all load skills in the same format.

How it works

Agents load skills by progressive disclosure, in three stages. At discovery, only each skill's name and description sit in context, about 100 tokens per skill. At activation, when a task matches the description, the agent reads the full SKILL.md body; the spec recommends under 5,000 tokens and under 500 lines. At execution, the agent follows the instructions and opens bundled scripts, references or assets only as needed.

  • Required frontmatter

    name: 1 to 64 lowercase letters, digits and single hyphens, matching the folder name. description: 1 to 1,024 characters saying what the skill does and when to use it.

  • Optional frontmatter

    license, compatibility (up to 500 characters on environment needs), a free-form metadata map, and allowed-tools, which is experimental and varies by agent.

  • Optional folders

    scripts/ for code the agent can run, references/ for documentation it reads on demand, and assets/ for templates, images and data files.

  • Validation

    The skills-ref reference library checks frontmatter and naming with skills-ref validate.

Status and adoption, checked 1 November 2026

  • Governance

    An Agentic AI Foundation project since 22 October 2026, alongside MCP, AGENTS.md and A2A. The spec repo, agentskills/agentskills, is Apache-2.0 with 26,839 GitHub stars; Anthropic's example repo, anthropics/skills, has 186,034.

  • OpenAI Codex and ChatGPT

    Skills build on the agentskills.io standard. Codex loads them from .agents/skills folders in the repo and home directory, from /etc/codex/skills and from bundled system skills, and invokes them explicitly by name or implicitly when a task matches the description.

  • Claude Agent SDK and Claude Code

    Skills load from the project's .claude/ folder and the user's ~/.claude/.

  • Microsoft Agent Framework

    Skills, as reusable packages of instructions, scripts and resources, were in preview at the 1.0 release in April 2026.

When to use a skill, and when not to

  • Use a skill for

    A procedure the agent needs sometimes, not always: a report format, a deployment checklist, a domain rulebook, or a script that does a step deterministically.

  • Use MCP instead for

    Access to a live system such as a CRM, database or ticketing tool. MCP supplies connectivity; skills supply expertise, and many skills tell the agent how to use an MCP server well.

  • Use AGENTS.md or the system prompt for

    Rules that apply to every task, such as tone, safety limits or repository conventions. Those should not depend on a description match to load.

  • One agent, many skills

    Anthropic's January 2026 guidance is to build one general agent and specialise it with a skills library, rather than a separate agent for each domain.

Gotchas from production

  • The description is the router

    A vague description means the skill never loads, or loads for the wrong task. OpenAI's guidance is to write descriptions as routing logic and include cases where the skill should not trigger, then test that it fires only when it should.

  • Skills are code

    Scripts run with the agent's permissions. A third-party skill deserves the review a new dependency gets, and a sandbox limits the damage if it misbehaves.

  • allowed-tools is not portable

    The field is experimental and support varies between agents, so pre-approved tools in one product may still prompt, or be ignored, in another.

  • Keep references shallow

    The spec advises file references one level deep from SKILL.md. Deep chains of files cost context and are easy for the agent to miss.

  • Skills age with the model

    As models get stronger, rigid step-by-step recipes can turn into scaffolding the model no longer needs, so a skill library needs the same eval-driven review as prompts.

Agent Skills compared with MCP and always-on instructions

Agent Skills compared with MCP and always-on instructions
Agent SkillsMCP serverAGENTS.md or system prompt
What it carriesInstructions, scripts and resources for a taskTools and data from a live systemRules for every task
When it enters contextName and description always; body on matchTool definitions when the server connects, unless tool search defers themAlways
FormatFolder with SKILL.md (YAML frontmatter plus Markdown)Protocol over stdio or HTTPMarkdown file or prompt text
Where code runsIn the agent's own sandboxIn the MCP server processNo code
GovernanceAgentic AI Foundation (since 22 Oct 2026)Agentic AI Foundation (founding project, Dec 2025)AGENTS.md: Agentic AI Foundation
Typical failureNever triggers, or triggers on the wrong taskToo many tools crowd the contextGrows until rules contradict each other

Common questions

What is the difference between Agent Skills and MCP?

MCP connects an agent to tools and data in other systems. A skill teaches the agent how to do a task, with instructions and scripts loaded only when needed. They are complementary, and a skill often explains how to use an MCP server well.

Who created Agent Skills?

Anthropic introduced Skills in October 2025, opened the format as a standard in December 2025, and donated it to the Linux Foundation's Agentic AI Foundation on 22 October 2026.

Do Agent Skills work with OpenAI Codex?

Yes. OpenAI's docs state that skills for ChatGPT and Codex build on the open agentskills.io standard, with skills stored in .agents/skills folders.

How long should a SKILL.md file be?

The specification recommends keeping the body under 500 lines and under about 5,000 tokens, and moving detailed material into separate reference files the agent reads on demand.

Running agents that have to hold up?

Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.