AI agent skills: a builder’s pattern library for reusable capabilities

On 18 September 2026, Microsoft defined Agent Skills as portable packages of instructions, scripts and resources that agents discover and load on demand. By 22 September 2026, Anthropic, OpenAI and Cloudflare had each published skills documentation or repositories with closely related folder-based patterns, but the sources here do not show a single formally shared contract across all four.

What an AI agent skill is in plain language?

In plain language, a skill is a folder that teaches an agent how to do one job. Microsoft says Agent Skills are portable packages of instructions, scripts and resources, OpenAI says a skill is a directory with a SKILL.md file plus optional scripts and references, and Anthropic says skills are folders of instructions, scripts and resources that Claude loads dynamically.

The required piece is the same in the three clearest specifications here: SKILL.md. Microsoft’s format requires YAML frontmatter and markdown content, while OpenAI and Anthropic both say the file must include at least name and description. The point is simple. The host shows the agent a short description first, then loads the full instructions only when the task matches.

Anthropic’s basic example is the shortest useful template in the sources, and it shows what most builders need to start:

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

That simplicity matters. A skill is not a full agent framework, and it is not a model. It is a reusable task package. OpenAI calls skills “the authoring format for reusable workflows”, and Microsoft frames them as a way to package domain expertise, extend capabilities and make multi-step tasks repeatable.

Why skills spread: they cut prompt bloat by loading details late?

The strongest shared idea is not the file name. It is progressive loading. Claude-Mem’s progressive disclosure write-up puts the problem in numbers: a traditional upfront load can dump 35,000 tokens into a session, of which about 2,000 tokens, or 6%, are relevant, while its indexed workflow uses about 920 tokens for the same case. That document is not a skills spec, but it gives the clearest explanation for why skills systems keep only a lightweight index in the initial prompt.

Microsoft formalises that approach as four stages. First the host advertises skills at roughly 100 tokens per skill. Then it loads the full SKILL.md body, with less than 5,000 tokens recommended, only when a task matches. Then it reads resources if needed. Then it runs scripts if needed. Microsoft also notes that load_skill is always advertised, while read_skill_resource and run_skill_script appear only when at least one installed skill needs them.

OpenAI applies the same pressure with a hard budget. In Codex, the initial skill list uses at most 2% of the model’s context window, or 8,000 characters when the window is unknown. If many skills are installed, Codex shortens descriptions first, and for larger sets it may omit some skills from the initial list and show a warning. That is a concrete implementation detail, not a design slogan. It tells builders to write descriptions that still work when truncated.

Cloudflare describes the operational result in more product-focused language: its skills are contextual and auto-loaded based on conversation triggers. Anthropic uses the same idea when it says Claude loads skills dynamically to improve performance on specialised tasks. Different vendors describe the mechanism differently, but the retrieval pattern is recognisably the same.

Microsoft, Anthropic and OpenAI describe very similar skill folders, but not one proven shared contract

The draft overstated this point. The sources support strong family resemblance, not a formally shared package contract across Claude, OpenAI, Microsoft and Cloudflare. Microsoft, Anthropic and OpenAI all describe a folder centred on SKILL.md, with optional scripts and resource files. That is enough to say builders are seeing the same pattern in multiple ecosystems.

It is not enough to say all vendors now share one contract. OpenAI adds optional agents/openai.yaml metadata for UI, policy and dependencies. Microsoft requires YAML frontmatter, documents fields such as license, compatibility and experimental allowed-tools, and defines provider and source abstractions around the package. Anthropic shows a basic format with only name and description required. Cloudflare’s repository clearly distributes skills, but its page is an install and catalogue document rather than a standalone format specification.

The safer claim is this: there is now enough overlap for a builder to recognise the pattern across hosts. Write one focused folder. Put the job description in SKILL.md. Keep optional scripts and references separate. Expect the host to advertise a short summary first, then load more detail when needed. The sources support that. They do not, on their own, prove full interchangeability.

Sources: Microsoft Agent Skills, Anthropic skills, OpenAI Codex skills, Cloudflare Skills, wuyoscar/jev-skill and kerpopule/hermes-jev-skills.

How skills differ from tools, plugins and MCP servers?

The terminology overlaps, so builders need a clean separation. In the sources here, a skill is the reusable workflow package. A tool is an operation the host exposes so the agent can work with a skill. Microsoft’s page is explicit: the provider advertises available skills in the system prompt and registers the tools the agent uses to load_skill, read_skill_resource and run_skill_script. The skill is the package. The tool is how the agent opens or executes parts of that package.

OpenAI draws a different but equally useful line. Skills are the authoring format for reusable workflows. Plugins are the distribution format when you want other people to install reusable skills, bundles of skills, or skills shipped alongside connectors. That matters because “plugin” in OpenAI’s stack is not a synonym for “skill”. A builder can keep a skill as a local folder for repo-scoped work, then package it as a plugin for wider distribution.

Cloudflare shows why that distinction matters in practice. Its native plugin installs both Cloudflare guidance and the Cloudflare MCP server where the host supports native plugins, while agents that only support the Agent Skills standard can install the skills separately. In other words, the skill carries domain guidance, and the plugin can add a live connector path as well.

MCP servers are different again. Cloudflare’s repository says its plugin includes one remote MCP server named cloudflare, which gives access to the Cloudflare API and current developer documentation through Code Mode MCP. OpenAI says plugins can optionally bundle registered MCP server connections or bundled MCP configuration, and its optional agents/openai.yaml dependency example declares an MCP tool with a URL. Microsoft uses MCP differently again: skills can be discovered from MCP servers via UseMcpSkills in C# or MCPSkillsSource in Python. Across all three, the server is the connector layer, not the skill itself.

Anthropic’s repository reinforces the same split from the opposite direction. Anthropic says skills are self-contained folders, and Claude Code exposes plugin marketplace commands to install sets of those skills. There too, the plugin is the delivery channel, not the workflow format.

Microsoft’s provider model is the clearest picture of how builders compose skills

If you want the most explicit architecture document in the public record, Microsoft has it. Its Agent Skills page splits the system into providers, sources and a builder. The provider exposes skills to the agent and registers the tools. Sources supply skills from files, inline code, classes or MCP servers. The builder then assembles multiple sources and applies aggregation, deduplication, caching and optional filtering.

The Go examples tree shows the same ideas as runnable examples rather than just documentation. By 22 September 2026, the public examples directory included step01_file_based_skills, step02_code_defined_skills, step03_mixed_skills and step04_skills_auto_approval. That progression is useful because it maps the actual decisions a team makes: start with a folder, add code-defined behaviour when needed, mix sources when the estate grows, then decide what the host should auto-approve.

Microsoft also makes the approval boundary explicit. All three skill tools require approval by default, and the harness middleware does not auto-approve any tool unless you add rules. The example rule auto-approves the read-only operations but not script execution. That is one of the more practical details in the sources, because it treats skills as operational code packages rather than pure prompt snippets.

OpenAI and Cloudflare show how skills become installable products

OpenAI’s documentation is strongest on authoring and distribution paths. It says standalone skills are available in the ChatGPT desktop app, Codex CLI and IDE extension, while skills bundled in plugins are also available across Chat and Work in ChatGPT on the web, desktop and mobile. That split is a product decision, but it has engineering consequences. Builders can iterate locally with a folder and move to plugin packaging when they need distribution, bundled connectors or presentation assets.

OpenAI is also specific about invocation. Skills can be called explicitly, such as @ selection in ChatGPT or $ mention in Codex, or implicitly when the task matches the skill description. That is why the documentation tells authors to front-load key use cases and trigger words in the description. The description is not marketing copy. It is the retrieval key.

Cloudflare’s repository shows the same packaging pattern deployed as a vendor library. Its catalogue lists 13 skills, including agents-sdk, durable-objects, wrangler, web-perf, cloudflare-one and cloudflare-one-migrations. The repo then offers multiple install routes: marketplace commands for Codex and Claude Code, source installation for VS Code or GitHub Copilot, a marketplace or remote rule path for Cursor, and npx skills add for the npx skills CLI.

The interesting part is the connector layer. Cloudflare says the native plugin installs both guidance and the Cloudflare MCP server, while skills-only hosts can install the skills separately. That is a cleaner real-world example than many abstract explainers. A skill can teach the workflow. A plugin can distribute the workflow and the live API access together.

Anthropic’s repository shows that a skill can be simple, but shipped skills can be much richer

Anthropic’s repository makes two points at once. First, a basic skill can be minimal: a folder, a SKILL.md file, two required frontmatter fields and instructions below. Second, production skills are often more involved. Anthropic says the repository includes source-available document creation and editing skills in skills/docx, skills/pdf, skills/pptx and skills/xlsx, and that those skills power Claude’s document capabilities under the hood.

That matters because many descriptions of skills stop at “a markdown file”. The sources here support a broader view. A skill can be an instruction-only folder, but it can also bundle scripts, templates and reference documents. Anthropic says its examples range from creative applications to technical tasks and enterprise workflows. Microsoft explicitly includes scripts, references and assets in the canonical structure. OpenAI adds optional dependencies and UI metadata. The common lesson is that SKILL.md is the entry point, not the whole design space.

Anthropic also says these example skills are already available to paid plans in Claude.ai and can be used through the Claude API. That is useful context for builders evaluating whether skills are still a lab pattern. In Anthropic’s case, they are already part of a production product surface.

Community libraries show the pattern expanding from product guidance to control loops

The community evidence in the public record is useful because it shows what independent builders do once the file format exists. wuyoscar/jev-skill presents itself as demos, workflows and skills for coding agents, and the repository front page says it collects 57 projects and resources, 5 skills, 108 scenarios and 14 recorded input/output pairs. Its five skills split the work into reusable jobs: jev for designing questions and batch calls, jev-triage for sorting and labelling records, jev-documents for finding and checking source evidence, jev-eval for rubric-based checks, and jev-act for choosing the next legal action.

That division is revealing. These are not end-user features like “write a blog post”. They are control functions inside a larger agent loop. The install prompt also targets multiple hosts at once by telling the agent to install Jev Skills for Codex, Claude Code or OpenCode. That is a practical sign that builders already expect one skill collection to travel across more than one environment, even if the install path still differs by host.

kerpopule/hermes-jev-skills pushes the same idea harder. The repo says nine skills ship as plain SKILL.md files, “so they are not Hermes-only”, and that the same folder works in Claude Code, Codex, or anything that reads a skill file. The project then puts measurements on a set of small but expensive agent decisions: model routing at about 0.4 seconds per turn, skill selection across 377 skills in about 2.8 seconds, choosing turns from a transcript of 71 turns in 0.95 seconds, mailbox sorting at about 0.44 seconds p50 per message and $0.00002 each, and browser use at about 0.4 seconds per step.

Those numbers do not prove general performance, but they do show how builders are using skills. The skill format is becoming a packaging layer for narrow, repeatable decisions: routing, retrieval selection, inbox triage and next-action choice. That is a richer and more professional use case than the usual “prompt template with a nicer name”.

Portability is improving, but install paths still depend on the host

No source here supports the idea that skills are now frictionless across hosts. The package pattern is portable. The install and discovery rules are not. OpenAI documents repository, user, admin and system locations for Codex, scanning .agents/skills from the current working directory up to the repository root, then $HOME/.agents/skills, /etc/codex/skills and bundled system skills. It also says Codex supports symlinked skill folders and can disable a local skill through ~/.codex/config.toml.

Cloudflare documents different directories for Claude Code, Cursor, OpenCode, OpenAI Codex and Pi when a user clones or copies the repo manually. Anthropic documents plugin marketplace commands for Claude Code, plus direct plugin installation for document skills or example skills. Hermes Jev Skills says its installer finds Hermes, Claude Code and Codex on the machine and installs for each one it finds.

That is still useful portability. It means one folder format can often survive a move across hosts, even if discovery paths, approval policy and distribution wrappers differ. It is not yet the same thing as one fully interchangeable package contract.

What we could not verify?

We could not verify the claim that Claude, OpenAI, Microsoft and Cloudflare now share one formal package contract. OpenAI says skills build on the open agent skills standard, Microsoft says skills follow an open specification, and Anthropic’s repository says it contains Anthropic’s implementation of skills for Claude, but the sources here do not identify one canonical standards-body release or conformance test that proves cross-vendor interoperability.

We also could not verify licensing detail beyond what the repositories state. Anthropic says many skills in its repo are open source under Apache 2.0, while the document skills are source-available rather than open source, but the exact terms for those subfolders are not set out in the excerpt provided here.

Cloudflare’s page says the plugin bundles the main remote MCP server, but it does not describe runtime limits, authentication details or versioning policy in the source excerpt here. The earlier draft also cited Oldcircle/geo-sleuth for installer and benchmark claims, and we could not verify those claims from the material provided for this revision. The open question for builders is therefore straightforward: when vendors say “open specification” or “open agent skills standard”, will they publish a conformance target that makes one SKILL.md package genuinely portable across hosts?

Sources

• https://docs.claude-mem.ai/progressive-disclosure
• https://github.com/cloudflare/skills
• https://github.com/microsoft/agent-framework-go/tree/main/examples/02-agents/skills
• https://github.com/MicrosoftDocs/azure-ai-docs/blob/main/agent-framework/agents/skills.md
• https://github.com/anthropics/skills
• https://developers.openai.com/codex/skills
• https://github.com/wuyoscar/jev-skill
• https://github.com/kerpopule/hermes-jev-skills
• https://github.com/Oldcircle/geo-sleuth