skills/

Skills live at skills/<name>/SKILL.md. They are release-owned procedures or reference material loaded on demand, not always-on prompt text. Add a skill when guidance is useful only sometimes. Change a checked-in skill in source and redeploy it; runtime learning cannot overwrite deployed instructions.

A skill is a folder, not just one file: supporting references/, scripts/, schemas/, and assets/ files travel with the SKILL.md byte-for-byte through compilation and deployment. Multi-skill plugins are supported with the same model. See Plugin-Provided Skills below.

There is no defineSkill. The SKILL.md file is the whole contract:

mkdir -p skills/note-taking
$EDITOR skills/note-taking/SKILL.md

Minimal Example

---
description: Capture durable notes for the user
allowed-tools: [record_note]
---

# Note Taking

Use this skill when the user shares a fact, preference, or decision that should
outlive the conversation.

Full Options

Frontmatter is the skill's entire option surface:

The body below the frontmatter is the skill's trusted instructions, loaded at the same trust level as instructions.md only when load_skill retrieves it.

Resource Files

Everything inside a skill folder ships with the agent: Markdown references, runnable scripts, JSON schemas, and binary assets (spreadsheets, images) are packaged byte-for-byte into the build artifact and exposed at runtime under the authored paths. A SKILL.md can therefore reference its companions with relative paths (references/checklist.md, or ../../shared/util.py inside a bundle) and they resolve exactly as authored.

Resources are trusted, read-only context at runtime:

• load_skill returns a compact inventory of the skill's available files (paths, sizes, content types), which is a map rather than the contents.
• read, list, and grep lazily hydrate any resource on demand; nothing is bulk-injected into the model prompt.
• Loading a skill materializes its full resource tree onto the active sandbox. If the sandbox is acquired later, the runtime materializes every previously loaded skill during that first acquisition so scripts and relative paths work.
• Scripts are files the agent may choose to execute through its normal sandbox and tool policy; they are never auto-executed.
• Checked-in SKILL.md and companion resources are read-only at runtime. Edits are ignored at sync time and reported as skill.resource_write_ignored; ship a new deployment to change them.

Plugin-Provided Skills

A conforming local or published Agent Plugin can ship reusable skills using the Agent Plugins v1 layout:

plugins/corporate-finance/
├── plugin.json
├── references/                 # shared across all bundle skills
├── schemas/
├── scripts/
├── shared/
└── skills/
    ├── dcf-model-builder/SKILL.md
    ├── cim-builder/SKILL.md
    └── ...

Each plugin skills/<name>/SKILL.md is a normal skill. A checked-in plugin is active by presence; a published plugin must be selected in agent.md and pinned in plugins.lock. Every entrypoint is added to the containing surface's compact skill index without separate registration. The body remains out of prompt context until the model calls load_skill.

Loading one plugin skill exposes that skill's folder plus the plugin's shared resources (references/, schemas/, scripts/, shared/, metadata, assets). Sibling skills' folders stay unavailable until those skills are loaded themselves, preserving the per-surface and per-loaded-skill boundary.

Limits and Validation

The compiler validates every skill plugin:

• Duplicate contributed skill names across bundles fail compilation.
• Symlinks and paths escaping the bundle fail compilation.
• Junk (.DS_Store, .git/, __pycache__/, caches, build output) is excluded from packaging.
• Per-plugin limits: 2,000 files / 64 MB.
• Resource hashes feed the agent revision, so changing any supporting file produces a new revision.

How Skills Load

The compiler automatically selects every compact skill entry in the current surface. The default-enabled load_skill tool lets the model retrieve a local skill's full body on demand, along with its canonical SKILL.md path, bundle identity, and resource inventory. load_skill cannot load an unselected skill and never widens the snapshot's tool set.

A child agent sees only its own skills/, not its parent's. Skill names and bundle ids are unique across the artifact so their canonical runtime paths stay unambiguous, while bodies and companion resources remain lazy.

The selected skill is projected into the sandbox when loaded or, if no sandbox exists yet, when the run first acquires one. It uses its canonical path (/skills/<name>/SKILL.md, or /skills/<plugin>/skills/<name>/SKILL.md for plugin skills) together with its read-only resource closure.

Self-Improvement

Self-improvement reviews completed runs and saves reusable learning to durable memory or skills. agent.md declares whether skill changes are autonomous, approval-gated, or disabled:

mutability:
  skills: autonomous
  automations: disabled
  externalAccess: disabled

The reviewer sees bounded evidence and receives only memory and skill tools. With skills: autonomous it may create new durable skills directly. Approval-gated changes are stored separately from the active skill. Each durable skill mutation appends a full-body revision; archive replaces permanent deletion, and rollback copies an older body into a new revision. A durable skill cannot use the name of a checked-in skill. Use skills: disabled, or the mutability: static shorthand, to disable runtime-authored skills entirely.

Every durable skill write must contain YAML frontmatter delimited by --- and a non-empty instruction body. The runtime rejects malformed reviewer, agent, and user writes before they enter the live catalog, so a bad learned skill cannot break later sandbox synchronization.

Accepted skill and memory changes are also mirrored into a runtime-owned Git repository at <artifactRoot>/evolution. This is an audit projection, not the live skill or memory store: Git failure never rolls back an accepted change, and the model is not given the repository path or Git tools. Pending skill changes enter the history only after approval. See Evolution History for the layout and inspection commands.

Every runtime surface owns its durable skill catalog. Skills learned by subagents/legal are available on later legal runs but remain invisible to the root agent, siblings, and nested children. A subagent declares mutability in its own agent.md. Plugin-authored tools do not need a custom learning tool; the normal runtime learning API is scoped to the current run.

Conventions

• Keep skills focused on repeatable procedures.
• Put durable product data in memory or state, not in skill bodies.
• Prefer a short description that helps the model choose the skill.
• Keep allowed-tools aligned with the tools the procedure actually needs.

Related Docs

• MD-First Agents: Plugins and Skills
• Customization: Mutability
• Tools
• MD-First Agents