How to Create Agent Skills for Your Product (2026)

The practical guide to writing, testing and distributing Agent Skills, so AI agents choose your product and use it the way you intended

On October 22, 2026, Anthropic handed the Agent Skills standard to the Linux Foundation's Agentic AI Foundation, with 1 million skills published and nearly 280 million installs behind it. More than 70 agent platforms had integrated the format by then, including ChatGPT, Cursor, GitHub Copilot and VS Code - Anthropic. A skill is a folder with one SKILL.md file that teaches an agent a specific job. It is now the closest thing the agent world has to a package format, and for the first time no single AI lab owns it.

The problem for anyone who runs a product: an agent, not a developer, increasingly decides how your product gets used. When someone asks a coding agent to "add billing" or "set up a database", the agent picks the provider, the API version and the integration pattern from training data that stopped months ago. A skill is the one artifact you write that lands in the agent's context at the moment it makes that decision. It is also easy to get wrong: in one public eval by Vercel, an agent never opened the skill in 56% of cases - Vercel. On the largest public registry, nearly half of all skills were installed exactly once, while 375 skills collected 62% of all installs - Vercel, State of agent skills.

This guide covers what a skill is and what the donation changes, why a skill is now a distribution channel rather than documentation, and how it relates to an MCP server, AGENTS.md and llms.txt. Then it walks through the actual work: scoping the skill, writing the SKILL.md, writing the description that decides whether the skill is ever read, testing triggering and output quality, making one skill work in every agent, and publishing it everywhere agents look, from your own docs domain to the Anthropic and OpenAI plugin directories. It closes with versioning, security, how to read install numbers honestly, where skills fail, and what comes next.

Contents

1. What Changed on October 22, and Why It Matters
2. Why a Skill Is the Highest-Leverage File Your Product Can Ship
3. Skill, MCP Server, AGENTS.md or llms.txt: Which Layer Does What
4. Anatomy of a Skill: The Specification in Plain Terms
5. How to Create an Agent Skill, Step by Step
6. The Description: One Paragraph That Decides Everything
7. Testing a Skill: Trigger Evals and Output Evals
8. One Skill, Every Agent: Portability Rules
9. Distribution: Getting Your Skill Into Agents
10. Reading the Install Numbers Honestly
11. Keeping Skills Current and Safe
12. Where Skills Fail
13. What Comes Next for Skills
14. Conclusion: A Decision Framework

Where to Ship Your Skill: Every Channel, Scored

Writing the skill is half the job. The other half is getting it into the agents your users already run, and the channels differ far more than they first appear. Some put your skill in front of millions of people but freeze the copy they installed. Others update every user the moment you merge, but only inside one vendor's apps. Some check your files before anyone can install them, and some let anyone publish a lookalike under your brand name.

The table below scores the seven channels a product team can use today on the same five criteria, using only what each channel's own documentation states. The scores are judgments, and the evidence for each one is in its cell, so you can disagree with a weight and recompute the result. A product with real reach usually ships through three or four of these at once, which is the point of section 9.

How the criteria were chosen. Reach (30%) is weighted highest because a skill nobody installs teaches nobody. Stays current (25%) comes next because the entire reason to ship a skill is to replace stale knowledge, and a frozen copy goes stale too. Trust (20%) covers review and whether the channel proves the skill really comes from you, which matters because impersonation is the dominant attack pattern documented so far (section 11). Effort (15%) is scored so that 10 means easiest. Usage data (10%) matters because you cannot improve a skill you cannot observe, but it is the easiest gap to fill with your own instrumentation.

The ranking hides one fact worth stating plainly: the top three are complements, not alternatives. The domain index and the GitHub repo cost an afternoon and reach every agent that speaks the standard; the Anthropic directory adds review, automatic updates and the only per-skill usage numbers on the list. Section 9 walks through each channel with the exact commands and files.

1. What Changed on October 22, and Why It Matters

Agent Skills started as a Claude feature. Anthropic introduced skills in October 2025 while building Claude Code, because the agent handled general work well but lacked the procedural knowledge real business tasks need - Anthropic Engineering. Within weeks of that launch, according to Anthropic's donation announcement, developers had published thousands of skills and written loaders for Codex, Cursor and OpenCode. In December 2025 Anthropic published the format as an open standard with its own GitHub organization and domain, and Simon Willison wrote at the time that he would not be surprised to see it end up in the AAIF - Simon Willison.

On October 22 that prediction came true. Anthropic donated the Agent Skills name and logo, the GitHub organization and the agentskills.io domain to the Agentic AI Foundation (AAIF), the Linux Foundation body it co-founded with Block and OpenAI in 2025 and the same home it gave the Model Context Protocol. Engineers from Anthropic, Google, OpenAI and other companies now maintain the standard as individuals, with David Soria Parra and Mahesh Murag as Lead Maintainers, and nobody has to join the AAIF to use or contribute to it - Anthropic.

Three roadmap items matter to product teams:

• Versioned releases of the specification, so a skill can declare what it was written against
• A formal proposal process, so changes stop depending on one company's product calendar
• Security guidance for the people who write skills and the people who install them

Each of those closes a gap you would otherwise have to manage yourself. Versioned releases mean a client can tell you whether your skill is too new or too old for it, which today is guesswork. A proposal process means features such as executable permissions or signed bundles arrive through one public track rather than as incompatible vendor extensions. Security guidance means the review checklists at Anthropic, OpenAI and Cursor will likely converge on one standard, so a skill that passes one review is far more likely to pass the others. All three lower the cost of maintaining one skill for every agent.

Why this matters for your product. Before the donation, betting on skills meant betting on Anthropic's format, even though OpenAI, Google and Microsoft's tools had adopted it. After it, the format has the same governance as MCP, which became the default way agents connect to products. The adoption list on the standard's own site already includes ChatGPT and Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, JetBrains Junie, Snowflake Cortex Code, Databricks Genie Code and Spring AI, among dozens of others - Agent Skills. That breadth is what makes one skill worth writing carefully: it is read by every serious agent your customers use.

The growth curve explains the urgency. Vercel's skills.sh registry, launched in January 2026, reached one million skills in seven months; by Vercel's comparison, GitHub took 27 months to reach a million repositories and npm more than nine years to reach a million packages - Vercel. A crawl assembled by the SkillsBench researchers shows daily additions peaking at 33,692 new skills on April 7, 2026 - SkillsBench. Your category almost certainly already has skills that teach agents how to use your product, written by people who do not work for you.

How to apply this. Treat the skill as a public interface with the same discipline as your API: one owner, a version number, a changelog and a deprecation policy. The next section explains why that interface now carries more weight than most of your documentation.

2. Why a Skill Is the Highest-Leverage File Your Product Can Ship

Start from the structural question rather than the trend. When an agent implements something for a user, what decides which product it uses and how? Two inputs: the model's prior, learned from training data with a cutoff, and whatever sits in its context window at that moment. Your marketing site is not in that window. Your documentation usually is not either, unless the agent goes looking. Everything you shipped after the model's training cutoff is invisible unless something puts it in front of the agent.

That gap is not theoretical. Vercel built evals around Next.js 16 APIs such as 'use cache', connection() and forbidden() precisely because they were missing from model training data, and found that agents without that knowledge "generate incorrect code or fall back to older patterns" - Vercel. Security fixes follow the same pattern. On October 21, Node.js shipped fixes for a Brotli decoder out-of-bounds write (CVE-2026-111497) only on the 22.x, 24.x and 26.x lines - Node.js. A model trained before that date cannot know which versions are patched, which is why we published a separate Node2Shell patch guide. A vendor-maintained skill is the most direct channel a vendor controls for correcting an agent's defaults on the day the facts change.

The evidence that skills move outcomes is now unusually strong. SkillsBench, a benchmark of 87 tasks across eight domains, ran 18 model and harness configurations with and without curated skills. Curated skills raised the average pass rate from 33.9% to 50.5%, a gain of 16.6 percentage points, and the gain was positive for every configuration tested - SkillsBench. The more important finding is about who writes the skill.

When each agent first wrote its own skill packs with Anthropic's skill-creator and then used only those, results fell below the no-skill baseline on all three dedicated harnesses: minus 8.1 points on Claude Code, minus 11.3 on Codex and minus 11.5 on Gemini CLI. Curated skills on the same setups added 18.2 to 24.8 points. The authors traced the deficit to packs the solver never found, authoring work that displaced solving, and "confidently wrong pack content" - SkillsBench. The models tested were the paper's configurations (Opus 4.7, GPT-5.5 and Gemini 3.1 Pro), not the newest releases, but the mechanism does not depend on the model generation.

The first-principles reading is direct. Models cannot author the procedural knowledge they benefit from consuming, because the knowledge that matters (your gotchas, your current defaults, your deprecations) is exactly what is missing from their training. That makes the vendor the scarce supplier. If you do not write the skill for your product, the alternatives are an agent guessing, or a third party writing one from your public docs, which is the "comprehensive documentation" pattern that, as section 7 shows, adds almost nothing.

A second finding changes the economics for your users. In SkillsBench, smaller models with skills matched larger models without them: MiniMax M2.7 with skills scored 34.9%, above the no-skill baselines of stronger configurations such as GLM 5.1 at 32.7% - SkillsBench. Your customers run your product through whatever model is cheapest that week. Moonshot's Kimi K3.1 Pro launched last week at $2/$10 per million tokens, with a vendor-reported 65.7% on Terminal-Bench 4.0 against 66.4% for Claude Opus 5.5 - OrcaRouter. That is half the $4/$20 Anthropic charges for Claude Opus 5.5 - Anthropic pricing. A skill travels with the user across every model they pick, so it protects your integration quality regardless of which lab wins the week.

The distribution argument follows from the same structure. This month agents started transacting at scale: Walmart launched an Agent Gateway, an MCP server for approved shopping agents with per-agent profiles and spending limits - TechCrunch, and Anthropic's Claude Duet shipped with Stripe MCP and Stripe's agent wallet built in - Stripe. The same week OpenAI took ChatGPT ads to 89 countries and more than 100,000 advertisers - The Next Web. Ads buy a place in the conversation; a skill earns a place in the agent's working context, at the moment it chooses how to do the job. We covered the commerce side in our guide to selling to AI agents, and the discovery side in getting your product recommended by ChatGPT.

There is also a defensive reason. A study of 98,380 skills from two registries confirmed 157 malicious skills, and more than half of the confirmed cases came from one threat actor using templated brand impersonation at scale - arXiv. When no official skill exists for a popular product, the slot is open to whoever fills it first. Publishing the official skill, from a source users can verify, is how you close it.

How to apply this. Rank your candidate skills by the size of the gap between what agents do today and what you want them to do, not by the size of your docs. The highest-value skill is usually the one that fixes the most common wrong default, which you can find by asking two or three agents to integrate your product cold and reading what they produce.

3. Skill, MCP Server, AGENTS.md or llms.txt: Which Layer Does What

Product teams now face four different files that all claim to make a product "agent-ready", and the most common mistake is shipping the wrong one for the job. The confusion is understandable because all four put text in front of a model. They differ in when that text loads, who controls it, and whether it can take action or only advise.

An MCP server gives an agent live access: your data, your actions, behind your authentication. A skill gives an agent judgment: the sequence of steps, the defaults, the gotchas and what good output looks like. AGENTS.md is the user's own file in their repository, loaded on every turn, holding rules for their codebase. llms.txt is a directory of your documentation pages that an agent can read when it decides to research. Mintlify, which hosts both for the documentation sites it runs, puts the difference simply: llms.txt "is a directory", while a skill "is a capability summary" that tells agents what they can accomplish, which inputs they need and which constraints apply - Mintlify.

The dashed arrow is where most of the value sits. Both big platforms now say a product should ship an MCP server and a skill together. Anthropic's plugin guide puts it bluntly: "A connector alone leaves Claude to work out your workflow from tool names. The skill is where you put the sequence, the defaults, and what good output looks like" - Claude. OpenAI says the same thing from the other side: use the skill for workflow instructions and the server "for live data, authorization, and controlled actions" - OpenAI. If you have already followed our guide to shipping an MCP server for your product, the skill is the missing half. Founden, which publishes this guide, exposes its builder to agents through an MCP server started with npx founden-mcp - Founden MCP, and the same logic applies to it.

A hard constraint decides some cases for you. On the Claude API, skills run in a sandboxed code-execution container with no network access and no runtime package installation - Claude Docs. A skill that tells the agent to call your REST API directly will fail there. Anything that needs to reach your product belongs in an MCP server; the skill explains how to use it.

When AGENTS.md beats a skill. Vercel's Next.js evals produced the most important counterexample in the field. A compressed 8KB docs index placed in AGENTS.md scored a 100% pass rate, while a skill scored 53% by default (no better than no documentation) and 79% only after the prompt explicitly told the agent to use it - Vercel. The reason is structural: AGENTS.md loads on every turn, while a skill loads only when the model decides it is relevant. Knowledge that applies to almost every task in a codebase (framework conventions, version-matched APIs) belongs in always-on context. Knowledge that applies to specific jobs belongs in a skill. We explain how to keep one AGENTS.md working across Claude Code, Codex and Cursor in our AGENTS.md guide.

Choosing the layers for your product comes down to what kind of product it is:

These pairings follow from the load timing of each layer, not from preference. An always-on file is expensive because every turn pays for it, so it should hold only what nearly every turn needs. A skill is cheap until used, so it can hold depth, but it must earn activation through its description. An MCP server is the only layer that can act, so anything with side effects or private data must go through it. If you are unsure, ship the MCP server and a skill first: that pair is what both the Anthropic and OpenAI directories are designed around.

IBM's explainer is a useful nine-minute primer on how these layers divide the work, especially for teammates who have only heard of one of them.

IBM frames the four techniques as playing different roles in helping agents access information, follow procedures and learn from experience; in that framing a skill is the procedure, and it rarely works alone. For a product team, the practical consequence is that your skill and your MCP server should be designed together, with the skill naming the exact tools it expects and the order to call them in.

4. Anatomy of a Skill: The Specification in Plain Terms

The specification is short enough to read in a few minutes, and that is deliberate. A skill is a directory containing, at minimum, a SKILL.md file: YAML frontmatter followed by Markdown instructions. Everything else is optional convention. The brevity is why seventy-plus clients could adopt it quickly, and it is also why the quality of a skill depends almost entirely on what you write rather than on any format feature.

Only two frontmatter fields are required, and only one of them does real work at runtime. The name identifies the skill; the description is what the agent reads to decide whether to load the rest. The other four fields are optional and mostly informational, with one experimental exception - Agent Skills specification.

A typical product skill on disk looks like this. The three optional folders are conventions, not requirements: scripts/ for executable code, references/ for documentation the agent reads on demand, and assets/ for templates and data files.

acme-invoices/
├── SKILL.md              # frontmatter + core instructions (under 500 lines)
├── references/
│   ├── api-errors.md     # read only when the API returns an error
│   └── migration-v3.md   # read only when upgrading from v2
├── scripts/
│   └── validate_payload.py
└── assets/
    └── invoice-template.json

The design principle that makes this work is progressive disclosure, and it is worth understanding precisely because it dictates how you write. An agent loads skills in three tiers: about 100 tokens of name and description per skill at startup, the full SKILL.md body (the specification recommends under 5,000 tokens and 500 lines) only when the skill activates, and the files in scripts/, references/ and assets/ only when the instructions point to them - Agent Skills specification.

Two details in that flow matter for product teams. First, the decision point in the middle is made by the model, not by keyword matching in the client; the client implementation guide says most agents rely on "the model's own judgment as the activation mechanism" - Agent Skills. Your description is therefore persuasion aimed at a model, not a search index. Second, scripts can run without their source code entering the context window, so a long validation script costs only its output.

Anthropic's own illustration of a minimal skill shows how little structure is needed. The frontmatter carries the identity and trigger; the Markdown body carries the procedure and points to two reference files the agent opens only when the task calls for them.

Notice the last sentence of the overview in that image: it tells the agent which file to read and when ("If you need to fill out a PDF form, read ./forms.md and follow its instructions"). That conditional pointer is the single most useful pattern in skill writing, because it lets a skill carry deep reference material at almost no context cost.

What real skills look like in aggregate is a useful calibration. In a sample of 767,425 public skills, the median SKILL.md was about 1,200 tokens, the median full bundle about 1,800 tokens, and 86.4% of bundles contained five files or fewer; Markdown made up 51.7% of all files - SkillsBench. Most skills are small, and the benchmark evidence suggests that is the right instinct: size is not a quality signal, and as section 7 shows, the most exhaustive skills perform worst.

Once loaded, a skill tends to stay. In Claude Code, an invoked skill's rendered content enters the conversation as a single message and remains across later turns; after context compaction, Claude Code re-attaches the most recent invocation of each skill, keeping the first 5,000 tokens of each within a combined 25,000-token budget - Claude Code Docs. The practical rule: put the instructions that must survive a long session at the top of SKILL.md, and write them as standing rules rather than one-time steps.

How to apply this. Draft your skill as a short SKILL.md that a new engineer could follow in ten minutes, push everything else into conditional reference files, and keep the frontmatter to the six standard fields unless you have a specific client feature you need (section 8 covers those).

5. How to Create an Agent Skill, Step by Step

The fastest way to write a bad skill is to paste your documentation into a SKILL.md. Documentation explains what your product can do; a skill must change what an agent actually does, which means it has to be built from the gap between the two. The steps below follow the order that the standard's authoring guidance, Anthropic's and OpenAI's own instructions and the benchmark evidence point to, and each one guards against a specific way skills fail.

Each step produces an artifact you keep: a list of agent mistakes, a scope decision, the SKILL.md, supporting files and a validation pass. The worked example uses a hypothetical invoicing API, called Acme Invoices here, purely as an illustration; replace it with your product's real defaults and failure modes.

Step 1: Collect the mistakes agents make with your product

Before writing anything, run your five most common integration tasks through two or three agents with no skill installed, and save what they produce. Read the traces, not just the final code. You are looking for the specific places an agent goes wrong: a deprecated endpoint, the wrong SDK, a missing idempotency key, a test-mode default that leaks into production. These failures are your skill's real content.

The standard's authoring guide makes the same point from the other direction: skills generated from an LLM's general knowledge produce "vague, generic procedures" such as "handle errors appropriately", while skills grounded in real expertise capture "the specific API patterns, edge cases, and project conventions that make a skill valuable" - Agent Skills best practices. The richest sources are the ones nobody publishes.

• Support tickets and the corrections your team writes most often
• Incident reports and runbooks, which record failures that defy reasonable assumptions
• Code review comments on integrations, which reveal recurring mistakes
• Your changelog, especially breaking changes and deprecations after the models' cutoffs
• Agent traces from your own test runs, as described above

Ranked by value, the changelog and the agent traces usually come first, because they capture exactly the knowledge that models lack: anything that changed after their training data ends. Support tickets come next because they show which mistakes cost your users time. This also explains why skills auto-generated from documentation underperform: documentation describes the happy path, while the content that changes agent behavior is the list of non-obvious corrections. Keep that list; it becomes the gotchas section of your skill.

Step 2: Scope one skill per job

Deciding what one skill covers is like deciding what one function does. Too narrow and several skills load for one task, with overhead and conflicting instructions; too broad and the description cannot say precisely when to activate - Agent Skills best practices. The benchmark data agrees: tasks paired with one skill gained 18.0 points and tasks with two or three gained 19.0, but four or more gained only 10.1, "suggesting excess content creates overhead or conflicting guidance" - SkillsBench.

Real vendors split along the jobs users bring, not along their product's org chart. Supabase publishes just two skills: one for any Supabase task and one for Postgres best practices that applies "for Postgres running anywhere" - Supabase index. Stripe publishes ten from its docs domain, including a connect-recommend skill for choosing a Connect setup and an upgrade-stripe skill for API version migrations - Stripe index. Cloudflare publishes 19, roughly one per product area - Cloudflare index.

A useful test: if two candidate skills would trigger on the same user request, merge them; if one skill's instructions contain a section that never applies to half its triggers, split it. Start with the one job where agents fail most often with your product, ship it, and add the second skill only after the first one triggers reliably.

Step 3: Write the SKILL.md

Write the body as instructions to a capable colleague who has never seen your product. Focus on what the agent would get wrong without you: "Would the agent get this wrong without this instruction? If the answer is no, cut it" - Agent Skills best practices. Give one default rather than a menu of options, explain why each rule exists, and teach the approach to a class of problems rather than the answer to one.

Here is a compact, illustrative skill for the hypothetical Acme Invoices API. Every section exists because a test run showed an agent getting that point wrong.

---
name: acme-invoices
description: >
  Use this skill when the user wants to create, send, update or reconcile
  invoices with Acme Invoices, connect Acme to an app, migrate from the v2
  API, or debug Acme webhooks, even if they only say "billing" or "send an
  invoice". Covers the v3 API, the official SDKs, idempotency and webhook
  verification. Not for payroll or expense reports.
license: MIT
compatibility: Requires network access to api.acme.example and an Acme API key.
metadata:
  version: "3.2.0"
  source: "https://docs.acme.example/agent-skills"
---

# Acme Invoices

## Defaults
- Use the v3 REST API through the official SDK (`@acme/invoices` for
  TypeScript, `acme-invoices` for Python). Never call v2 endpoints: they
  stop accepting writes on 2027-01-31.
- Send an `Idempotency-Key` header on every POST. Retries without one
  create duplicate invoices, which users cannot delete, only void.

## Workflow
1. Read the API key from the environment (`ACME_API_KEY`). Never hard-code it.
2. Create the customer first, then the invoice, then finalize it.
3. Verify webhooks with the SDK's `verifySignature`, using the raw body.
4. Run `python scripts/validate_payload.py <file>` before sending a bulk batch.

## Gotchas
- Amounts are integers in the smallest currency unit (cents), never floats.
- Test keys start with `ak_test_`; a test key against production returns 404,
  not 401.
- A finalized invoice cannot be edited. Void it and create a new one.

## When to read more
- Read `references/api-errors.md` if the API returns any non-2xx status.
- Read `references/migration-v3.md` only when the project still uses v2.

Three choices in that file are deliberate. The description begins with "Use this skill when", names the user's intent in plain words including the ones that do not mention the product ("billing", "send an invoice"), and states what the skill is not for, which prevents false activations on adjacent tasks. The defaults name exact packages and dates rather than "use the latest SDK", because "latest" is precisely what the model gets wrong. And each reference file has a stated condition for reading it, so the deep material costs nothing until it is needed.

Step 4: Add references and scripts only where they earn their place

References are the cheap part: move anything long, rare or version-specific into references/ and point to it conditionally. Keep each file focused and one level deep from SKILL.md, since deeply nested chains make agents read partial files; Anthropic also recommends a table of contents at the top of any reference file longer than 100 lines - Claude best practices.

Scripts are the expensive part, in security and in maintenance. Add one only when the agent would otherwise reinvent the same logic on every run, or when a step must be deterministic, such as validating a payload against your schema. OpenAI's guidance is blunt: "Do not add a script when instructions and existing tools can complete the task reliably" - OpenAI. The security data backs the caution: skills that bundle executable scripts were 2.12 times more likely to contain a vulnerability than instruction-only skills - arXiv.

When you do ship a script, design it for an agent rather than a person. The standard's script guide lists the requirements: no interactive prompts (an agent cannot answer a TTY prompt, so the script hangs), a --help that documents the interface, structured output on stdout with diagnostics on stderr, distinct exit codes, idempotent behavior and a --dry-run for anything destructive - Agent Skills. Inline dependency metadata keeps the script self-contained:

# /// script
# requires-python = ">=3.11"
# dependencies = ["jsonschema>=4.22,<5"]
# ///
"""Validate an Acme invoice batch before sending.

Usage: uv run scripts/validate_payload.py BATCH.json  (run from the skill root)
Exit codes: 0 valid, 2 invalid input file, 3 schema violations found.
"""
import json, sys
from jsonschema import Draft202012Validator

def main() -> int:
    if len(sys.argv) < 2 or sys.argv [1] in ("-h", "--help"):
        print(__doc__, file=sys.stderr)
        return 2
    batch = json.load(open(sys.argv [1]))
    schema = json.load(open("references/invoice.schema.json"))
    errors = [
        {"path": list(e.path), "message": e.message}
        for e in Draft202012Validator(schema).iter_errors(batch)
    ]
    print(json.dumps({"valid": not errors, "errors": errors}))
    return 3 if errors else 0

if __name__ == "__main__":
    sys.exit(main())

The pattern to copy is the error output. A message such as "field amount must be an integer, got 49.99" lets the agent fix its own mistake on the next attempt, which is the entire point of a validation loop. A bare "invalid input" wastes a turn and often sends the agent down a wrong path.

Step 5: Validate the package before anyone installs it

Validation catches the boring failures that silently disable a skill: a name that does not match its folder, a description over the limit, YAML that one client accepts and another rejects. The standard ships a reference validator, skills-ref, which checks frontmatter and naming conventions, though its maintainers describe it as intended for demonstration rather than production - skills-ref.

# Reference validator from the standard (demonstration-grade)
git clone https://github.com/agentskills/agentskills && cd agentskills/skills-ref
uv sync && source .venv/bin/activate
skills-ref validate ~/code/acme-skills/acme-invoices

# GitHub CLI v2.90+: validates against the spec and checks repo protections
gh skill publish
gh skill publish --fix

# Claude Code: validate a plugin bundle before submitting it
claude plugin validate ./acme-plugin

The GitHub CLI check is worth running even if you never use gh to install anything. Besides validating every skill against the specification, gh skill publish checks repository settings such as tag protection, secret scanning and immutable releases, which protect users who pin to a version even if someone later gains control of your repository - GitHub Changelog.

Why this matters, and how to apply it. Each step above removes a specific failure mode: Step 1 prevents generic content, Step 2 prevents conflicting skills, Step 3 prevents vague defaults, Step 4 prevents fragile or risky scripts, and Step 5 prevents silent load failures. Do them in order for your first skill, then make Steps 1 and 5 part of every release.

6. The Description: One Paragraph That Decides Everything

The description is the only part of your skill an agent sees before deciding whether to read the rest. The standard's guide says it plainly: "the description carries the entire burden of triggering" - Agent Skills. A brilliant body behind a weak description is a skill that never runs, which is exactly what Vercel measured when its skill went unopened in more than half of its eval cases.

Anthropic's diagram of the context window shows why. Every installed skill contributes a short snippet to the system prompt, the user's message arrives, and the model decides on its own whether to open a SKILL.md, then whether to follow a reference inside it. Nothing forces the read.

The snippet row at the top of that diagram is a shared, limited space, and this is the part most guides skip. Your description competes for a budget with every other skill the user has installed. Each client handles that competition differently:

Read together, these rules mean three things for a product skill. First, put the key use case and the trigger words in the first sentence, because truncation cuts from the end; OpenAI's docs say to "front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened". Second, an unused skill degrades over time in Claude Code, since its description is the first to be dropped, so a skill that triggers rarely can stop triggering at all. Third, the 1,024-character spec limit is the safe ceiling for a skill meant to load everywhere, even though some clients accept more.

Length is a real trap, and it caught Founden, which publishes this guide. Founden serves a catalog of 28 builder skills into each company workspace its AI builder works in. When it added a check for Claude Code's 1,536-character listing cap, seven descriptions had already drifted past it, silently pushing their trigger phrases out of view; the check now logs any description over the cap rather than letting it go dark. No validator would have reported the problem, because the skills still loaded.

The four rules of a description that triggers, from the standard's optimization guide - Agent Skills:

• Use imperative phrasing: "Use this skill when...", because the model is deciding whether to act
• Describe user intent, not your implementation: what the user is trying to achieve
• Be pushy about scope: list contexts where it applies even when the user never names your product
• State boundaries: what the skill does not cover, to stop near-miss activations

Real vendor descriptions show these rules at work. Supabase's main skill opens with "Use when doing ANY task involving Supabase" and then lists triggers ranging from getSession errors to RLS surprises and Edge Function crashes. Stripe's connect-recommend description runs to 804 characters of concrete situations, from "building a marketplace" to "needs to pay out sellers", and even carves out an exception for "operational SaaS without payment routing". Mintlify's skill triggers on migrating "from Docusaurus, GitBook, ReadMe, Fern", naming competitors' products because that is how users phrase the request. Each is written for the user's words, not the vendor's.

One nuance prevents wasted effort. Agents typically consult a skill only for tasks beyond what they can do alone; a one-step request such as "read this PDF" may not trigger a PDF skill even with a perfect description - Agent Skills. Aim the description at the multi-step, product-specific work where your knowledge changes the outcome, and do not chase triggers on trivial requests.

How to apply this. Write the description last, after you have the body and a list of real user requests. Start with "Use this skill when", put the most common request first, add the indirect phrasings and competitor names users actually type, add one sentence of boundaries, and keep it under 1,024 characters. Then test it, which is the next section.

7. Testing a Skill: Trigger Evals and Output Evals

A skill has two independent ways to fail: it does not activate when it should (or activates when it should not), and it activates but does not improve the result. They need different tests. Trigger evals check the description; output evals check the body. Teams that test only by "trying it once" usually discover the first failure from users and never discover the second.

Testing matters more for skills than for prompts because model behavior is nondeterministic and harnesses differ. In SkillsBench, the same model scored 61.2% with skills in Claude Code but 53.1% in OpenHands, which the authors read as evidence that "the harness's discovery, prompting, execution, and tool-use loop mediate realized benefit" - SkillsBench. Your skill has to be tested where your users run it.

Trigger evals: does the agent open your skill?

Build a set of about 20 realistic queries: 8 to 10 that should trigger the skill and 8 to 10 that should not. The most valuable negatives are near-misses, requests that share vocabulary with your skill but need something else - Agent Skills. For an invoicing skill, "what's the weather today" tests nothing, while "write a script that imports last year's invoices into Postgres" shares the vocabulary but needs a data import, not your invoicing workflow.

[
  {"query": "our customers keep getting charged twice when the request times out, can you fix the acme integration in src/billing?", "should_trigger": true},
  {"query": "send the March retainer invoice to Hollis & Webb, net 30", "should_trigger": true},
  {"query": "migrate this repo off the old acme v2 client", "should_trigger": true},
  {"query": "write a script that loads last year's invoices from a CSV into postgres", "should_trigger": false},
  {"query": "add a payroll export for our contractors", "should_trigger": false}
]

Run each query three times, because the same query can trigger on one run and not the next, and count a should-trigger query as passing when its trigger rate exceeds 0.5. Split the set into a 60% train and 40% validation portion, revise the description using only train failures, and pick the iteration with the best validation score, which is often not the last one. Five iterations is usually enough, according to the same guide. In Claude Code you can detect activation from JSON output, as the standard's own example script does:

# Returns success if Claude Code invoked the skill for this query
check_triggered() {
  claude -p "$1" --output-format json 2>/dev/null \
    | jq -e --arg skill "acme-invoices" \
      'any(.messages [].content []; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
      > /dev/null 2>&1
}

The discipline that matters most is resisting overfitting. When a positive query fails, do not paste its exact words into the description; find the general category of request it represents and describe that. A description tuned to twenty specific phrasings fails on the twenty-first, while one that describes the user's goal generalizes.

Output evals: is the agent better with your skill?

Output evals compare the same tasks with and without the skill (or against the previous version). Each test case has a realistic prompt, a human-readable description of success, optional input files, and, after the first run, a few verifiable assertions such as "the request includes an Idempotency-Key header" or "amounts are integers". Store them in evals/evals.json inside the skill folder, run each case in a clean context, grade assertions with evidence, and aggregate pass rate, tokens and time into a benchmark - Agent Skills.

{
  "skill_name": "acme-invoices",
  "evals": [
    {
      "id": 1,
      "prompt": "Our webhook handler in api/acme.ts accepts every request. Make it secure.",
      "expected_output": "Handler verifies the signature with the SDK using the raw body and rejects failures with 400.",
      "files": ["evals/files/acme.ts"],
      "assertions": [
        "Uses verifySignature from @acme/invoices",
        "Reads the raw request body, not parsed JSON",
        "Returns 400 on a failed signature"
      ]
    }
  ]
}

OpenAI's engineering guidance frames the same idea as four kinds of checks: outcome goals (did the task complete), process goals (did the agent invoke the skill and run the intended steps), style goals (does the output follow your conventions) and efficiency goals (did it get there without thrashing) - OpenAI. The efficiency check is the one teams forget, and it is where an over-long skill shows up: more tokens and more steps for the same outcome.

The benchmark evidence on skill size makes this concrete. SkillsBench grouped tasks by the complexity of their curated skills, and the pattern is stark.

Compact and standard skills added 19.0 and 21.5 points; detailed skills added 14.5; comprehensive documentation added 0.7, effectively nothing. The authors' conclusion is the best one-line rule in skill writing: "focused procedural guidance beats exhaustive prose". This is also why a skill generated by dumping your docs into a file disappoints, and why Anthropic's own advice is to build evaluations before writing extensive documentation, then write "just enough content to address the gaps and pass evaluations" - Claude best practices.

You do not have to build this harness from scratch. Anthropic's skill-creator skill automates the description loop (splitting the eval set, measuring trigger rates in parallel and proposing improvements) and much of the output loop - Agent Skills. Codex ships a built-in $skill-creator that asks what the skill does and when it should trigger - OpenAI Codex. Remember the SkillsBench result before you let one write the content for you: these tools are good at structure and testing, and bad at supplying the expertise.

Matt Pocock, whose skills hold several of the top spots on skills.sh, gave the clearest practitioner talk on this at AI Engineer: a checklist for triggers, structure, steering and pruning. The section from 16:48 on removing "sediment" from skills is the part most teams need.

His pruning advice lines up with the benchmark: every instruction that does not change behavior is a cost, paid in tokens and in the agent's attention. How to apply this: keep a small eval set in the skill's repository, run trigger and output evals before every release, and treat any instruction that does not move an assertion as a candidate for deletion.

8. One Skill, Every Agent: Portability Rules

The promise of the standard is that one folder works in every agent, and for the core format that promise holds. The friction sits at the edges: each client looks for skills in different directories, accepts different extra frontmatter fields, runs skills with different network permissions, and follows instructions with different sensitivity. A product skill has to be written to the common core and packaged for the edges, otherwise it works perfectly in the agent you tested and fails quietly in the four you did not.

The cross-client convention for locations is .agents/skills/, which the standard's client guide describes as "a widely-adopted convention for cross-client skill sharing", while noting that the specification itself only defines what goes inside a skill, not where it lives - Agent Skills. Claude Code is the main exception: it reads .claude/skills/, which is why installers write to both.

The practical answer is to stop hand-copying folders. The skills CLI can install one canonical copy and symlink it into each detected agent's directory (its recommended method), so one update reaches all of them - skills CLI. For your own repositories, keep the source of truth in .agents/skills/ and let tooling handle Claude Code's path.

The frontmatter rule is the one that breaks most often. Claude Code accepts a set of useful extensions: disable-model-invocation (only the user can trigger it), user-invocable: false (only the model can), context: fork (run in a subagent), model, and richer allowed-tools semantics, and it silently ignores fields it does not recognize. But claude.ai uploads and the Claude Skills API accept only the six specification fields and reject anything else with an unexpected-key error - Claude Code Docs. A product skill meant for every surface should therefore stick to name, description, license, compatibility, metadata and, sparingly, allowed-tools.

Client-specific presentation belongs in client-specific files. Codex and the ChatGPT desktop app read an optional agents/openai.yaml for a display name, icons, a brand color, a default prompt, a policy flag that disables implicit invocation, and declared MCP dependencies, so the app knows which server the skill needs - OpenAI Codex:

# acme-invoices/agents/openai.yaml (read by Codex and the ChatGPT desktop app)
interface:
  display_name: "Acme Invoices"
  short_description: "Create, send and reconcile invoices with Acme"
  icon_small: "./assets/acme-small.svg"
  brand_color: "#1F6FEB"
policy:
  allow_implicit_invocation: true
dependencies:
  tools:
    - type: "mcp"
      value: "acme"
      description: "Acme Invoices MCP server"
      transport: "streamable_http"
      url: "https://mcp.acme.example/mcp"

Write for every model, not your favorite one. Models differ in how strictly they read a skill. OpenAI's notes on GPT-6 Astra say it follows longer instructions better but "can also be more sensitive to information in context", so that "unclear or conflicting guidance in a skill file may cause the model to pause and block work early"; OpenAI recommends stating that the user's instructions take precedence over a skill's - OpenAI. Anthropic recommends testing a skill with each model tier you plan to support, because "what works perfectly for Opus might need more detail for Haiku" - Claude best practices. We compared how the major coding agents behave in practice in Claude Code vs Codex vs Devin.

Five portability rules prevent most cross-client failures:

• Use provider-neutral language: OpenAI's conversion guide asks you to replace "Claude" with "the model" in skill instructions - OpenAI
• Use forward slashes and paths relative to the skill root, never Windows-style paths
• Declare environment needs in compatibility, including network access
• Name MCP tools fully (server and tool), so agents with several servers do not guess
• State the precedence rule once: explicit user instructions win over the skill

The network rule deserves emphasis because it changes the design, not just the wording. A skill that runs in Claude Code has the network access of any program on the user's machine; on claude.ai it depends on admin settings; through the Claude API it has none at all, and custom skills uploaded to one Claude surface do not sync to the others - Claude Docs. If your workflow needs your API, route that part through an MCP server and let the skill describe it, as section 3 explained.

How to apply this. Keep one canonical skill folder with spec-only frontmatter, add agents/openai.yaml and a Claude plugin manifest as thin packaging layers, and run your trigger evals in at least two different agents before release.

9. Distribution: Getting Your Skill Into Agents

A skill in a private folder helps nobody but you. Distribution is where product teams have the most leverage and spend the least thought, mostly because most of the channels arrived within the last year and each vendor documents only its own. The table at the top of this guide scored seven channels; this section explains how each one works and how they fit together.

The structure that works is one source of truth feeding several channels. You maintain the skill in one repository; your release process publishes it to your docs domain, tags a GitHub release, and updates the plugin bundles the directories read from. Each channel then reaches a different set of agents and users without a second copy of the content to keep in sync.

9.1 Your docs domain: the well-known index

The cheapest channel with the strongest trust signal is your own domain. A Cloudflare-led draft, now at version 0.2.0, defines an index at /.well-known/agent-skills/index.json that lists each skill with a name, a type (skill-md for a single file or archive for a bundle), a description, a URL and a SHA-256 digest of the artifact - Agent Skills Discovery RFC. Because the file sits on your domain, it proves origin in a way no registry listing can, and the digest lets a client verify that what it downloaded is what you published.

Adoption is already real among developer-facing companies. As of October 26, Cloudflare, Vercel, Supabase and Mintlify serve the v0.2.0 index, while Stripe and Feishu (Lark) serve the earlier /.well-known/skills/ path; Stripe documents the install as a single command, npx skills add https://docs.stripe.com - Stripe Docs. Mintlify goes further and generates a skill.md automatically for every public documentation site it hosts, refreshed as the docs change - Mintlify.

The spread is instructive. Feishu publishes one skill per app (approvals, calendar, docs, mail), Cloudflare roughly one per product area, Supabase deliberately only two. None of these is wrong; the right number follows the jobs your users bring, as section 5 argued. A minimal v0.2.0 index for the example product looks like this:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "acme-invoices",
      "type": "archive",
      "description": "Use this skill when the user wants to create, send, update or reconcile invoices with Acme Invoices...",
      "url": "https://github.com/acme/agent-skills/releases/download/v3.2.0/acme-invoices.tar.gz",
      "digest": "sha256:3f1c...e9a0"
    }
  ]
}

Supabase uses exactly this pattern: its index points at archives attached to a tagged GitHub release (v0.1.9), each with its digest, so the domain proves origin and the release provides an immutable artifact - Supabase index. The draft also instructs clients not to execute bundled scripts by default, one more reason to keep scripts optional.

9.2 A public GitHub repository: npx skills, gh skill and skills.sh

A public repository is the lowest-effort channel and the one most agents can install from. Vercel's skills CLI installs from GitHub shorthand, any Git URL or a docs domain, supports Claude Code, Codex, Cursor, OpenCode and 75 more agents, installs to the project by default (-g for global), and exposes find, check and update commands - skills CLI. Installs are counted through anonymous telemetry and ranked on skills.sh, whose all-time leaderboard listed 1,463,223 skills on October 26. The registry also publishes security audit results for listed skills from Gen Agent Trust Hub, Socket and Snyk - skills.sh.

GitHub's own CLI added a parallel path in April. gh skill install installs into Copilot, Claude Code, Cursor, Codex, Gemini CLI or Antigravity, supports pinning to a tag or commit with --pin, and gh skill update reads provenance metadata from each installed skill to check for upstream changes - GitHub Changelog. For a vendor, the important consequence is that a tagged, immutable release is now the unit users can pin to.

# What your users run (any of these)
npx skills add acme/agent-skills --skill acme-invoices
npx skills add https://docs.acme.example
gh skill install acme/agent-skills acme-invoices --pin v3.2.0

# What you add to your README
[![skills.sh](https://skills.sh/b/acme/agent-skills)](https://skills.sh/acme/agent-skills)

There is a reputational layer too. skills.sh keeps an Official list of skills published by the companies that build the technology; on October 26 it listed 102 organizations, from Stripe, Supabase, Sentry and Cloudflare to Microsoft and NVIDIA - skills.sh. Being on that list is the clearest signal to a developer browsing the registry that a skill really is yours. For context on which community skills developers already install for web work, see our ranking of the top Claude Code skills for web and app builds.

9.3 The Anthropic directory

Anthropic's directory is the most complete channel on the list, with one structural rule you must know first: skills are not a submission type on their own; you put them in a plugin bundle - Claude. Anyone on a paid plan (Pro, Max, Team or Enterprise) can submit from the developer portal at claude.ai, with no partner program. Every version gets automated validation and a security scan, and a person reviews each new listing before it goes live.

Once listed, the channel solves the freshness problem. You keep the listing current by merging to the branch the directory tracks; it picks up each commit, scans it and serves it to the people who have your plugin. The Usage tab shows installs, versions, how often each skill and MCP server runs, and error rates, which none of the other channels in this guide documents. If your plugin references a remote MCP server you run, submit that server as a separate connector too and pair the two listings, so users see one set of tools.

{
  "name": "acme-invoices",
  "displayName": "Acme Invoices",
  "version": "3.2.0",
  "description": "Create, send and reconcile Acme invoices from a conversation, with the Acme connector and the official integration rules.",
  "author": { "name": "Acme", "url": "https://acme.example" },
  "license": "MIT"
}

That manifest lives at .claude-plugin/plugin.json, with skills under skills/<name>/SKILL.md; the directory also requires a license and a README of at least 40 words - Claude. Run claude plugin validate before submitting, then follow the portal's validation findings.

The underused lever is the CLI hint. If your product has a CLI or SDK and your plugin is in Anthropic's official marketplace, your tool can print a one-line <claude-code-hint v="1" type="plugin" value="acme-invoices@claude-plugins-official" /> tag to stderr when the CLAUDECODE environment variable is set. Claude Code strips the line before the model sees it and shows the user a one-time prompt to install your plugin - Claude Code Docs. It is the only mechanism on this list that puts your skill in front of a user at the exact moment their agent starts using your product.

9.4 The OpenAI plugin directory

OpenAI's equivalent is one universal plugin directory shared by ChatGPT and Codex: a plugin can bundle skills, MCP connections or both, and it reaches ChatGPT on web, desktop and mobile as well as Codex - OpenAI. You submit a ZIP through the platform portal, complete individual or business verification to publish under your name, resolve automated findings, provide review details and test cases, and choose when to publish once approved - OpenAI.

The dashboard above shows the shape of the process: each uploaded package version has its own review status, separate from the MCP configuration. That separation explains the channel's main trade-off. After publication, OpenAI scans your MCP server daily and ships eligible server changes without a new package, but any change to skills or metadata needs a new ZIP with its own checks and review. Skills you update often are better served by a channel that tracks a branch.

Two newer paths are worth knowing. If you already have a Claude plugin, OpenAI accepts a skills-only upload of the same archive and converts the manifest, after you replace Claude-specific wording - OpenAI. And OpenAI can import skills directly from your MCP server during submission, using a bounded subset of the draft MCP Skills extension, though the import is a static snapshot rather than a live fetch - OpenAI. For the broader question of selling through ChatGPT, see our guide to selling your product inside ChatGPT.

9.5 Cursor, npm packages and your own CLI

Cursor runs its own Marketplace of plugins distributed as Git repositories; every plugin is manually reviewed before listing, and Cursor loads plugins in both its own format and the open Agent Plugins format - Cursor Docs. Agent Plugins 1.0.0, released August 6, standardizes a root plugin.json plus skills/ and mcp.json, and launched with support from ChatGPT and Codex, Cursor, GitHub Copilot, Kiro and VS Code - Vercel. Writing one Agent Plugins package is the closest thing today to "submit once, install anywhere".

For libraries, the most elegant channel is the package itself. The skills CLI can sync skills that ship inside npm dependencies (npx skills experimental_sync), relinking them on every run so the skill always matches the installed version of your package; the feature is explicitly experimental - skills CLI. A skill that versions with your SDK cannot drift away from the API the user actually has installed.

Finally, a product with its own CLI can install everything itself. Stripe's stripe agent setup detects which agents a developer uses and installs the plugin that configures the Stripe MCP server and keeps Stripe's skills current, with manual npx skills add as the fallback - Stripe Docs. It is the most effort of any channel, and for a company whose developers already live in its CLI, the most reliable.

How to apply this. Ship the domain index and the GitHub release on day one, submit the plugin bundle to Anthropic's directory once the skill passes its evals, add the OpenAI directory when your skill changes less than monthly, and add the CLI hint the same week your plugin is listed.

10. Reading the Install Numbers Honestly

Install counts are the most visible metric in the skills ecosystem and the easiest to misread. Vercel's state-of-the-registry report is unusually candid about this: its install figures "use aggregate registry counters" that "do not represent unique people or necessarily independent choices" - Vercel. Treat installs as a rough signal of reach, never as users.

Two patterns make the counters noisy. First, concentration: nearly half of all skills on skills.sh were installed exactly once, 375 skills (0.04% of the registry) account for 62% of installs, and the top 1.2% account for 94%; even the most-installed skill holds less than 1% of all installs. Second, bundling: skills.sh credits Feishu's domain with 29 skills and 21.7 million total installs, and its top four sit at 812.8K, 812.2K, 812.1K and 811.9K installs - skills.sh. Near-identical counts across a pack mean one install command counts once per skill, so a vendor that splits into more skills reports more installs without reaching more people.

The useful part of the report is where demand exceeds supply. Vercel compared each category's installs per listing with the registry average.

The average business operations skill draws 74% more installs than the registry average, writing and documents 50% more, and cloud and infrastructure 42% more, while software engineering skills draw about 30% fewer and research skills 55% fewer. Supply leans technical because skills started in developer tools; demand is broader because agents now work in every part of a company. Cross-industry skills, the kind that help a bank and a restaurant alike, make up 66% of classified skills but 87.5% of installs.

For a product team, this reframes the opportunity. If your product serves business operations, documents or infrastructure, a well-made skill faces less competition per install than yet another coding skill. And the metric to optimize is not installs but activation and outcome: how often the skill runs when it should, and whether tasks succeed more often with it. The Anthropic directory's per-skill run counts and error rates are the closest any channel comes to that today; elsewhere, instrument your MCP server and API to see which calls arrive with your skill's recommended patterns.

11. Keeping Skills Current and Safe

A skill solves the stale-knowledge problem only if the skill itself does not go stale. Every installed copy is a snapshot. Stripe states the consequence directly: "Manually installed skills don't auto-update", and users must run npx skills update -y to get new versions - Stripe Docs. A skill that teaches last quarter's API version recreates the exact failure it was meant to fix, now with your name on it.

Freshness is therefore a distribution property, not just a writing task. Channels that track a branch (the Anthropic directory, Cursor team marketplaces with auto-refresh, your own plugin installer, npm-synced skills) update users when you release. Channels that copy files (manual installs from GitHub or a domain) update only when users act. Design for the second case as if it were the default.

Four versioning practices keep stale copies from doing damage:

• Put a version in metadata and publish a changelog next to the skill
• Publish immutable, tagged releases with digests, so pinned installs cannot change under users
• Write dated version checks into the body ("If the project uses the v2 client, read references/migration-v3.md first; v2 stops accepting writes on 2027-01-31"), so an old copy still warns about the cutoff
• Keep one canonical source and generate every channel's package from it

The last practice is the one most teams skip, and it decides whether the other three hold. Mintlify's hosted skill carries a metadata line telling readers it was generated from a canonical source and should be edited there, "not this copy" - Mintlify skill.md. Founden, which publishes this guide, applies the same principle to its builder skills: each one is read from a single source document and written into a company's workspace when the desktop app connects, so an improvement reaches every company on its next sync rather than living in many diverging copies. Whatever your tooling, the rule is the same: copies are outputs, never sources.

Retiring a skill needs the same care as retiring an API endpoint. Deleting it from your repository does not remove the copies already installed, so publish a final version whose description narrows to the old trigger only and whose body tells the agent which skill or page replaces it, keep that version in your index for at least one release cycle, and only then remove it. In channels that track a branch the notice reaches users automatically; for manual installs it is the only message those users will ever receive, so make it specific.

Security is the other half of trust, and the data is sobering. A study of 31,132 skills from two marketplaces found that 26.1% contained at least one vulnerability, with data exfiltration (13.3%) and privilege escalation (11.8%) the most common patterns, and 5.2% showing high-severity patterns that strongly suggest malicious intent - arXiv.

Other audits found the same shape. Snyk scanned 3,984 skills from ClawHub and skills.sh and found 13.4% with at least one critical issue and 76 confirmed malicious payloads - Snyk. Koi Security's February audit of ClawHub found 341 malicious skills among 2,857, after which OpenClaw began scanning every published skill with VirusTotal - CSO Online. The registries reacted quickly, and the attack pattern still matters to vendors: as section 2 noted, the largest confirmed malicious campaign ran on brand impersonation.

What makes your own skill trustworthy follows from what attackers do. They hide instructions (one study takes its title from the phrase "Do not mention this to the user"), download unpinned code at runtime, request broad permissions and obscure what scripts do. None of that is subtle once you know to look for it, which is why scanners catch much of it: Snyk reports 90 to 100% recall on its confirmed malicious samples with no false positives on the top 100 skills.sh skills - Snyk. It also means a legitimate skill that borrows one of those patterns, such as an unpinned download, invites a warning in the public audits that sit next to its listing.

The defense is the inverse: no instructions that conceal actions from the user, no curl | bash, every external dependency pinned, the narrowest possible allowed-tools, readable scripts with a stated purpose, and network needs declared in compatibility. Anthropic's guidance for installers is to audit every bundled file for unexpected network calls or operations that do not match the skill's stated purpose - Claude Docs, so write your skill to pass that audit at a glance.

Two broader controls connect to topics we have covered in depth. If your skill guides agents through actions that spend money or touch accounts, pair it with the patterns in our guides to giving agents an identity rather than an API key and letting agents spend money safely. And before launch, run the skill's scripts through the same checks as the rest of your code, as in our pre-launch security checklist.

How to apply this. Release skills the way you release packages: tagged, immutable, with digests, from your own domain and your own GitHub organization, with a changelog and a security review of every script. Then check the public audit results for your listing on skills.sh after each release.

12. Where Skills Fail

Skills are not a cure-all, and the failure modes are now well documented. Knowing them in advance is the difference between a skill that quietly underperforms and one you can fix. Most failures fall into a handful of categories, and each one has a structural cause rather than a wording problem.

Activation is discretionary. The model decides whether to open a skill, and sometimes it does not. Vercel's eval saw a skill go unopened in 56% of cases until the prompt told the agent to use it; SkillsBench, by contrast, found that in its harnesses "skill discovery is usually not the bottleneck" and many failures happened after the skill was read - SkillsBench. Both can be true: activation depends heavily on the harness and the description, which is why section 7 insists on trigger evals in the agents your users run.

Skills can make things worse. In the first version of SkillsBench, 16 of 84 tasks showed negative deltas with curated skills, and the latest version still shows tasks where skills hurt specific models - SkillsBench v1. The authors' explanation is that gains shrink or turn negative "when models already have strong priors or the Skill adds overhead" - SkillsBench v4. A skill for a task the model already does well is pure cost.

Too much content dilutes the signal. Comprehensive documentation added 0.7 points in the complexity ablation, and four or more skills per task roughly halved the gain. Exhaustive skills give the agent instructions that do not apply, which it then follows anyway.

Sprawl erodes everyone's skills. Every installed skill adds to the listing on every turn. Claude Code drops descriptions for the least-used skills when the listing overflows and now ships a /skill-doctor report to find unused ones - Claude Code Docs. After the donation, one creator audited 374 skills on one of their own machines and flagged 70 for deletion and 46 that could merge into six - Mark Kashef. Your skill competes in that environment; a precise, frequently useful skill survives the cleanup.

Conflicts stall agents. Contradictions between your skill, the user's AGENTS.md and the user's request can make stricter models pause, as OpenAI's GPT-6 Astra notes warn; we covered that model's behavior in our GPT-6 Astra breakdown. State the precedence rule and avoid absolute language that will collide with a user's explicit request.

A public skill is not a moat. Anyone can copy a public SKILL.md. What cannot be copied is the maintenance: the vendor who updates the skill the day an API changes, publishes it from the domain users trust and measures whether it works. The advantage lies in the operation, not the file.

How to apply this. Review each failure mode against your skill before release, and schedule a quarterly prune: delete instructions that no eval depends on, merge skills that trigger on the same requests, and retire skills for tasks models now handle unaided.

13. What Comes Next for Skills

Several threads now in motion will shape how product skills work over the next year. None of them is speculative in the sense of being unannounced; each is a published roadmap item, a draft specification or a shipped product. The open question is pace, not direction.

Governance comes first. The AAIF roadmap starts with versioned releases of the specification, a formal proposal process and security guidance for writers and installers - Anthropic. Expect compatibility and metadata conventions to harden, and expect review checklists across directories to converge on the security guidance once it exists.

Skills over MCP is the most consequential technical change. A draft MCP extension, SEP-2640, lets an MCP server advertise and serve skills through a declared io.modelcontextprotocol/skills capability; OpenAI already supports a bounded, static subset of it for plugin submissions, while noting it is not yet part of the stable MCP specification - OpenAI. Mintlify already exposes its docs sites' skills to MCP-connected agents as MCP resources. If the extension stabilizes, the server that gives an agent your tools will also hand it the skill for using them, and the distribution problem in section 9 shrinks to "ship an MCP server".

Packaging is converging too. Agent Plugins 1.0.0 gives skills and MCP servers one portable wrapper across ChatGPT and Codex, Cursor, Copilot, Kiro and VS Code, and the Anthropic and OpenAI directories now accept closely related bundles. A year from now, maintaining a separate package per vendor is likely to look as dated as maintaining a separate SDK per cloud.

Agents are becoming buyers. Walmart's Agent Profiles, with per-agent spending limits, roll out next month; Claude Duet is on a waitlist with Stripe built in. As agents purchase, book and file on a user's behalf, the skills that describe how to transact with a product (which plan fits, which checkout flow, what not to do without approval) become the new storefront copy. Our guide to getting your site cited by ChatGPT and Claude covers the discovery half of that shift.

The economics favor whoever owns procedural knowledge. Frontier prices keep falling: Kimi K3.1 Pro arrived at half the price of Claude Opus 5.5, within a point of it on Terminal-Bench 4.0 by Moonshot's own numbers, and SkillsBench shows a cheaper model with good skills can beat a stronger one without them. When intelligence gets cheaper, the scarce input is the specific knowledge of how to do a job well with a specific product. That knowledge belongs to the vendor, and a skill is the format in which it now travels.

How to apply this. Build your skill and MCP server as one product, package them in the portable plugin format, and plan to serve the skill over MCP when the extension stabilizes, so today's work carries forward rather than being replaced.

14. Conclusion: A Decision Framework

The donation settled the format question: Agent Skills is now a neutral standard read by more than seventy agent platforms, governed the same way as MCP. What remains is execution, and the evidence points to a consistent recipe. Skills written from real expertise lift outcomes by double digits; skills an agent writes for itself make things worse; focused skills beat comprehensive ones; and a skill only helps if its description wins a crowded listing and its copy stays current.

If you run an API product (or a SaaS with an API), ship an MCP server and one skill per job agents do with it, publish both through your domain index and a tagged GitHub release, and submit the pair to the Anthropic and OpenAI directories. Add the Claude Code CLI hint if you have a CLI.

If you maintain a library or framework, ship a focused skill for the jobs that need judgment, a short AGENTS.md snippet for knowledge every task needs, and consider shipping the skill inside your npm package so it versions with your code.

If your docs run on Mintlify, or on a similar platform that generates skills, check the skill it already generates for you, then replace it with a curated one built from your real failure modes, since the benchmark evidence favors focused, expert-written skills over generated or comprehensive ones.

If you have one week, write one skill for the single most common mistake agents make with your product, give it a description that starts with "Use this skill when", run twenty trigger queries and three output evals with and without it, publish it on your domain and GitHub, and submit the plugin bundle. Then measure activation and outcomes, not installs, and prune every quarter.

The broader lesson extends beyond skills. As agents take over implementation, the products that win are the ones whose makers deliver knowledge into the agent's context at the moment of decision, and keep it true. A skill is the cheapest, most portable way to do that today, and the window in which your category's default is still unclaimed will not stay open long.

This guide reflects the Agent Skills ecosystem as of October 26, 2026. Directory policies, client limits, install counts and model prices change frequently, so verify current details in each vendor's documentation before you publish.