AIP-3: SKILL (skill/v1): skill manifest format

A markdown + frontmatter format for distributing reusable agent skills as portable, version-controlled files.

FieldValue
AIP3
TitleSKILL (skill/v1): skill manifest format
StatusFinal
TypeSchema
Domainskills.sh
RequiresAIP-1, AIP-2
Spec authorAnthropic (anthropics/skills) — open-sourced Dec 2025
AIP editorJeremy André
Reference ImplSKILL.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/skills in 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.json and Cargo.toml as 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 of typescript, javascript, python, or shell; runtimes MAY refuse languages they do not support.
  • code: exactly one of { file } or { inline }. file is a relative path to the entry file, which SHOULD live under scripts/; path traversal with .. segments escaping the skill dir MUST be rejected. inline is 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), timeout in milliseconds (runtimes MUST enforce), and memory (e.g. 512MB).
  • artifacts: required patterns, 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.json and Cargo.toml as portable manifests.
  • YAML frontmatter over TOML. The frontmatter is delimited by --- lines and parsed as YAML 1.2, which the draft folder's ADAPTER.md holds 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 runtime field. Host targeting is expressed with the top-level compatibility field (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 in allowed-tools and 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 execution binding under metadata.aip3, gated behind variant: 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 under metadata.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-tools is 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, inline code MUST be sandboxed before executing, and execution.code.file paths that escape the skill directory with .. segments MUST be rejected. Runtimes must enforce execution.runtime.timeout.
  • Extension keys under metadata. Hosts MUST tolerate unknown metadata.<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 →