You want to write a SKILL.md. Maybe you’ve already written one and you’re wondering why nobody outside your own agent setup has noticed it. This is the practical guide for the second part of that question — the file is the easy part; getting it adopted by other people is where the work hides.
We score every SKILL.md in our directory on two independent axes: Craft (is the file itself well-written?) and Adoption (is the repository around it maintained, documented, licensed, and used?). Of 2,389 SKILL.md files we’ve scraped, 322 publish at composite ≥ 4.0/5. The rest don’t fail because the spec is bad. They fail on the second axis — almost always for the same five reasons.
This post walks through both axes, ordered by what actually moves the needle. By the end you should be able to (a) write a SKILL.md that scores Craft ≥ 4.5 the first time, and (b) hit publish on a repo that scores Adoption ≥ 4.0 in under an hour. The composite that gets you on our top picks page is the harmonic mean of the two, so both bars matter.
What the SKILL.md format actually is
Briefly, because Anthropic’s official skills repo covers this better than we will: a SKILL.md is a single Markdown file inside a folder, with YAML frontmatter declaring name and description, and a body describing when the skill should fire, what it does, and any examples or constraints. The agent (Claude Code, Claude Desktop, Codex, etc.) discovers the folder, parses the frontmatter, and uses the description to decide whether to load the skill for a given task.
The spec is permissive. You can pass the format check with thirty lines. The high-scoring ones in our directory aren’t longer — they’re more specific. Below is what specifically.
Why most SKILL.md files don’t get adopted
Before the craft tips, the harder uncomfortable data. Across the 2,389 files we’ve scored:
- 2,376 of 2,389 have no license — that’s 99.5%. Without a
LICENSEfile, the SKILL.md is technically all-rights-reserved by default. Most adopters won’t touch it. - The average Craft score is 2.8/5 and the average Adoption score is 2.2/5. Both are mediocre. The gap between the median and the best is wider on Adoption than on Craft.
- Only 13 entries ship a permissive license (MIT, Apache, BSD, ISC, Unlicense). 13 out of 2,389.
- Most repos haven’t been touched in months. Maintenance is the single biggest differentiator in the Adoption score.
What this means in practical terms: a Craft score of 4.8 with no LICENSE file scores composite ≈ 3.4, which is below our publish threshold. A Craft score of 4.0 with an MIT license, an examples folder, and a commit this week scores composite ≈ 4.1, which is above. The math is unforgiving to the first; generous to the second.
Five SKILL.md files in our directory currently score Craft ≥ 4.5 but Adoption ≤ 2.5 — beautifully written specs nobody can find: tock, audio-tts, ffmpeg, aisync, btw, and claudraband. If any of those authors are reading: a LICENSE file plus one commit this week lifts your composite past 4.0 and onto our homepage. It’s the cheapest leveraged effort in the ecosystem.
Now the actual playbook.
Craft — the five things to nail in the file itself
We score Craft on five dimensions weighted into a 0–10 internal score. Hit all five and you’ll land at 4.5+/5.
D1 — Trigger clarity (25%)
The hardest single thing to get right. The description field tells the agent when to load this skill. Vague descriptions force the agent to guess, which usually means the skill never fires.
Bad:
description: A skill for working with PDF files.Good:
description: Use this skill whenever the user wants to do anything with PDF
files. This includes reading or extracting text/tables from PDFs, combining
or merging multiple PDFs into one, splitting PDFs apart, rotating pages,
adding watermarks, creating new PDFs, filling PDF forms, encrypting/
decrypting PDFs, extracting images, and OCR on scanned PDFs. If the user
mentions a .pdf file or asks to produce one, use this skill.That’s the actual description from Anthropic’s pdf skill, and it’s why it scores 4.4 on D1. Notice the structure: a generic frame (“anything with PDF files”), followed by an enumerated list of the specific transformations, followed by a tripwire condition (“mentions a .pdf file”). Three sentences, the agent has no ambiguity.
The top 8 Craft scorers in our directory all share this pattern: docx, pptx, xlsx, doc-coauthoring, claude-api, skill-creator, figma-use, and chatgpt-apps. Copy this pattern.
D2 — Output specificity (20%)
The skill body should tell the reader (and the agent) exactly what artifacts the skill produces. Names of files. Schemas of returned data. Numbers of slides or rows. “Helpful output” is not a deliverable.
The pptx skill says it produces a .pptx file with N slides, where N is derived from the input outline. The docx skill names the output extension explicitly. claude-api declares it emits a Python or TypeScript file that compiles against the anthropic SDK. Each is verifiable.
D3 — Scope precision (20%)
A skill that does everything does nothing. The Craft rubric rewards skills whose scope is bounded by what they explicitly don’t do.
claude-api is the canonical example: it explicitly states “SKIP when the file imports openai/other-provider SDK, filename like *-openai.py/*-generic.py, provider-neutral code, general programming/ML.” The SKIP section is a Craft superpower — it tells the agent how to not trigger the skill, which is half the reliability gain.
D4 — Self-containment (20%)
Does the skill assume context it doesn’t have? The pdf skill ships its own examples folder, declares its Python dependencies, and points at a requirements.txt. The reader doesn’t need to guess which library version or where to look for sample inputs.
The two-question test: (a) could a stranger run this skill end-to-end based only on what’s in the repo? and (b) could the agent recover from a failure case the SKILL.md describes? If yes to both, D4 is 4+/5.
D5 — Reusability (15%)
Will this skill work in a project that isn’t the one you wrote it for? Skills that hardcode a path, a database name, or a company-specific API land at D5 ≤ 2. Skills that accept configuration via the user’s prompt, environment variables, or arguments land at D5 4+.
skill-creator, doc-coauthoring, and claude-api all score D5 ≥ 4.5 because none of them assume a particular project layout.
Adoption — the five things to fix in the repo around the file
This is where most SKILL.md authors leave points on the table. Adoption is scored mechanically from GitHub API data — no LLM involved — so the fixes are concrete and verifiable.
A1 — Maintenance (25%)
When did you last commit to the repo? A1 = 10 if the answer is “in the last 30 days.” It drops to 4 at the 1-year mark and to 0 if the repo is archived. The bonus signal is a published release — even one tagged v0.1.0 adds a point.
Five-minute fix: push a commit to bump the version in a top-level VERSION or update a README line. Cut a release on GitHub’s Releases UI. Both moves take less than five minutes; together they bump A1 by 2-3 points.
A2 — Documentation (25%)
A1 and A2 together account for half of Adoption. A2 is scored on README length + structure: do you have a ## Usage or ## Examples heading? A demo (gif, screencast, video link, badge)?
The skills scoring A2 ≥ 4.5 in our directory all have a README that’s at least ~4,000 characters with at least one fenced code block under an “Examples” heading. A linked screencast or asciinema is worth another half-point. spark-joy and frontend-slides (both repo_tool format, technically not SKILL.md, but their README structure is what to aim for) are good models.
A3 — License (15%)
Permissive license = full marks. Strong copyleft = half. No license file at all (the modal case in our directory) = neutral.
Two-minute fix: at the root of the repo, create LICENSE and paste in MIT or Apache 2.0. GitHub will auto-detect it and surface a license badge on the repo. A3 jumps from neutral to 10/10.
Of the 2,389 SKILL.md files we track, 13 have a permissive license. Doing this alone would put your skill in the top 0.5% of the directory.
A4 — Traction (20%)
This one is partly out of your control — it’s log-scaled stars and forks — but the long tail matters. The metric maxes out at ~10k stars; the marginal difference between 10 and 100 stars is bigger than the marginal difference between 1,000 and 10,000.
The way to actually move A4: ship something an early audience will care about, and tell them. Post the skill on r/ClaudeAI, in Anthropic’s Discord, in a relevant niche subreddit, and link to it from a personal blog or X. We see a clear pattern in our data: skills that ship with a launch post outperform identical-quality skills that ship silently.
A5 — Authorship (15%)
The last dimension is about you, not your repo. If we already track you as a builder — meaning we’ve graded other skills you’ve published — your A5 starts at 6. If we’ve written an editorial profile of you, it starts at 8. The score caps at 10 when the rest of your published work also scores well.
A5 is the dimension that makes the directory self-reinforcing. The two builders we’ve editorially profiled — Zara Zhang and swyxio — both see A5 = 10 boosts across every repo they’ve shipped. The way for you to lift A5 is to ship more than one skill, and to ship them with the same consistent voice. Builders we eventually profile have, on average, four to six published skills before we notice.
Worked example: the anatomy of a composite-4.0 skill
Take claude-api, which currently scores composite 4.0 (Craft 4.8, Adoption 3.4) and is the highest-ranked skill_md skill in our directory. What does it actually do right?
- D1: the description is 250 characters, lists the exact tools/features it covers, and has a SKIP section
- D2: explicitly produces TypeScript or Python files importing
@anthropic-ai/sdk - D3: scope is bounded to a single SDK, with the SKIP section keeping it out of
openaifiles - D4: ships its own examples folder, declares versions, expects the agent to pick the SDK language from project context
- D5: works on any project regardless of layout, because it triggers on file content not file path
- A1: maintained, latest commit recent
- A2: 8k+ character README with examples and migration guide
- A3: MIT licensed
- A4: in the
anthropics/skillsrepo, which has ~3.9M aggregate stars across the catalog - A5: anthropics is the format owner; A5 = 10
If you publish a new skill and ten things from that list are true, your composite will land in the top 5% of the directory automatically.
Getting listed in our directory
We scrape GitHub for files literally named SKILL.md every 24 hours at 03:00 UTC. Your skill will appear here within a day of being public. There’s no submission form. The directory is comprehensive by design — the bar isn’t “do we accept you,” it’s “does your composite clear 4.0.”
If you’d like to get on our radar for a builder profile (which lifts A5 across everything you’ve shipped), the path is to publish two or three skills, then open an issue pointing us at your work. We profile builders on a rolling basis; the queue is read every week.
If we get a score wrong on your skill — the directory’s home is the source of truth, and the raw scoring data is in data/db.sqlite. Open an issue with the slug and your correction; we re-score in the next daily run.
Found this useful? The next post will be the inverse — how to read a SKILL.md and decide if you should adopt it. Subscribe to the Journal RSS or check back in a week.