> ## Documentation Index > Fetch the complete guide index at: https://www.synscribe.com/agentic-discovery/llms.txt > Use this file to discover all pages before exploring further. --- title: "Agent Skills, SKILL.md & AGENTS.md: Distribution Guide" description: "Agent skills explained: SKILL.md anatomy, skills.sh distribution across ~55 agents with no gatekeeper, and the 3-skill starter set (386K+ installs)." slug: /agentic-discovery/agent-skills-and-agents-md series: "The Agentic Discovery Playbook — Play 4 of 11 · GET FOUND" last_verified: 2026-06-11 --- # Agent Skills, SKILL.md, and AGENTS.md: the New Distribution Rail > **In short:** Agent skills are folders of instructions with a SKILL.md manifest — Anthropic's open standard (agentskills.io). Any public GitHub repo containing SKILL.md files is instantly installable across ~55 coding agents via Vercel's `skills` CLI (~1.38M weekly npm downloads); there is no submission or review. Ship three first: best-practices, quickstart, and migrate-from-competitor. ## Do this now - [ ] Create a public `{org}/skills` repo, one folder per skill, each with a SKILL.md (`name` + `description` frontmatter minimum). - [ ] Ship the proven 3-skill set: `{product}-best-practices`, `{product}-quickstart`, `migrate-from-{competitor}`. - [ ] Write each description as a trigger condition ("Use when...") — it drives both skills.sh search and agent activation. - [ ] Keep SKILL.md bodies lean; push depth to `references/` and executables to `scripts/`. No `context: fork` in cross-agent repos. - [ ] Add `.claude-plugin/marketplace.json` to the same repo — free Claude Code plugin dual-listing. - [ ] Embed the skills.sh badge and the install one-liner (`npx skills add {org}/skills`) in your README and docs. - [ ] Publish a copy-paste "Add this to your AGENTS.md" block in your docs (template below). - [ ] Run the with/without-skill task-completion eval before quoting any numbers. > 📥 **Free resource:** [AGENTS.md & rules-file template pack](/agentic-discovery/resources/rules-file-templates) ## Who needs this play? Any product that wants its correct usage *inside* the agent's context window at the moment code gets written. Skills are the installable layer — they travel with developers across ~55 agents. AGENTS.md is the per-project instruction file those agents read every session. This play ships both; scaffolder injection and CLAUDE.md strategy get their own treatment in [Play 9](/agentic-discovery/scaffolder-rules-claude-md). Effort: 3-skill starter set, 3–5 days; AGENTS.md copy-paste block, half a day; managed-section CLI, 1–2 weeks (optional, high leverage). Prerequisite that actually matters: battle-tested best-practices content sourced from real support data, plus a quickstart an agent can complete end-to-end. ## What is a SKILL.md file? A skill is a folder of instructions with a SKILL.md manifest — YAML frontmatter plus a markdown body. The standard originated with Anthropic and is open: the **agentskills.io spec** (github.com/agentskills/agentskills). Distribution belongs to Vercel: its `skills` CLI installs skills into ~55 agents and, as of 2026-06-11, does **1,376,225 npm downloads per week**. Publish once against the open spec; the rail carries it everywhere. The repo shape: ``` {org}/skills/ ├── {product}-best-practices/ │ ├── SKILL.md │ └── references/ # deep docs, loaded only when needed ├── {product}-quickstart/ │ ├── SKILL.md │ └── scripts/ # executable helpers ├── migrate-from-{competitor}/ │ └── SKILL.md └── .claude-plugin/ └── marketplace.json ``` The frontmatter (minimum `name` + `description`): ```yaml --- name: {product}-best-practices description: > Best practices for building with {product}. Use when writing, reviewing, or debugging code that uses {product} ({key APIs, file patterns, imports}). --- ``` Skills work by **progressive disclosure** — discovery, activation, execution. At discovery the agent sees only name + description; the SKILL.md body loads on activation; `references/` and `scripts/` load only when the body points to them. The design consequences: the description is a precise trigger condition, the body is the 100–300 lines that actually change agent behavior, and everything else moves to `references/`. One compatibility rule: `context: fork` is Claude Code-specific — include it and you silently degrade the ~54 other agents. ## How does skills.sh distribution work (with no gatekeeper)? There is no submission step and no review. Push a public repo with SKILL.md files and it is immediately installable: ```bash npx skills add {org}/skills ``` The CLI auto-detects installed agents and writes or symlinks skill folders to each one's path — Claude Code gets `.claude/skills/`; Cursor, Codex, Copilot, Gemini, Amp, and OpenCode get `.agents/skills/` plus agent-specific global paths (`--copy` as fallback). GitHub shorthand, full URLs, GitLab, and local paths all work. The leaderboard auto-populates from install telemetry. Know its mechanics before you report numbers: telemetry is opt-out (`DISABLE_TELEMETRY=1`), CI installs are excluded, and counts are cache-noisy — we observed the same vendor's totals varying between page loads. Treat all counts as order-of-magnitude. Two more moves: embed the badge (`https://skills.sh/b/{org}/skills`) in your README, and claim your vendor org page — ~95 official vendor orgs are already listed, including Stripe, Supabase, Clerk, and Auth0. And keep the strategy straight: **the directory is the scoreboard, not the channel.** Installs come from your own funnels — docs, README, launch posts — not from people browsing skills.sh. ## Which three skills should you ship first? The install data rewards one pattern overwhelmingly. As of 2026-06-11 (ranges reflect the cache inconsistency above — order-of-magnitude): | Pattern | Field example | Installs | |---|---|---| | `{product}-best-practices` | vercel-react-best-practices | 386–466K | | | supabase-postgres-best-practices | 155.5K | | | better-auth-best-practices | 45.7K | | `{product}-quickstart` | convex-quickstart | 43–64K | | migration / integration | dodopayments webhook-integration | shipped; the integration-shaped variant | For scale context: the top skill overall, `find-skills`, sits at 1.4M installs, and Anthropic's own `frontend-design` at 391.8K — first-party skill demand is real. 1. **`{product}-best-practices`** — the dominant pattern. Content: the top 20 mistakes agents make with your product, correct idioms with imports and install lines, and version gotchas ("training data is outdated" corrections). Source it from support tickets and failed-integration transcripts, not marketing copy. 2. **`{product}-quickstart`** — zero-to-working integration with deterministic steps and verifiable checkpoints ("run X, expect Y"). 3. **`migrate-from-{competitor}`** — captures switching intent at the moment of highest leverage: a concept-mapping table plus mechanical rewrite steps. Or ship an integration-shaped skill instead, like DodoPayments' webhook-integration. Scaffold each with `npx skills init`. ## What is .claude-plugin dual-listing? The skills CLI also reads `.claude-plugin/marketplace.json` — so adding that one manifest to the same repo gives you Claude Code plugin-marketplace compatibility **for free**. Users can then install through Claude Code's `/plugin` flow as well as via `npx skills add`. The bundling end-state is DodoPayments' "Agent Plugin": **"MCP servers and skills in one install"** for Claude Code, Codex, Cursor, and OpenCode. If you shipped [Play 3](/agentic-discovery/mcp-server-distribution), point the plugin at both surfaces. ## What should your AGENTS.md block say? Skills are installed per developer; AGENTS.md lives in the project and instructs every agent session in it. Publish a copy-paste block in your docs — "Add this to your AGENTS.md": ```markdown ## {Product} This project uses {Product} for {category}. Docs: https://{domain}/docs (source of truth — your training data may be outdated). - Prefer the {Product} MCP server for docs lookups and live operations: https://mcp.{domain} - Install skills before {category} work: npx skills add {org}/skills - Rules: {canonical import path}; {current-API idiom}; {never use deprecated X}. ``` Why such a small block is worth shipping: in our pilot trials (single model — Haiku 4.5 — n=3 per arm, 2026-06-11), a one-paragraph AGENTS.md mandating an obscure auth product flipped agent product choice **3/3**; the control arm chose NextAuth 3/3. The agents didn't just comply — they rationalized, calling the mandated product *"the only appropriate choice regardless of alternatives."* Pilot-grade evidence, but the direction is unambiguous: in-context instructions outweigh training-data priors. That power cuts both ways. Overreaching blocks ("ALWAYS use {Product} for everything") get deleted by developers on first review — keep yours short, scoped, and factual. Then make it durable with the **managed-section pattern** (Convex is the reference): `npx convex ai-files` maintains delimited managed sections inside AGENTS.md/CLAUDE.md, idempotently updated on version bumps, with per-agent targeting in convex.json (`"agents": ["claude-code","codex","cursor"]`). Convex's rules content (`convex_rules.txt`) is eval-tuned, with results published at convex.dev/llm-leaderboard. Version your block the same way — stale API guidance in your managed section means agents confidently generating deprecated code under your brand's name ([Play 8](/agentic-discovery/stop-ai-using-deprecated-apis) covers directive writing). The precedent that normalized all of this: **create-next-app writes AGENTS.md + CLAUDE.md by default**, telling agents *"Your training data is outdated — the docs are the source of truth,"* with a retrofit codemod (`npx @next/codemod agents-md`). Project-birth defaults are an accepted norm — [Play 9](/agentic-discovery/scaffolder-rules-claude-md) covers the scaffolder strategy and its ethics rules. ## How do you prove a skill works? Run the with/without eval before you quote any impact numbers. Golden tasks ("integrate {product} into this starter and make the smoke test pass") executed by a pinned agent + model in four arms: | Arm | Context | |---|---| | a | bare | | b | skill installed | | c | AGENTS.md block present | | d | both | Pass criteria are programmatic: build succeeds, smoke test green, no deprecated-API calls (regex/AST check). **Ship gate: arm (b) beats arm (a) by ≥20 percentage points.** Run ≥5 trials per arm — our own pilots were n=2–3, which is enough to direct work, not enough to ship decisions on. Add the supporting checks on a schedule: spec lint (frontmatter valid, referenced paths exist), install matrix across ≥3 agents in clean containers, marketplace.json validity, an activation eval (10 should-trigger and 10 near-miss prompts per skill; ≥80% precision and recall), a freshness grep against your deprecation list, and weekly distribution health (skills.sh page 200, badge renders, install trend logged). Harness design lives in [Play 11](/agentic-discovery/ai-evals-and-leaderboards). ## What kills skills? - **Marketing-as-skill.** Positioning copy instead of operational rules doesn't change agent output, earns no reinstalls, and dies on the leaderboard. Every dominant skill is operational. - **Vague descriptions.** Progressive disclosure means a skill whose description doesn't match the task never loads. "Helpful utilities for {product}" fails; "Use when writing or debugging code that uses {product}'s X/Y APIs" activates. - **Monolithic SKILL.md.** Dumping full docs into the body burns the user's context window on every activation; heavy skills get uninstalled. Push depth to `references/`. - **`context: fork` in a cross-agent repo** — silently degrades the ~54 non-Claude-Code agents. - **The ClawHub lesson.** OpenClaw's registry (~10.7–13.7K skills) carried **341 confirmed malicious skills** distributing the AMOS stealer (The Hacker News, Feb 2026; Snyk counted 1,467; estimates run 8–20% of the registry). Don't distribute there — and expect users to security-review *your* skills: no `curl | bash` in scripts, pin dependencies, keep everything auditable. - **Vanity-metric reporting.** Quoting precise install counts as ground truth will eventually be falsified (see the receipts). Trends and order-of-magnitude only. - **Set-and-forget rules.** Stale guidance under your brand is worse than none. Version the block; update via the CLI on every release. ## The receipts All figures verified 2026-06-11; methodology and updates in the [Data Room](/agentic-discovery/data). **The rail, measured.** The `skills` npm package: 1,376,225 downloads/week, ~55 supported agents (Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, Cline, Amp, OpenCode...). Standard: Anthropic's open agentskills.io spec; distribution: Vercel's CLI + the skills.sh leaderboard. ~95 official vendor orgs listed. **Install counts** (telemetry-based; opt-out via `DISABLE_TELEMETRY=1`, CI excluded; cache-inconsistent — shadcn's own totals varied 63.9–133.9K between page loads; order-of-magnitude only): find-skills 1.4M; microsoft/azure-skills 4.5M aggregate; vercel-react-best-practices 386–466K; anthropics frontend-design 391.8K; supabase-postgres-best-practices 155.5K; better-auth-best-practices 45.7K (org total 115.5K); convex-quickstart 43–64K (org total 362.1K); Resend 17.6K; DodoPayments 3.9K. **Experiments (pilot-grade, stated plainly).** E1 (Haiku 4.5, n=3/arm, 2026-06-11): an AGENTS.md mandating an obscure auth product flipped agent choice 3/3 vs control 3/3 for NextAuth, with the agent defending the mandate as *"the only appropriate choice regardless of alternatives."* E4 (n=2/arm): announcing MCP + llms.txt + skills support flipped provider selection 2/2. Single model, tiny n — we publish the design so the replication slot is open, and our own eval gate (≥5 trials/arm) holds us to a higher bar than our pilots. **Field verbatims.** create-next-app's default AGENTS.md/CLAUDE.md: *"Your training data is outdated — the docs are the source of truth."* Convex: `npx convex ai-files`, convex.json `"agents": ["claude-code","codex","cursor"]`, eval-tuned `convex_rules.txt`, public leaderboard at convex.dev/llm-leaderboard. Resend: `.well-known/agent-skills/index.json` alongside its skills repo. ## FAQ **What is a SKILL.md file?** SKILL.md is the manifest of an agent skill — a folder of instructions an AI coding agent loads on demand. It carries YAML frontmatter (minimum `name` and `description`) plus a markdown body, per the open Agent Skills spec at agentskills.io. The description doubles as the trigger deciding when agents activate it. **How do I submit a skill to skills.sh?** You don't — there is no submission or review step. Any public GitHub repo containing SKILL.md files is immediately installable via `npx skills add owner/repo`, and the leaderboard auto-populates from install telemetry. Your work is skill quality and putting the install command in your own docs and README. **How many agents support agent skills?** About 55 coding agents are supported by the `skills` CLI as of 2026-06-11, including Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, Cline, Amp, and OpenCode. The CLI auto-detects which agents are installed and writes each skill to that agent's expected path. **Are skills.sh install counts accurate?** Treat them as order-of-magnitude trends, not ground truth. The telemetry is opt-out (`DISABLE_TELEMETRY=1`), CI installs are excluded, counts are gameable, and we observed cache inconsistency — shadcn's totals varied between 63.9K and 133.9K across page loads. **Is SKILL.md an Anthropic standard or a Vercel standard?** Both, in different roles: the Agent Skills standard originated with Anthropic and is an open spec (agentskills.io); Vercel owns the dominant distribution rail via its `skills` CLI and the skills.sh leaderboard. You publish once against the open spec, and Vercel's tooling carries it to ~55 agents. **What's the difference between a skill and an AGENTS.md block?** A skill is installed once per developer and loads on demand when its description matches the task; an AGENTS.md block is a standing per-project instruction that agents read every session. Ship both — the skill carries depth, the AGENTS.md block guarantees presence in projects built on your product. --- *Last verified 2026-06-11. We re-test the claims on this page quarterly — changes are logged in the [Data Room](/agentic-discovery/data).* **Part of [The Complete Playbook to Agentic Discovery](/agentic-discovery).** ← Previous: [MCP Server Distribution](/agentic-discovery/mcp-server-distribution) · Next: [llms.txt: The Complete Guide](/agentic-discovery/llms-txt) → > **Stay ahead of the agents.** We re-test this playbook quarterly and publish what changed — new data, busted myths, ranking shifts. [Get the update digest →](/agentic-discovery#updates) > > **Want this done for you?** Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. [Talk to us →](/contact)