Write Once, Run Everywhere: Building Agent Skills (SKILL.md) That Work in Claude, Cursor, Copilot and Codex

An Agent Skill is a folder with a SKILL.md file at its root: a Markdown document with YAML frontmatter that tells any compatible coding agent what the skill does, when to use it, and how to run it. The reason it matters in 2026 is that SKILL.md has become a shared open format, so the same skill folder loads in Claude Code, GitHub Copilot, Cursor, OpenCode, Codex, and Kiro without rewriting it per tool. In this post I walk through how I author one portable skill with progressive disclosure, show a real reusable skill I ship to clients, and explain why I stopped rebuilding the same workflow three times for three different agents.

What is a SKILL.md Agent Skill, exactly?

A SKILL.md skill is a self-contained folder that packages instructions, optional scripts, and reference files so an agent can load a procedure on demand instead of you re-explaining it every session. Think of it as a function the agent can call in plain language, except the "function body" is Markdown plus whatever files you bundle next to it.

The minimum is one file. A skill named pr-review lives at pr-review/SKILL.md, and that file has two parts: YAML frontmatter and a Markdown body.

---
name: changelog-entry
description: >
  Generate a changelog entry from staged git changes following
  Keep a Changelog format. Use when the user asks to update the
  changelog, write release notes, or document changes for a release.
---

## Changelog Entry

When the user wants a changelog entry:

1. Run `git diff --staged --stat` to see what changed.
2. Group changes into Added, Changed, Fixed, Removed.
3. Write entries in past tense, user-facing language, one line each.
4. Insert them under the `## [Unreleased]` heading in CHANGELOG.md.

Skip internal refactors that have no user-visible effect.

That is a complete, working skill. The agent reads the description, decides whether the current request matches, and if it does, pulls the body into context and follows it. Everything else in this post is about making that loading smart instead of dumping everything at once.

How does progressive disclosure actually work in a skill?

Progressive disclosure means the agent only loads what it needs, in three stages: discovery, activation, and execution. This is the single most important idea in skill authoring, because context windows are finite and a skill that front-loads 4,000 tokens of instructions will get ignored or will crowd out the actual task.

Here is how the three stages map to what lives where:

For the full tone rules, read `reference/voice-guide.md` before drafting.
Run `scripts/validate.py` against the output and fix any errors it reports.

release-notes/
  SKILL.md
  reference/
    voice-guide.md
  scripts/
    fetch-merged-prs.sh

---
name: release-notes
description: >
  Draft customer-facing release notes from merged GitHub PRs since the
  last tag. Use when asked to write release notes, prep a release
  announcement, or summarize what shipped this sprint.
---

## Release Notes

## Steps

1. Run `scripts/fetch-merged-prs.sh` to list PRs merged since the last
   git tag. It prints title, number, and labels as TSV.
2. Drop PRs labeled `internal`, `chore`, or `dependencies`.
3. Group the rest under: New, Improved, Fixed.
4. Read `reference/voice-guide.md` and rewrite each line in that voice.
5. Output Markdown only. No preamble. Lead with the single biggest
   user-visible change.

## Rules

- One sentence per item. Active voice. Name the user benefit, not the
  code change.
- If a PR has no user-visible effect, leave it out even if it is large.
- Never invent a feature that is not backed by a PR in the list.

#!/usr/bin/env bash
set -euo pipefail
last_tag=$(git describe --tags --abbrev=0)
gh pr list --state merged --search "merged:>$(git log -1 --format=%cs "$last_tag")" \
  --json number,title,labels \
  --template '{{range .}}{{.number}}\t{{.title}}\t{{range .labels}}{{.name}} {{end}}{{"\n"}}{{end}}'

My rule: write to the lowest common denominator. Put all trigger logic in the description as plain phrases, reference scripts by relative path, and never depend on a frontmatter key that only one tool reads. If a tool needs a vendor-specific field, I add it as an extra key the others will ignore, rather than restructuring the skill.

The one real portability risk is scripts. A skill that shells out to gh or python assumes that runtime exists wherever the skill runs. I keep scripts dependency-light and document the requirement in the body so the agent can degrade gracefully if a tool is missing.

Why is the open SKILL.md standard better than per-tool config?

Because you author the workflow once and it follows the developer instead of the tool. Before this format settled, the same "write release notes our way" workflow meant a Claude project instruction, a Cursor rule file, and a Copilot custom instruction, three copies that drifted out of sync the moment one changed. A single SKILL.md collapses that into one source of truth.

Three concrete payoffs I see in client work:

• Versioning. A skill is a folder. It goes in git, gets reviewed in a PR, and ships with the repo. Per-tool config usually lives in scattered settings that no one reviews.


• Onboarding. A new hire clones the repo and inherits every team skill automatically. There is no "and now configure your editor" step.


• No vendor lock. If a team moves from one agent to another, the skills come along. I have migrated clients between tools without rewriting a single skill body.

How do I test a skill so it fires when I want it to?

Test the description first, because a skill that never activates is worse than no skill. The fastest check is to open a fresh session and phrase a request the way a real user would, then see if the agent picks the skill up without you naming it.

My checklist before I hand a skill to a client:

1. Trigger test. Ask for the task in three different phrasings. If it only fires when I say the skill name, the description is too narrow. Add the phrasings that failed.


2. Anti-trigger test. Ask for something adjacent but wrong. If a release-notes skill fires when I ask for a commit message, the description is too greedy. Tighten it.


3. Cold execution. Run the skill in a session with no prior context. The body must stand alone, since the agent has no memory of how I built it. This is the same constraint a sibling agent faces, which is why I write bodies as if explaining to someone who just walked in.


4. Missing-runtime test. Run it where the bundled script's runtime is absent and confirm the body tells the agent what to do instead of failing silently.

If you want to render skill output inside a chat UI rather than just dropping Markdown, that overlaps with shipping an MCP app with interactive UI ↗, which is the path I take when a client wants the result to look like a product feature instead of a transcript.

What is the fastest way to start?

Make a folder, add one SKILL.md with a sharp description and a five-step body, and test it in a real session before adding anything else. Resist the urge to bundle scripts and reference files on day one. Most of my skills started as a single file and only grew a reference/ folder once the body got long enough to hurt activation.

The progression I recommend:

1. One file, plain body, sharp description.


2. Move long reference material to a sibling file the body reads on demand.


3. Add a script only when the agent is doing repetitive deterministic work better handled by code.


4. Commit the folder to the repo so the whole team and every tool inherits it.

The short version: author to the portable subset, lean on progressive disclosure so activation stays cheap, and keep taste in reference files and logic in the body. Do that and one skill folder serves every agent your clients will ever use.