The Agent Skills Spec Is Trending on GitHub. Its Entire Contract Is Two Required Fields.

agentskills/agentskills passed 20,000 stars as the standard behind SKILL.md, the format Anthropic released as an open standard. What it guarantees is thinner than "skills-compatible" sounds.

Specification repos do not trend on GitHub. Nobody stars an RFC. And yet agentskills/agentskills, a repo containing no product, no framework, and no model, just the documentation for a file format, is sitting at 20,600 stars this week and climbing the trending charts alongside the tools that implement it.

When the spec itself charts, the format has stopped being a feature and started being infrastructure. That's the story everyone can see. The story worth your time is what happens when you actually read the specification, because it is short. Shorter than you think. The entire binding contract of the format that Claude Code, Codex, and a growing list of agent products now share is: a folder, a markdown file, and two required YAML fields.

I mean that literally, and I think the minimalism is both why the format won and where it's going to bite people who assume "standardized" means more than it does.

What the spec actually pins down

A skill, per the specification, is a directory containing a SKILL.md file. That file opens with YAML frontmatter, and exactly two fields are required. name: max 64 characters, lowercase letters, numbers, and hyphens only, no leading, trailing, or doubled hyphens, and it must match the folder name. description: 1 to 1,024 characters, non-empty, describing what the skill does and when to use it.

That's the contract. Everything else is optional: a license field, a compatibility field for environment requirements (capped at 500 characters), a free-form metadata map, and allowed-tools, a space-separated list of pre-approved tools that the spec itself labels experimental. The markdown body below the frontmatter has no format restrictions at all. The spec's own words: "Write whatever helps agents perform the task effectively."

The other thing the spec pins down is the loading model, and this is the genuinely clever part. Skills load through progressive disclosure in three stages. At startup, an agent reads only each skill's name and description, roughly 100 tokens per skill. When a task matches a description, the agent pulls the full SKILL.md body into context, with a recommended budget under 5,000 tokens and 500 lines. Bundled extras (a scripts/ directory for executable code, references/ for deeper docs, assets/ for templates) load only if the instructions call for them.

That three-stage ladder is why an agent can carry fifty skills without burning its context window, and why the description field matters more than anything in the body. The description is the trigger. If it doesn't name the tasks and keywords a request will contain, the skill never loads, and nothing else about it matters.

The repo ships one more thing worth knowing about: skills-ref, a Python reference library (99% of the repo's code) with a validator. skills-ref validate ./my-skill checks your frontmatter and naming against the rules. That validator is the closest thing the ecosystem has to a conformance test, and note what it checks: the packaging. Not the behavior.

What the spec deliberately leaves open

Now read the gaps, because they're load-bearing.

The one field with security implications is the weakest field in the document. allowed-tools sounds like a permission boundary: list the tools the skill may use, and the agent stays inside the list. The spec says it is experimental and that "support for this field may vary between agent implementations." Translated: the boundary exists if your agent's harness decides it exists. A skill that declares allowed-tools: Read can still end up in a client that ignores the field entirely. If you're evaluating a third-party skill and taking comfort from a tight allowed-tools line, the comfort is not backed by the standard.

The spec has no versioning story, for skills or for itself. The metadata map can carry an author's version string, but the spec doesn't define one, and the repo has no releases published. There is no "Agent Skills 1.0" you can pin, no changelog that tells a client author what changed, no way to say "this skill requires spec revision N." The format that portability now depends on is a moving document on a main branch. In practice it's moving slowly and conservatively. But "the maintainers have been reasonable so far" is a different guarantee than a versioned standard, and anyone who lived through the MCP spec's breaking revision this summer knows how much that difference costs.

There's no conformance definition for clients either. The client showcase lists tools that support Agent Skills, but "supports" is self-declared. Does the client honor allowed-tools? Does it implement all three stages of progressive disclosure or just paste the whole file into context? Does it load references/ on demand or eagerly? The spec recommends; clients decide. Two "skills-compatible" agents can execute the same skill differently enough to change its behavior.

And provenance is out of scope entirely. Nothing in the format signs a skill, attests to its author, or verifies that the file you installed matches the file that was reviewed. The spec standardizes what a skill looks like, not whether you should trust it.

None of this is a scandal. It's a young standard doing what young standards do: specify the minimum that enables interop, defer everything contentious. The two-field contract is arguably why adoption happened at all. A format this easy to implement gives no vendor an excuse not to. But you should build with an accurate picture of which walls are structural and which are painted on.

Put this into practice

The best way to calibrate is to write and validate one real skill. Twenty minutes, start to finish.

Make a folder named for the skill, kebab-case: commit-messages/. The folder name and the name field must match, and this is the mistake the validator catches most.
Create SKILL.md with the two required fields and nothing else, then write the body as instructions to a competent new teammate. Concrete steps beat prose. If you have house rules (commit format, test commands, tone), this is where they finally live outside your head.
Spend most of your effort on the description. Pack it with the words a real request would use: "Use when writing commit messages, PR titles, or changelog entries." Vague descriptions are the number one reason skills never fire.
Validate it: install the reference library from the agentskills repo and run skills-ref validate ./commit-messages. Fix what it flags.
Drop it into any client you already use that reads skills, and watch whether it triggers when it should. If it doesn't, the description is the first thing to rewrite.
Version it yourself, since the spec won't: put version: "1.0" in the metadata map and treat any behavioral edit as a bump. Future you, diffing a misbehaving agent, will be glad.

The one thing not to do: don't treat allowed-tools as a security control when installing other people's skills. Read the body of any third-party skill before it goes anywhere near an agent with credentials. The spec makes skills easy to read on purpose. Use that.

Honest limitations

The star count deserves one asterisk: GitHub shows 20.6k stars while some trending aggregators quote figures closer to 22k. The gap is aggregator lag, not fraud, but quote the repo, not the leaderboard.

The bigger structural point: this is an open standard with one dominant author. Anthropic developed the format, released it, and the governance is "open to contributions" via a CONTRIBUTING.md rather than a foundation, a working group, or any formal multi-vendor process. Apache 2.0 code and CC-BY docs mean nobody can take the text away from you. They don't mean the ecosystem gets a vote on where it goes. If Agent Skills follows the path of other de facto standards, formal governance arrives after a conflict, not before.

And the spec's minimalism has a cost that lands on you: everything the format doesn't specify, your team now has to. Skill review policy, versioning discipline, a decision about which clients' quirks you support. The standard being one page means your internal standard has to be a few pages longer.

Where this leaves you

A one-page spec with 20,000 stars is the ecosystem voting for less standard, not more, and so far the bet is paying off: write once, load anywhere, read everything. The open question is how long a format can stay this small while carrying this much weight. The pressure for signing, versioning, and real conformance is already visible at the edges, and each of those additions will make the format safer and heavier at the same time.

Go write the twenty-minute skill, run the validator, and read the whole spec while you're there. It'll take you less time than this article did, which is exactly the point.

Sources: agentskills/agentskills on GitHub, Agent Skills specification, Agent Skills overview.