Agent Skills

A skill is a packaged operating procedure that an agent can discover and load for a matching task. The shared specification defines a portable core around a directory and SKILL.md; on top of it, each host handles discovery, metadata, activation, tools, and code execution in its own way.

Whether a skill gets used depends on a sentence or two of description. When the agent starts, it puts only each skill's name and description into context; when your request matches a description, it reads the whole SKILL.md; files in references/ open only when that body tells the agent to read them. Take verify-release below: day to day, the only part in context is "Check a release candidate after code is already staged; do not deploy." Ask "check this release candidate for me," and the agent loads its five steps. This layered, on-demand loading is called progressive disclosure, and it means an agent with dozens of skills installed carries only dozens of descriptions by default.

A skill is a convention and content package, not an isolated sandbox or proof that a procedure works.

Package Anatomy

A typical my-skill/ directory contains:

• SKILL.md for the trigger, boundaries, workflow, and checks;
• scripts/ for deterministic mechanics when justified;
• references/ for detailed material loaded on demand;
• assets/ for templates or non-secret examples;
• optional host-specific metadata.

As of October 1, 2026, Claude Code, ChatGPT and Codex, Gemini CLI, Cursor, and GitHub Copilot all document support for the open format, and the differences show up exactly in how they list descriptions, load bodies, and activate skills.

Codex shows the consequence most clearly. By default it caps the initial skill list at 2% of the model's context window, or 8,000 characters when the window is unknown; with many skills installed it shortens descriptions first and may leave some skills out, so a vague description can make a skill undiscoverable. The budget can be changed with skills.max_context_tokens, up to 10,000 tokens; it covers only the initial list, and once Codex picks a skill it still reads the full SKILL.md.

The other hosts differ in activation and extensions. Gemini CLI asks the user to confirm before loading a skill and then adds the skill's directory to the paths the agent may read. Claude Code adds fields of its own on top of the format: disable-model-invocation: true makes a skill manual-only, and context: fork runs it in a subagent. OpenAI reads optional appearance, invocation-policy, and dependency settings from agents/openai.yaml. A skill that relies on one host's extensions is portable only in its core.

Where to Put Your First Skill, and the Limits on Its Name and Description

A host only finds a skill folder that sits where it looks:

Host	Project location	Personal location	Invoke by hand	Turn off automatic loading
Claude Code	.claude/skills/<name>/SKILL.md, searched from the start directory up to the repository root	~/.claude/skills/<name>/SKILL.md	/name	disable-model-invocation: true
Codex	.agents/skills, scanned in every directory from the current one up to the repository root	$HOME/.agents/skills	$name	allow_implicit_invocation: false in agents/openai.yaml
Pi	.agents/skills/, searched from the current directory up to the repository root	~/.agents/skills/	/skill:name	disable-model-invocation: true

Under the specification, the SKILL.md frontmatter has only two required fields:

• name is at most 64 characters of lowercase letters, digits, and hyphens; it cannot start or end with a hyphen, cannot contain --, and must match the folder name.
• description is at most 1,024 characters and says what the skill does and when to use it.
• The optional fields are license, compatibility, metadata, and allowed-tools, the last marked experimental.
• Keep the body under 500 lines and 5,000 tokens; move long reference material into references/.

The specification's skills-ref validate ./my-skill checks the format. Claude Code adds a limit of its own: in the skill listing, description plus when_to_use is cut off at 1,536 characters, so put the key use case first. Its old .claude/commands/ custom commands have also been merged into skills, and a skill wins when both share a name.

What Belongs in a Skill

• a method repeated across sessions or repositories;
• domain rules that materially change safe execution;
• a bounded sequence with inputs, outputs, stop conditions, and checks;
• deterministic scripts safer to reuse than regenerate.

Keep stable authority rules in repository/user instructions. Keep ordinary facts in documentation. When the missing piece is live connectivity rather than procedure, connect a Model Context Protocol (MCP) server or another integration. The two also work together. MCP's official Skills extension (io.modelcontextprotocol/skills, SEP-2640, now Final) lets a server ship skill folders together with the service they describe. Clients discover and read those skills through Resources, and the host can still require user approval before loading one. Host support for the extension is still being rolled out.

Worked Skeleton

---
name: verify-release
description: Check a release candidate after code is already staged; do not deploy.
---

# Verify release

1. Read the repository release policy completely.
2. Confirm the working tree and target version.
3. Run the smallest checks, then the full offline baseline.
4. Record commands, exit states, and skipped live checks.
5. Stop on credentials, destructive migration, or deployment request.

The description includes both trigger and exclusion: the trigger is "code is already staged and a release candidate needs checking," the exclusion is "do not deploy." The body has evidence and stop conditions, not motivational prose.

Testing a Skill

Test more than folder validity:

Test	Question
positive trigger	Does a matching request load the skill?
negative trigger	Does an adjacent task avoid it?
boundary case	Does it stop before unauthorized work?
forward task	Can the agent produce the expected artifact and checks?
stale reference	Does a moved command or API fail visibly?
portability	What changes under another host, model, or tool set?

Retain failed activation examples. Otherwise descriptions become broader over time because only successful demos are observed.

Risks and Trade-offs

• instructions can conflict with higher-priority policy or repository rules;
• scripts and packages may execute with full user authority;
• long skills can consume context and encourage ritual over judgment;
• a description that is too broad loads the skill on unrelated tasks; one that is too narrow misses tasks it should handle;
• host-specific features can make a nominally portable skill non-portable;
• copied skills age, fork, and acquire supply-chain risk.

Inspect third-party skills as code, pin provenance where useful, keep secrets outside the package, and test in an isolated workspace. A skill should reduce repeated reasoning while preserving visible decisions—not become a second application hidden in Markdown.

Follow the reading route