Agent Skill Manifest Specification: Publishing SKILL.md for AI Agent Discovery

TL;DR: A skill is a folder. The folder must contain a SKILL.md with YAML frontmatter (name, description required) plus instructions in Markdown. The folder may bundle scripts, references, and assets that are loaded only when the skill activates (progressive disclosure). To publish skills from a docs site, expose them at a stable URL (commonly /.well-known/skills//SKILL.md) and list them in llms.txt so agents can discover and install them. This spec is authoritative for publisher-side authoring; runtime semantics belong to each agent platform.

Status of this specification

• Origin: Anthropic Agent Skills, announced October 16, 2025; published as an open standard on December 18, 2025 at agentskills.io.
• Adoption: Claude Code, Claude.ai, OpenAI ChatGPT + Codex, Microsoft Agent Framework, GitHub Copilot, Google Gemini CLI, JetBrains, Cursor, Cline, Goose, Windsurf, Snowflake Cortex Agents, and others within 12 weeks of release.
• Layering: This specification covers the manifest (SKILL.md file format) and publishing (how docs sites expose skills). Runtime invocation, sandboxing, and execution semantics are platform-specific and out of scope.
• Compatibility: A skill that conforms to this spec MUST work on any platform that implements the open Agent Skills standard. Platform extensions (e.g. Claude's context forking, Codex's openai.yaml) are additive and MUST NOT break baseline interoperability.

Keywords "MUST", "SHOULD", and "MAY" follow RFC 2119.

1. Folder layout

A skill is a directory. Implementations MUST treat the directory name as the canonical skill identifier when no name is provided.

my-skill/

├── SKILL.md # REQUIRED — manifest + instructions

├── scripts/ # OPTIONAL — executable code referenced from SKILL.md

├── references/ # OPTIONAL — supplementary docs loaded on demand

├── assets/ # OPTIONAL — templates, images, JSON, fixtures

└── ... # Any additional files

• The folder name SHOULD be lowercase, kebab-case, and unique inside its host registry.
• Implementations MAY support nested skills as long as each leaf folder contains its own SKILL.md.
• A skill folder MUST be self-contained: relative paths inside SKILL.md MUST resolve within the folder.

2. SKILL.md file format

SKILL.md is UTF-8 Markdown that opens with a YAML frontmatter block delimited by ---.

2.1 Required frontmatter fields

2.2 Recommended frontmatter fields

Platforms MAY define additional namespaced fields. Vendor-specific fields SHOULD use a vendor prefix, e.g. anthropic.context_fork: true or openai.runtime: hosted. Unknown fields MUST be preserved by tooling.

2.3 Body

The Markdown body is the agent-facing instruction set. It SHOULD use the structure below in order:

1. Purpose — one sentence: when to use this skill.
2. When to invoke — explicit trigger phrases or task patterns.
3. Inputs — what the agent must collect before running.
4. Procedure — numbered steps. Each step references at most one script or reference file.
5. Outputs — what the user sees on success.
6. Failure modes — known errors and recovery hints.
7. References — relative paths to references/*.md for deep context.

Keep the body small (target ≤ 2 KB). Push deep context into references/ so the orchestrator can defer loading until needed.

3. Progressive disclosure tiers

The core architectural pattern is progressive disclosure: agents load only the context they need, when they need it. The spec defines three tiers.

Tier 1 — Discovery metadata

Only name and description from frontmatter are loaded into the orchestrator at registration time. The orchestrator uses them to decide whether the skill is relevant to the current task.

Tier 2 — SKILL.md body

If the orchestrator selects the skill, it reads the full SKILL.md (frontmatter + body). The body MUST be self-contained enough to execute simple skills without further loads.

Tier 3 — Referenced files

When SKILL.md references scripts/ or references/.md, the agent loads them on demand. Implementations MUST NOT preload Tier 3 files at registration; doing so defeats progressive disclosure and inflates token cost.

This tiering is what makes SKILL.md scale: a registry can hold thousands of skills without poisoning every prompt with their full text.

4. Publisher-side rules (publishing SKILL.md from a docs site)

The Agent Skills open standard is silent on transport. The community convention codified by Cloudflare's RFC, Mintlify's autogenerator, and Vercel's skills CLI is:

4.1 Stable discovery path

• Sites SHOULD expose a default skill at /.well-known/skills/default/SKILL.md.
• Additional skills SHOULD live under /.well-known/skills//SKILL.md.
• The same folder MUST serve any referenced scripts/, references/, and assets/ so relative paths resolve.

4.2 Index in llms.txt

List every published skill in your llms.txt so AI agents that discover the site through GEO can install them. Use the convention:

Agent Skills

• default skill: high-level product capabilities
• migration skill: upgrade guides and codemods

This pairing — SKILL.md alongside llms.txt — is the publisher-side analog of the Tier 1 / Tier 2 split.

4.3 Versioning and immutability

• Each release SHOULD bump version in frontmatter (SemVer).
• Public registries (e.g. OpenAI hosted Skills) treat versions as immutable. Publishers MUST NOT rewrite a published SKILL.md for a given version; ship a new version instead.
• Tooling SHOULD expose /skills///SKILL.md for archival fetches.

4.4 Caching and freshness

• Serve SKILL.md and references/* with Cache-Control: max-age=3600 minimum.
• Set Last-Modified and ETag; agents SHOULD revalidate on each task.
• Allow major AI crawler user agents (ChatGPT-User, ClaudeBot, OAI-SearchBot, Google-Extended, PerplexityBot) per your CDN configuration checklist.

5. Authoring rules for high-quality skills

The spec defines structural compliance, but a usable skill also needs authoring discipline:

• Description is the router. Write the description to answer "when should an agent pick this skill?" Avoid marketing copy.
• Single responsibility. One skill = one outcome. Split big workflows into multiple skills with cross-references.
• Cite tools, do not assume. List every tool, MCP server, or external API the skill expects in tools.
• Pin model floors. If your skill relies on long context or vision, set model_min so weaker models don't silently fail.
• Document failure modes. AI agents recover better when SKILL.md tells them how to detect and unwind failures — see agent error handling documentation.
• Prefer references over inlining. Push checklists, schemas, and long examples into references/*.md. Keep SKILL.md short.
• Keep scripts deterministic. Scripts in scripts/ SHOULD exit non-zero on failure and emit machine-readable output where possible.

6. Compatibility matrix (April 2026)

A skill that uses only the open-standard fields (Sections 2.1-2.2) MUST run on every row of this matrix.

7. Validation checklist

Before publishing a skill, verify:

• [ ] Folder name is lowercase kebab-case and unique.
• [ ] SKILL.md exists and parses as Markdown + YAML frontmatter.
• [ ] name and description are present and within length limits.
• [ ] version is SemVer if shipping to a registry.
• [ ] All referenced files in scripts/, references/, assets/ exist.
• [ ] Body ≤ 2 KB; references hold the heavy context.
• [ ] No secrets in SKILL.md or scripts.
• [ ] Linted with vercel skills validate (or equivalent) with zero errors.
• [ ] Published under /.well-known/skills//SKILL.md and listed in llms.txt.
• [ ] Pair-tested on at least Claude Code + Codex CLI to verify cross-agent invocation.

8. Common mistakes

• Treating description as marketing copy. It is the router; write it for the orchestrator, not the human.
• Inlining 30 KB of reference text into SKILL.md. Defeats progressive disclosure; agents will refuse to load it.
• No version field. Public registries reject the publish.
• Hard-coded absolute paths. Skills MUST be portable.
• Skipping tools. Agents silently fail when expected MCP servers or API keys are missing.
• Hand-edits to a published version. Always bump version; never rewrite an immutable release.
• Publishing SKILL.md but blocking AI crawlers at the CDN. Skill files MUST be reachable by ClaudeBot, ChatGPT-User, OAI-SearchBot, etc.

FAQ

Q: What is a SKILL.md file?

A SKILL.md is a Markdown manifest with YAML frontmatter that tells an AI agent how to perform a specific task. It contains required name and description fields plus instructions, and it can reference scripts, additional docs, and assets in the same folder. It is the unit of an Agent Skills package.

Q: Who maintains the Agent Skills spec?

Anthropic published the original Agent Skills standard on December 18, 2025 and hosts the canonical reference at agentskills.io. OpenAI, Microsoft, Google, JetBrains, Cursor, and the broader community now contribute interoperable implementations.

Q: How is SKILL.md different from llms.txt?

llms.txt indexes a site for AI search and citations; SKILL.md packages a reusable agent capability. The two are complementary: list each SKILL.md under /.well-known/skills/ inside your llms.txt so AI agents can discover and install your skills while crawling for context. See the llms.txt generator spec.

Q: Do I need a separate SKILL.md per agent platform?

No — if you use only the open-standard fields, one SKILL.md works on Claude Code, Codex CLI, Gemini CLI, Cursor, GitHub Copilot, and Microsoft Agent Framework. Add platform-specific extensions only when you need them, and namespace them under a vendor prefix.

Q: Can I version skills like an API?

Yes. Set version in frontmatter using SemVer, expose /skills///SKILL.md for archival fetches, and treat published versions as immutable. OpenAI's hosted Skills enforce this contractually; community registries follow the same convention.