Agent Skills: one SKILL.md for every coding agent

A skill is a folder with a SKILL.md file in it: a name, a description, and the steps for one job. Agent Skills is an open format, and most coding agents now load it. They don't all look in the same folder, though. Most read .agents/skills/. Claude Code and Kiro don't.

Below: the format, which folder each agent reads, why a repo ships one folder plus two copies, and a real skill from a generated Next.js repo.

What a SKILL.md looks like

The spec requires two frontmatter fields:

• name: lowercase letters, numbers and hyphens, up to 64 characters. It must match the folder name.
• description: what the skill does and when to use it, up to 1,024 characters. Agents route on it.

Then the body: markdown steps, with no format rules. A skill folder can also hold scripts/, references/ and assets/.

Agents load skills in layers. At startup, only each skill's name and description. The full body when the skill is used. Extra files only when the body points at them. That's why 30 skills cost 30 descriptions, not 30 files. The spec suggests keeping SKILL.md under 500 lines.

A real skill

This is the start of setup, the skill every generated repo ships for a fresh clone. It comes straight from a real generate run:

---
description: Set up this repo after download. Fills .env.local, connects the MCP servers, sets up the database and services, and makes the product yours. Shows a plan first and acts only after a yes. Safe to run again.
name: setup
---

Get `my-app` running on this machine. Plan first. Act after a yes.

`SETUP.md` is your script. It lists every step for the services this repo was
built with, in order. A step with a `> **/setup:**` note tells you how to do it.

## Rules

- **Never ask for a key in chat.** Keys, tokens, passwords and connection
  strings go in `.env.local`. The user pastes them there. If they paste one in
  chat, do not use it or write it anywhere. Tell them to put it in
  `.env.local` and to rotate it if it is a live key.
- **Never read `.env.local`.** The guard hooks block it anyway.
  `bun run setup:env -- --check` tells you what is set.
- **Write values only through `setup:env`.** Secrets go through stdin:
  `<command that prints it> | bun run setup:env -- --set KEY`. Ids that are
  not secret: `bun run setup:env -- --set KEY=value`.
- **Ask before you create anything** in the user's accounts: projects,
  products, webhooks.
- **Stay in "Set up".** Steps under "While you build" and "Before you launch"
  in SETUP.md are not setup. Skip them.
- **Talk short.** One step at a time. Say what you did and what is next.

First 26 of 177 lines of .agents/skills/setup/SKILL.md.

What makes it portable:

• Only name and description in the frontmatter. No field that one agent understands and another ignores.
• Agent-neutral steps. Where a command differs per agent, the skill names each one: further down it lists claude mcp list, codex mcp list, gemini mcp list and copilot mcp list.
• The repo is the state. It checks what's done every run, so running it twice is safe.

Which folder each agent reads

Agent	Reads skills from
Claude Code	.claude/skills/. Never .agents/
Codex	.agents/skills/
Cursor	.agents/skills/ and .claude/skills/
GitHub Copilot	.agents/skills/, .claude/skills/ and .github/skills/
Antigravity	.agents/skills/
Gemini CLI	.agents/skills/ (we checked on 0.63)
OpenCode	.agents/skills/, .claude/skills/ and .opencode/skills/
Windsurf (Devin Local)	.agents/skills/ and .claude/skills/
JetBrains AI (Junie)	.agents/skills/
Kiro	.kiro/skills/ only
Amp, Factory Droid, Warp, Cline, Kilo Code, Zed, Goose, Augment Code, Qwen Code, Crush	.agents/skills/

Jules reads AGENTS.md, but not .agents/skills/.

How you run one: /name in most agents, $name in Codex. In Gemini CLI, ask for the skill by name. Most agents also load a skill on their own when your request matches its description.

Why .agents/skills plus two copies

.agents/skills/ reaches the most agents, so every skill lives there. Two agents don't read it:

• Claude Code never reads anything under .agents/. It gets .claude/skills/.
• Kiro reads skills only from .kiro/skills/. It gets its own copy.

In a generated repo the three folders hold the same files, byte for byte. Don't edit a copy by hand. Change the source, regenerate, and all three change together.

Claude Code skills vs Codex skills

Same format, different folder and prefix:

	Claude Code	Codex
Folder	.claude/skills/	.agents/skills/
Run one	/name	$name
Loads	Name and description at start, body when used	Same
Frontmatter	Agent Skills, plus Claude-only fields like disable-model-invocation, when_to_use, context: fork and paths	Agent Skills
Shipped in plugins	Yes	Yes

The extra fields are Claude Code features. They're fine in a Claude-only repo. A skill meant for every agent should lean on name and description alone, so it means the same thing everywhere. Claude Code's side in depth: Claude Code skills. Codex's: Codex setup.

All 29 skills in a generated repo

The Indie SaaS preset (Better Auth, Neon, Drizzle, Stripe, Resend, PostHog, Sentry, admin panel, MDX blog) ships these, shown as Claude Code names them:

• /add-admin-action: Add an admin action (verify an email, reset a plan, delete an account) as a checked, validated, audited server action with a confirm dialog.
• /add-admin-page: Add a page to /admin with the role check, a sidebar entry, loading and empty states, and data read through the admin ports.
• /add-app-page: Add a page to the signed-in app (sidebar entry, session check, loading state), or a new tab under /settings.
• /add-email-template: Add a React Email template, preview it, wire it into a send, and check it renders and lands in a real inbox.
• /add-event: Add a product event end to end, catalogue entry, the question it answers, the capture call on the correct side of the network, and a check that it arrives.
• /add-mdx-component: Add a component that posts can use without importing it, registered in src/mdx-components.tsx and styled with design tokens only.
• /add-oauth-provider: Turn on Google, GitHub or Microsoft sign-in (env keys only), or add another OAuth provider to the list in src/lib/auth/providers.ts.
• /add-plan: Add or change a plan or price on Stripe (monthly, yearly or one-time lifetime). Edit src/lib/pricing.ts, create the Stripe price, wire its env var, and prove checkout and the webhook end to end.
• /add-table: Add a table to the Drizzle schema, generate and apply its migration, and wire the typed queries for it.
• /ask-product: Answer a question about user behaviour from this repo's event catalogue and the PostHog project, with the caveats that make the number usable.
• /db-branch: Create, use, reset and delete Neon database branches, for a feature branch, a preview deploy, a migration rehearsal or a point-in-time investigation.
• /deploy-to-vercel: Ship my-app to Vercel, local gates, environment variables per scope, preview verification, promotion and rollback.
• /edit-pricing: Add, change or remove a plan or a price (monthly, yearly or one-time lifetime) and wire it to the payment provider.
• /help: Explain the agentic system in this repo, rules, skills, agents, hooks, solution docs and the CE loop, and where to go for help beyond it.
• /landing-copy: Rewrite the landing page, the metadata and the legal details for the real product from a short brief, by editing src/lib/site.ts only.
• /migrate-on-neon: Run a schema migration against Neon safely, on the direct URL, rehearsed on a branch first, with a recovery path when it fails halfway.
• /migrate: Generate, review and apply Drizzle migrations safely, including backfills, destructive changes and the deploy step.
• /new-component: Add a component to the Daylight kit. Prefer pasting from shadcn/ui, fix the two bridge classes, keep it token-only and verify it in both light and dark.
• /new-post: Draft, validate and publish a new MDX post in content/blog, with frontmatter that passes the checker and a slug that will never change.
• /preview-and-test-email: Diagnose an email problem, not sending, landing in spam, rendering wrong, in the order that finds the cause fastest.
• /protect-route: Put an authentication or role check on a page, a route handler, a server action or a whole route group, at the right layer, without a redirect loop.
• /qa-feature: Exercise a feature end to end, happy path, unhappy paths, auth boundaries, refresh and mobile, before anyone calls it done.
• /scrub-pii: Audit what this app actually sends to Sentry, extend the scrubbing layer for a new field or shape, and respond when something sensitive has already been sent.
• /security-audit: Run the standing security pass through the security-auditor agent, secrets, auth boundaries, injection, dependencies and deploy config, and turn findings into fixes.
• /setup: Set up this repo after download. Fills .env.local, connects the MCP servers, sets up the database and services, and makes the product yours. Shows a plan first and acts only after a yes. Safe to run again.
• /test-webhook: Exercise the Stripe webhook endpoint locally. Forward real events with the CLI, buy a subscription and a one-time price, refund one, assert idempotency, and debug signature failures.
• /triage-errors: Work the Sentry issue list, rank by users affected, separate regressions from background noise, find the deploy that caused it, and fix or suppress with a reason.
• /verify: Prove the repo is actually configured, every required env var present, every configured service reachable, and the guard hooks still blocking what they claim to block.
• /write-spec: Turn a loose request into a written spec, problem, scope, behaviour, acceptance criteria, that /ce-plan can consume without guessing.

Eight come with the Next.js stack in every repo. Every design adds /new-component. The rest come from the batteries you pick: Stripe brings /add-plan and /test-webhook (Stripe battery), Neon brings /db-branch and /migrate-on-neon (Neon battery).

Agent Skills best practices

• Name it as a verb. add-table, test-webhook, db-branch. Same as the folder.
• Write the description for the router. What it does and when to use it, main case first.
• Keep agent-only fields out of shared skills. name and description work everywhere.
• Steps are exact commands. Real script names, in order, with the failure branches.
• End with a check. A skill that can't tell you whether it worked isn't finished.
• Split long ones. Keep SKILL.md under 500 lines. Move reference into references/.
• One source, generated copies. Never two hand-edited versions.
• No secrets. A skill is committed with the repo.

Common mistakes

• A skill only in .claude/skills/. Codex and Kiro never see it.
• A skill only in .agents/skills/. Claude Code and Kiro never see it.
• A name that doesn't match the folder. The spec says they must match.
• Uppercase or spaces in the name. Lowercase letters, numbers and hyphens only.
• A vague description. "Helps with the database" never loads at the right time.
• Copies that drift. Edit one folder, forget the others, and agents run different steps.

Get every skill in every folder

Pick your batteries and agents at /build. All 10 agents are on by default. You get every skill in .agents/skills/, plus the .claude/skills/ and .kiro/skills/ copies when those agents are picked, with the rules, subagents and guard hooks that go with them. Every battery has to ship at least one skill to get in. $99 once, with lifetime updates. How the pieces fit: the agentic layer.

More: AGENTS.md examples, guard hooks in every agent, GitHub Copilot setup.

FAQ

What is SKILL.md?

The file that defines an Agent Skill. YAML frontmatter with a name and a description, then markdown steps. It sits in its own folder, named after the skill, with any scripts or reference files next to it.

Where do Agent Skills go?

In .agents/skills/<name>/SKILL.md for most agents: Codex, Cursor, Copilot, Antigravity, Gemini CLI, OpenCode and more. Claude Code reads .claude/skills/ and Kiro reads .kiro/skills/.

Does Claude Code read .agents/skills?

No. Claude Code never reads anything under .agents/. Keep a copy in .claude/skills/, or generate both from one source.

What's the difference between Claude Code skills and Codex skills?

The format is the same. Claude Code reads .claude/skills/ and runs a skill as /name. Codex reads .agents/skills/ and runs it as $name. Claude Code also supports extra frontmatter fields, like disable-model-invocation and context: fork.

Does Kiro read .agents/skills?

No. Kiro reads skills only from .kiro/skills/, so a repo that serves Kiro needs a copy there.

Are skills the same as slash commands?

In Claude Code, yes: custom commands were merged into skills, and each skill is a /name command. Other agents run skills by name too: /name in most, $name in Codex.