Package reference
Head file, frontmatter, paths, limits and serialized package fields
A skill package contains a SKILL.md head and optional supporting text files. The head is parsed for name, description and Markdown body; the remaining files retain their relative paths and content types.
Head contract
| Element | Requirement |
|---|---|
| Head path | Exactly SKILL.md; it must appear among the package files |
| Opening and closing delimiters | YAML frontmatter bounded by --- lines |
| name | Nonempty string, at most 128 characters |
| description | Nonempty string, at most 1024 characters |
| Body | Nonempty Markdown instructions after the frontmatter |
---
name: equipment-review
description: Review a supplied equipment prediction and its dated evidence.
---
# Equipment review
Record the equipment identifier, evidence cutoff and evaluation window.
Distinguish a predicted probability from a confirmed observed failure.
List missing evidence and propose a next check without changing records.Extra YAML fields are not an enforced permission or activation contract. In particular, triggers does not create keyword-based execution and tools does not grant access to connectors. Put usage instructions in the body; configure capabilities and permissions separately.
Supporting files and paths
Files may be organized under references/, scripts/, assets/ or other relative directories. Each file entry needs path, content and contentType. Paths must stay inside the package: absolute paths and .. segments are invalid. Duplicate paths are invalid, and the head must exist. The editor does not allow removing SKILL.md.
Reference supporting files by their package-relative paths. Loading the head does not prove every file was consumed; the task's context must supply or read them. Folder names are organization conventions, not runtime declarations. All supported package contents are text.
Limits
| Value | Limit |
|---|---|
| Text content per file | 256 KiB in UTF-8 bytes |
| Total text content | 1 MiB in UTF-8 bytes |
| Agent creation intent | 1–4000 characters |
| Commit message | 1–500 characters when supplied |
| Branch name | 1–100 lowercase letters/numbers/hyphens |
Serialization
The envelope is version 1, kind asset-package, headPath SKILL.md and a nonempty files array. Each file is {path, content, contentType}. Download the complete equipment example to inspect all fields with actual text.
The name and description are derived from the head. Editing frontmatter changes the saved summary when the version is committed; an editor title is not an independent package identity.
Resource identifiers
Standalone skill IDs are asset UUIDs, version IDs are saved revision UUIDs, and plugin skill IDs are capability UUIDs. A display name or catalog entry ID is not interchangeable with any of those. Historical package views are read-only; edit the current standalone package to create another revision.