AIP-3: SKILL.md — skill manifest format

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" pattern (markdown-as-skill, frontmatter for metadata)
• 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

Status note. The reference implementation in packages/skills/ (v1.0.0) defines the working schema. The canonical normative specification is being authored from that implementation. This section will be filled in as part of moving AIP-3 from Draft → Review.

The high-level shape, pending the full normative text:

---
schema: skills/v1
name: <kebab-case-skill-id>
title: <human-readable title>
description: <one-sentence what-it-does>
version: <semver>
tags: [<topic>, <topic>]
inputs:
  - name: <param>
    type: string | number | boolean | object
    required: true
    description: <prose>
tools:
  - <tool-name>           # optional — tools this skill expects to be available
examples:
  - input: { ... }
    output: <expected output sketch>
---

# Body — instruction prose for the agent

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.

Rationale

To be authored. Key decisions to defend in this section: why markdown over JSON Schema, why YAML frontmatter over TOML, why no separate runtime field (use tags + capability negotiation instead), why no embedded code (skills declare what they need, runtimes provide it).

Reference Implementation

packages/skills — 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.

Security Considerations

To be authored. Threat surface includes: untrusted skills loaded into a trusted runtime, skill bodies that perform prompt injection on the host agent, frontmatter tools declaring tools the runtime should not expose. Mitigations live in runtime policy, not the file format itself.