A year ago, customizing an AI agent meant rewriting the same prompt over and over, once for each tool you used. Today there's a shared format — Agent Skills — that lets you write a workflow once and run it in Claude Code, Codex, Gemini CLI, Copilot, and more. This post is a practical guide to what skills are, how to use them, and where to find the good ones.
\nI’ve written before about Claude Code skills, but skills have since outgrown any single tool. The format Anthropic released as an open standard has been adopted across the ecosystem, and a whole layer of registries and tooling has grown up around it. If you’ve been treating skills as a Claude-only feature, this is the post that reframes them as something portable, shareable, and worth investing in regardless of which agent you reach for.
\nStrip away the marketing and a skill is almost disappointingly simple: it’s a folder containing a single SKILL.md file. That file has a small block of YAML frontmatter — at minimum a name and a description — followed by plain-English instructions telling the agent how to perform a task. That’s the whole core of the standard.
---\nname: changelog\ndescription: Generate a changelog entry from staged git changes.\n Use when the user asks to write a changelog or release note.\n---\n\n## Writing a changelog entry\n\n1. Run `git diff --staged` to see what changed.\n2. Group changes under Added, Changed, Fixed, Removed.\n3. Write each entry in past tense, user-facing language.\n4. Skip internal refactors that don't affect behavior.\n5. Prepend the entry to `CHANGELOG.md` under an `## [Unreleased]` heading.That’s a real, working skill. There’s no SDK, no compilation step, no API to register against. The agent reads the description, decides the skill is relevant, loads the instructions, and follows them. A skill is procedural knowledge written down in a format an agent knows how to find and read.
\nThe frontmatter is the contract. The name is the slug you’d type to invoke it. The description is the single most important line you’ll write, because it’s the only thing the agent sees until the skill is actually needed. More on that in a moment.
A skill folder can hold more than just SKILL.md. You can bundle:
my-skill/\n├── SKILL.md # metadata + instructions (always read)\n├── reference.md # loaded only when SKILL.md links to it\n├── template.tsx # a scaffold the agent copies\n└── validate.py # a script the agent can executeThis bundling is what separates a skill from a saved prompt. A prompt is text; a skill is text plus the resources and executable steps needed to actually carry the work out.
\nThe clever part of the design is how skills are loaded. At startup, the agent reads only the name and description of every installed skill — roughly a hundred tokens each. The full instructions, the reference files, the scripts: none of that enters the context window until a task actually matches the skill’s description.
\nThis is called progressive disclosure, and it’s the reason you can have fifty skills installed without drowning your agent in irrelevant context. Each skill costs almost nothing until it’s needed, then expands to full detail on demand. It’s the difference between handing someone an entire library versus handing them a card catalog and letting them pull the one book they need.
\nThe practical consequence: write descriptions that are precise about when a skill applies, not just what it does. A vague description like “helps with testing” forces the agent to guess. A sharp one — “Use when the user asks to write or fix a Vitest unit test, or when a test file is open and failing” — gives it a clear trigger. The description is doing matching work, not marketing work.
\nThe Agent Skills format was developed by Anthropic and released as an open standard. The specification lives at agentskills.io and is open to contributions from the wider ecosystem. The significance isn’t the spec document itself — it’s who adopted it.
\nAs of mid-2026, the same SKILL.md folder works across a growing list of tools:
| Tool | \nVendor | \nSkill support | \n
|---|---|---|
| Claude Code | \nAnthropic | \nNative | \n
| Codex CLI | \nOpenAI | \nNative | \n
| Gemini CLI | \nNative | \n|
| GitHub Copilot | \nMicrosoft | \nVia VS Code agent skills | \n
| Cursor | \nAnysphere | \nManual placement | \n
| Cline / Windsurf / OpenCode | \nCommunity | \nSupported | \n
Write a skill once and it follows you across all of them. If your team standardizes on a deployment checklist as a skill, that checklist works whether a given engineer prefers Claude Code in the terminal or Copilot in VS Code. The investment compounds because it isn’t locked to a vendor.
\nThis is a genuine shift. Most AI tooling so far has been proprietary and non-transferable — your ChatGPT custom instructions don’t move to another assistant. Skills break that pattern by being a plain-text, version-controllable, tool-agnostic format. They behave like source code, because effectively they are.
\nThere are three things you’ll do with skills: install them, invoke them, and write your own.
\nSkills live in conventional locations the agent scans automatically. The exact paths vary slightly by tool, but the Claude Code convention is representative:
\n| Scope | \nPath | \nApplies to | \n
|---|---|---|
| Personal | \n~/.claude/skills/<name>/SKILL.md | \nAll your projects | \n
| Project | \n.claude/skills/<name>/SKILL.md | \nOne repository | \n
Personal skills are for habits that follow you everywhere — your commit message style, your preferred way of explaining code. Project skills encode team conventions and get committed to version control, so every contributor and every fresh checkout inherits the same playbook. When a new engineer clones the repo, the skills come with it.
\nInstalling a skill is, at its simplest, dropping a folder in the right place. That’s also why distribution matters — and why registries exist.
\nSkills run two ways:
\n/changelog). You’re telling the agent exactly which playbook to follow.The automatic path is where skills feel magical — you ask for a changelog in plain language and the agent quietly pulls in your changelog skill without being told. The explicit path is your override for when you want a specific behavior guaranteed.
For skills with side effects — deploying, deleting, sending messages — you generally want to disable automatic invocation so they only ever run when you type the command. In Claude Code that’s a frontmatter flag:
\n---\nname: deploy\ndescription: Deploys the app to production.\ndisable-model-invocation: true\n---This is a safety boundary worth respecting: read-only skills can be automatic; anything destructive should be explicit-only.
\nThe best first skill is a workflow you’ve explained to an agent more than twice. Open a folder, write a SKILL.md, and keep it tight:
SKILL.md short — under a few hundred lines. Push detailed reference material into separate files the instructions link to, so it loads only when needed.The mindset shift: you’re not prompt-engineering, you’re writing documentation for a colleague who happens to read fast and never remembers between sessions.
\nOnce skills became portable packages, the natural next step was an npm-style registry — somewhere to publish, discover, and install them. That layer arrived fast. The ecosystem went from a single registry in late 2025 to a handful of major marketplaces by Q2 2026.
\nThe most visible is skills.sh, billed as “The Agent Skills Directory.” It works like a package registry crossed with a leaderboard. Every skill page shows an install count, which platforms it’s compatible with, and a one-line install command. There are rankings by all-time installs, by 24-hour trending, and by what’s “hot” right now. It has tracked tens of thousands of unique skills, which gives the trending lists real signal rather than being a static list.
\nTreating skills like packages and the directory like a registry is what makes sharing scale. Instead of emailing a folder around, you publish once and anyone can install with a command. Teams can standardize on a published skill and get updates the same way they’d update a dependency.
\nA few directories worth knowing, beyond skills.sh:
\nOne honest caveat: a registry is not a quality gate. The big catalogs are open, which means anyone can publish, and a skill is just instructions plus executable scripts that your agent will run. That’s a real trust surface. Before you install a third-party skill — especially one with bundled scripts — read the SKILL.md, look at what the scripts actually do, and check the install count and source as weak signals of legitimacy. Treat an unknown skill the way you’d treat an unknown npm package with a postinstall hook: useful, but worth a glance first.
If you take one framing away, make it this. Persistent project context — your architecture, your conventions, the stuff every session needs — belongs in an always-loaded file like CLAUDE.md. On-demand playbooks — how to deploy, how to write a changelog, how to scaffold a component — belong in skills, loaded only when the task calls for them.
Context files answer “what is this project?” Skills answer “how do I do this specific thing?” Together they turn a general-purpose agent into one that knows both your codebase and your team’s way of working — and because skills are portable, that knowledge isn’t trapped in whichever tool you happened to set it up in.
\nYou don’t need a grand plan. Pick the single workflow you re-explain to your agent most often — the one where you find yourself typing the same paragraph of instructions every few days. Write it as a SKILL.md. Use it for a week. Refine the description until the agent reaches for it at the right moments without being told.
Then browse skills.sh for the obvious wins others have already solved — changelog generators, test scaffolders, commit formatters — and install the ones that fit. As your collection grows, the savings compound: every session starts with the agent already knowing how you work, and every teammate who clones the repo inherits the same playbooks for free.
\nThe format is open, the registries are public, and the skill you write today works in tools that don’t exist yet. That’s a rare kind of durable investment in a field that reinvents itself every few months.
\n‘Till next time!
","rawMarkdownBody":"\n## One Folder, Every Agent\n\nA year ago, customizing an AI agent meant rewriting the same prompt over and over, once for each tool you used. Today there's a shared format — Agent Skills — that lets you write a workflow once and run it in Claude Code, Codex, Gemini CLI, Copilot, and more. This post is a practical guide to what skills are, how to use them, and where to find the good ones.
\n\nI've written before about [Claude Code skills](/blog/claude-code/), but skills have since outgrown any single tool. The format Anthropic released as an open standard has been adopted across the ecosystem, and a whole layer of registries and tooling has grown up around it. If you've been treating skills as a Claude-only feature, this is the post that reframes them as something portable, shareable, and worth investing in regardless of which agent you reach for.\n\n### What an AI Skill Actually Is\n\nStrip away the marketing and a skill is almost disappointingly simple: it's a folder containing a single `SKILL.md` file. That file has a small block of YAML frontmatter — at minimum a `name` and a `description` — followed by plain-English instructions telling the agent how to perform a task. That's the whole core of the standard.\n\n```markdown\n---\nname: changelog\ndescription: Generate a changelog entry from staged git changes.\n Use when the user asks to write a changelog or release note.\n---\n\n## Writing a changelog entry\n\n1. Run `git diff --staged` to see what changed.\n2. Group changes under Added, Changed, Fixed, Removed.\n3. Write each entry in past tense, user-facing language.\n4. Skip internal refactors that don't affect behavior.\n5. Prepend the entry to `CHANGELOG.md` under an `## [Unreleased]` heading.\n```\n\nThat's a real, working skill. There's no SDK, no compilation step, no API to register against. The agent reads the description, decides the skill is relevant, loads the instructions, and follows them. A skill is procedural knowledge written down in a format an agent knows how to find and read.\n\nThe frontmatter is the contract. The `name` is the slug you'd type to invoke it. The `description` is the single most important line you'll write, because it's the only thing the agent sees until the skill is actually needed. More on that in a moment.\n\nA skill folder can hold more than just `SKILL.md`. You can bundle:\n\n- **Scripts** the agent runs as part of the workflow — a Python helper, a shell script, a linter config.\n- **Reference files** — API docs, style guides, schemas — that get loaded only when the instructions point to them.\n- **Templates** — boilerplate the agent fills in, like a PR description or a component scaffold.\n\n```\nmy-skill/\n├── SKILL.md # metadata + instructions (always read)\n├── reference.md # loaded only when SKILL.md links to it\n├── template.tsx # a scaffold the agent copies\n└── validate.py # a script the agent can execute\n```\n\nThis bundling is what separates a skill from a saved prompt. A prompt is text; a skill is text plus the resources and executable steps needed to actually carry the work out.\n\n### Why the Format Matters: Progressive Disclosure\n\nThe clever part of the design is how skills are loaded. At startup, the agent reads only the **name and description** of every installed skill — roughly a hundred tokens each. The full instructions, the reference files, the scripts: none of that enters the context window until a task actually matches the skill's description.\n\nThis is called progressive disclosure, and it's the reason you can have fifty skills installed without drowning your agent in irrelevant context. Each skill costs almost nothing until it's needed, then expands to full detail on demand. It's the difference between handing someone an entire library versus handing them a card catalog and letting them pull the one book they need.\n\nThe practical consequence: write descriptions that are precise about *when* a skill applies, not just *what* it does. A vague description like \"helps with testing\" forces the agent to guess. A sharp one — \"Use when the user asks to write or fix a Vitest unit test, or when a test file is open and failing\" — gives it a clear trigger. The description is doing matching work, not marketing work.\n\n### The Open Standard and Why It's Portable\n\nThe Agent Skills format was developed by Anthropic and released as an [open standard](https://agentskills.io). The specification lives at agentskills.io and is open to contributions from the wider ecosystem. The significance isn't the spec document itself — it's who adopted it.\n\nAs of mid-2026, the same `SKILL.md` folder works across a growing list of tools:\n\n| Tool | Vendor | Skill support |\n| --- | --- | --- |\n| Claude Code | Anthropic | Native |\n| Codex CLI | OpenAI | Native |\n| Gemini CLI | Google | Native |\n| GitHub Copilot | Microsoft | Via VS Code agent skills |\n| Cursor | Anysphere | Manual placement |\n| Cline / Windsurf / OpenCode | Community | Supported |\n\nWrite a skill once and it follows you across all of them. If your team standardizes on a deployment checklist as a skill, that checklist works whether a given engineer prefers Claude Code in the terminal or Copilot in VS Code. The investment compounds because it isn't locked to a vendor.\n\nThis is a genuine shift. Most AI tooling so far has been proprietary and non-transferable — your ChatGPT custom instructions don't move to another assistant. Skills break that pattern by being a plain-text, version-controllable, tool-agnostic format. They behave like source code, because effectively they are.\n\n### How to Actually Use Skills\n\nThere are three things you'll do with skills: install them, invoke them, and write your own.\n\n#### Installing Skills\n\nSkills live in conventional locations the agent scans automatically. The exact paths vary slightly by tool, but the Claude Code convention is representative:\n\n| Scope | Path | Applies to |\n| --- | --- | --- |\n| Personal | `~/.claude/skills/