AIP-3: SKILL (skill/v1): skill manifest format
A markdown + frontmatter format for distributing reusable agent skills as portable, version-controlled files.
| Field | Value |
|---|---|
| AIP | 3 |
| Title | SKILL (skill/v1): skill manifest format |
| Status | Final |
| Type | Schema |
| Domain | skills.sh |
| Requires | AIP-1, AIP-2 |
| Spec author | Anthropic (anthropics/skills) — open-sourced Dec 2025 |
| AIP editor | Jeremy André |
| Reference Impl | SKILL.md doctype spec |
Abstract
SKILL.md is a markdown-with-frontmatter file format that packages a single
reusable agent skill — its metadata, instructions, optional tool bindings,
and example invocations — into a portable, version-controlled artifact.
Skills are first-class citizens of an agent's repertoire; SKILL.md makes
them shareable across runtimes.
Motivation
Skills today are scattered across vendor-specific JSON, framework-specific class hierarchies, and ad-hoc prompt files. A skill defined for one runtime rarely runs in another without rewriting. SKILL.md gives a single declarative file a developer can hand to any AIP-compliant runtime and have the skill loaded, indexed, and invocable.
The format draws on:
- Anthropic's Agent Skills
(markdown-as-skill, frontmatter for metadata) — open-sourced at
anthropics/skillsin Dec 2025 and adopted by OpenAI Codex; AIP-3 is aligned with, not a fork of, this format. See related standards for scope split. - The success of
package.jsonandCargo.tomlas portable manifests - AIP-4 (DESIGN.md) and AIP-5 (CANVAKIT.md) as sibling Schema specs in the same family
Specification
A SKILL.md manifest is a markdown file whose YAML frontmatter (delimited by
--- lines) carries the manifest fields and whose markdown body carries the
instruction prose. The frontmatter MUST validate against
SKILL.schema.json. AIP-3 is a profile of
agentskills.io: the top-level fields mirror the
upstream specification (name, description, license, compatibility,
allowed-tools, metadata), and the AIP-specific extensions live under
metadata.aip3.* so an AIP-3 skill remains a valid agentskills.io skill in any
conformant runtime.
Two properties are required:
---
name: <kebab-case-skill-id> # 1-64 chars, lower alphanumerics and
# hyphens, no leading/trailing/consecutive
# hyphens; MUST equal the parent
# directory name
description: <one-paragraph purpose> # 1-1024 chars, written for the LLM
# caller: what the skill does and when
# to use it
metadata:
aip3: {} # see below
---
# Body
The body is markdown. Headings, code blocks, and prose are all consumed by
the runtime as instructions. Sections that read as data (e.g. "## Tool
catalog") are conventionally extracted; sections that read as guidance
("## When to use this skill") are passed through verbatim.Top-level fields
name (required). Machine identifier, 1 to 64 characters, lowercase alphanumeric and hyphens only, with no leading, trailing, or consecutive hyphens. MUST equal the parent directory name. Inherited verbatim from agentskills.io.
description (required). One-paragraph purpose, written for the LLM caller. SHOULD describe both what the skill does and when to use it. 1 to 1024 characters. Inherited from agentskills.io.
license (optional). License identifier, e.g. an SPDX identifier such as
MIT or Apache-2.0, or a pointer to a bundled license file such as
LICENSE.txt has complete terms. At most 200 characters. Inherited from
agentskills.io.
compatibility (optional). Free-form environment requirements, 1 to 500 characters: intended product, required system packages, network access, and so on. Most skills omit this. Inherited from agentskills.io.
allowed-tools (optional). Space-separated list of pre-approved tool
patterns, e.g. Bash(git:*) Bash(jq:*) Read. Experimental upstream; runtimes
MAY ignore it. The field is a request, not a grant: runtimes apply policy
mediation before honoring it. Inherited from agentskills.io.
metadata (optional). Free-form key-value mapping. Hosts and standards stash
extension fields under namespaced keys, e.g. metadata.aip3.* or
metadata.acme.*. Inherited from agentskills.io.
metadata.aip3 extensions
The Aip3Extensions object of SKILL.schema.json
carries the AIP-3 fields. Runtimes that do not implement AIP-3 MUST preserve
this object verbatim, since it lives inside agentskills.io's metadata.
schema. The dispatch tag. Required for AIP-3 conformance and pinned to
skill/v1 for this spec version. skills/v1 is accepted as a legacy alias
(AIP-70).
variant. One of instruction (prose-only, the default), executable
(bundles runnable code via execution), or composite (references other
skills via uses).
version. Semver, bump on breaking changes to the skill's behavior or required tools.
tags. Up to 12 catalog tags; lowercase kebab-case with no leading symbols. Three to six tags is typical.
category. Coarse grouping such as productivity, creative, or
development. Free-form; runtimes SHOULD NOT enumerate the values. 1 to 64
characters.
requires. Other AIPs the skill depends on, as an array of AIP numbers,
e.g. [9] for the operator runtime. Runtimes MAY warn when a declared
dependency is unsupported.
author. Optional, at most 200 characters. Conventional shape: a
Name <email> pair or a stable handle. It mirrors the agentskills.io
metadata.author convention; when both are present, metadata.aip3.author
wins for AIP-3 runtimes.
title. Optional human-readable display title, 1 to 120 characters. Headless runtimes that cannot render the body H1 MAY use this; the body H1 is preferred.
uses. Skill names this skill composes with, each validated like name.
Required and non-empty when variant is composite.
execution. Executable bindings, required when variant is executable,
with code and language required inside it:
language: one oftypescript,javascript,python, orshell; runtimes MAY refuse languages they do not support.code: exactly one of{ file }or{ inline }.fileis a relative path to the entry file, which SHOULD live underscripts/; path traversal with..segments escaping the skill dir MUST be rejected.inlineis source code that runtimes MUST sandbox before executing.entrypoint: optional function name within the entry file.runtime: optional execution hints:provider(e.g.modal,daytona,vercel-sandbox,local),timeoutin milliseconds (runtimes MUST enforce), andmemory(e.g.512MB).artifacts: requiredpatterns, one or more glob patterns of output files the runtime should capture.dependencies: a package to version map, lockfile-style.
---
name: pdf-report
description: >-
Turns a CSV of sales data into a formatted PDF report; use when the user
asks for a shareable summary of raw numbers.
allowed-tools: Bash(python:*) Read
metadata:
aip3:
schema: skill/v1
variant: composite
version: 1.2.0
title: PDF report builder
tags: [reporting, pdf, sales]
category: productivity
requires: [9]
author: Jane Doe <[email protected]>
uses: [csv-clean]
---The full reference patterns live in the EXAMPLES.md
companion of the draft folder, and the authoring skill
(skills/author-skill/SKILL.md) in the
same folder exercises this schema on itself.
Rationale
The decisions behind the format, in the order the schema presents them:
- Markdown over JSON Schema for the manifest. The payload of a skill is
prose written for the agent, and prose reads best in markdown. A JSON-only
format would force authors to escape their instructions into strings; here
the instructions are the body and the fields are the frontmatter, which is
also why the format draws on
package.jsonandCargo.tomlas portable manifests. - YAML frontmatter over TOML. The frontmatter is delimited by
---lines and parsed as YAML 1.2, which the draft folder'sADAPTER.mdholds normative for hosts (a real YAML parser, never home-rolled). YAML keeps single-field manifests almost free and matches how agentskills.io declines the same shape. - No separate
runtimefield. Host targeting is expressed with the top-levelcompatibilityfield (free-form environment requirements) rather than a structured runtime field; there is no capability negotiation to compute against, so a free-form field matches reality. A skill whose needs are tool-shaped declares them inallowed-toolsand runtimes apply policy mediation there. - No embedded code in the core. A skill declares what it needs; runtimes
provide it. Code appears only through the optional
executionbinding undermetadata.aip3, gated behindvariant: executable, because bundling code is the exception, not the baseline. The baseline skill is the markdown body itself. - Extensions under
metadata. The AIP-3 fields live undermetadata.aip3.*so a skill authored against AIP-3 stays a valid agentskills.io skill anywhere; runtimes that do not know AIP-3 preserve the object verbatim.
Reference Implementation
packages/skill:
parser, file-tree source, DB-backed source, and library tooling. The
implementation is the source of truth for the schema during the Draft
phase.
Backwards Compatibility
Not applicable — this AIP introduces a new spec.
Since 2026-10-23 (AIP-70) the canonical schema id is skill/v1; documents that declare skills/v1 remain valid, and hosts MUST accept both.
Security Considerations
The threat surface of the format, and what the schema already does about it:
- Untrusted skills in a trusted runtime. A skill's body is instruction text
injected verbatim into the agent, so a hostile body can carry prompt
injection. Hosts register skills through controlled surfaces (the install
scopes of the draft
ADAPTER.md) and treat the body as instructions to gate, not as host commands. allowed-toolsis a request, not a grant. The field only names tool patterns the skill would like pre-approved; runtimes MAY ignore it and MUST apply policy mediation before honoring it. (Capability gating across AIP policies is the runtime's job, per the draft ADAPTER.md.)- Executable skills run code. With
variant: executable,inlinecode MUST be sandboxed before executing, andexecution.code.filepaths that escape the skill directory with..segments MUST be rejected. Runtimes must enforceexecution.runtime.timeout. - Extension keys under
metadata. Hosts MUST tolerate unknownmetadata.<host>.*keys but give them no semantics, so a skill cannot lend itself authority by carrying a host's namespaced keys. - Skill inputs are a runtime concern. The manifest describes no input shape; where a host needs one it collects it through the host's own policy and validation, keeping the format free of code or credentials.
Mitigations live in runtime policy, not the file format itself. Nothing in
this format grants authority: every field is descriptive, and the only
executed thing (execution, for variant: executable) is optional and
sandbox-gated.
Resources
Supporting artifacts for AIP-3. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-2: TEMPLATE: the template every new AIP starts from
The template every new AIP starts from. Copy this file, change the frontmatter, and fill in the sections.
AIP-4: DESIGN (design/v1): design token format & registry conventions
A markdown + frontmatter format for portable design tokens, and the registry conventions used by designkit.sh to share community kits.