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; hosts may differ in discovery, metadata, activation, tools, and code execution.

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.

Progressive disclosure reduces default context: metadata supports discovery, SKILL.md explains the route, and supporting files load only when needed. Hosts do not necessarily implement each stage identically.

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. Use MCP or another integration when the missing piece is live connectivity rather than procedure.

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 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;
• shallow descriptions cause false positives; narrow ones cause missed activation;
• 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 · Opened notes are remembered in this browser.