General-purpose agents can already read files, run commands, call tools, and operate across a full development environment. The hard part is not giving the model one more tool. The hard part is giving it the right procedural knowledge at the right time without filling every turn with manuals, style guides, examples, and policy text. Agent Skills solve that context-engineering problem by packaging reusable expertise as small folders that an agent can discover cheaply and load only when the current task calls for them.
A skill is usually a directory with a required SKILL.md file, YAML frontmatter, task instructions, and optional supporting assets such as scripts, templates, examples, or reference documents. At startup, the agent only needs a compact listing of skill names and descriptions. If the current task matches one of those descriptions, the harness or the model reads the full SKILL.md. If the skill points to deeper files or executable helpers, the agent can fetch or run those later. This staged loading is the core mechanism: progressive disclosure for agent context.
The technique is transferable beyond one vendor. It is useful whenever a team repeatedly pastes the same playbook into an agent, maintains long project instruction files, or wants portable task expertise that works across coding agents and automation harnesses. Compared with a tool protocol, a skill is not primarily an API surface. It is a versioned context package: a discoverable bundle of when-to-use metadata, operational procedure, examples, and deterministic helpers.
The frontmatter is the skill’s routing layer. A concise name and a specific description tell the agent when the skill might apply. This metadata is intentionally small because it may be present in every session. A vague description like “helps with documents” causes false positives and misses. A better description names the workflow, input shape, output shape, and boundaries.
Progressive disclosure separates skill awareness from skill content. The agent first sees a compact catalog. It then loads the main instruction file only when needed. It can then load supporting files only when the main instructions identify a relevant branch. This keeps many capabilities available without paying the token cost of every detailed guide in every prompt.
Skills can include scripts for operations that are cheaper, safer, or more reliable as code than as generated text. A script can inspect a file, validate an output, convert formats, lint a generated artifact, or compute a deterministic result. The agent does not need to paste the script body into context; it can invoke the helper and consume the result.
A skill is most valuable when it defines an activation boundary. The description answers “should this load?” The main instructions answer “what procedure should the agent follow?” Supporting files and scripts answer “what deeper material or deterministic operation is needed now?”
The entry point is a SKILL.md file with frontmatter followed by instructions. The frontmatter should be optimized for routing, while the body should be optimized for execution. Put the most important activation clues early, then write the procedure as concrete steps the agent can follow without guessing.
---
name: api-migration-review
description: Review API migration plans for backward compatibility, versioning, rollout safety, and client impact. Use when changing REST or GraphQL contracts.
---
# API Migration Review
When reviewing an API migration:
1. Identify removed fields, renamed fields, status-code changes, and auth changes.
2. Compare the old and new schemas before approving implementation.
3. Require a rollout plan for clients that cannot upgrade immediately.
4. Produce a compatibility table with risk level and mitigation.A mature skill should not put every edge case in the main file. Keep the default path lean and reference deeper files by purpose. The main file can say when to read each companion document, letting the agent pull only the branch needed for the current task.
api-migration-review/
SKILL.md
references/
rest-compatibility.md
graphql-deprecation.md
rollout-checklist.md
scripts/
diff-openapi.py
validate-changelog.pyWhen a step can be checked mechanically, package it as a helper. The agent remains responsible for judgment, but it can rely on code for parsing, comparison, validation, and transformation. This improves repeatability and reduces context load because large inputs can stay on disk while the helper returns a targeted summary.
#!/usr/bin/env python3
import json
import sys
old_path, new_path = sys.argv[1], sys.argv[2]
old = json.load(open(old_path))
new = json.load(open(new_path))
removed = []
for path, methods in old.get("paths", {}).items():
if path not in new.get("paths", {}):
removed.append({"path": path, "method": "*"})
continue
for method in methods:
if method not in new["paths"][path]:
removed.append({"path": path, "method": method})
print(json.dumps({"removed_operations": removed}, indent=2))File-format work often combines procedural rules with deterministic helpers. A spreadsheet skill can explain workbook conventions, include templates, and provide scripts that inspect formulas or validate sheet names. A PDF skill can describe form-filling procedure while delegating field extraction to a bundled parser. The agent gets both domain guidance and reliable file operations.
Teams can convert repeated engineering procedures into skills: release review, database migration review, frontend accessibility checks, incident postmortem drafting, dependency upgrade safety, or security triage. The skill captures the checklist, points to canonical repository files, and can include verification commands. This is more maintainable than pasting a long checklist into every session.
Because the package is mostly Markdown plus ordinary files, the pattern can move across compatible agent clients. A team can version a skill with the codebase, distribute it through an internal template, or publish it as part of a plugin. The same procedural knowledge can then be reused in local coding tools, hosted agent runtimes, and API-driven automation.
The description should include both positive and negative activation boundaries. Tell the agent what the skill does, when to use it, and when not to use it. This reduces accidental activation when several skills sit near the same domain.
---
name: changelog-entry
description: Draft a customer-facing changelog entry from merged product changes. Use for release communication. Do not use for internal incident reports, migration plans, or commit summaries.
---A good SKILL.md is not a knowledge dump. It is an operating procedure with pointers. Put the default path, required checks, output contract, and supporting-file map in the main file. Move long examples, policy details, and domain references into separate files with clear names.
# Supporting Material
Read these only when needed:
- references/tone-guide.md when drafting external prose.
- references/security-language.md when the change mentions auth, encryption, or customer data.
- templates/changelog.md when producing the final entry.Skills should be tested on representative tasks. Track whether the agent activates the skill when it should, ignores it when it should, reads the right supporting files, runs helpers correctly, and produces the expected output. Improve the description first when routing fails. Improve the body when the skill loads but the procedure is weak.