The open source agent skills specification, and what it leaves open

A folder, a file name and two fields

The specification describes itself in one line: "Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. At its core, a skill is a folder containing a SKILL.md file." It is published in an open source repository, agentskills/agentskills, and the requirement fits on a page: a directory, a file with that exact name, YAML frontmatter, then Markdown.

Everything else in the format is a constraint on that wrapper. name "Must be 1-64 characters" and "May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)". It "Must not start or end with a hyphen (-)", "Must not contain consecutive hyphens (--)" and "Must match the parent directory name". description "Must be 1-1024 characters" and "Should describe both what the skill does and when to use it", with keywords an agent can match against a task. A validator can check those two rules. It can say nothing about whether the file is any good.

What the specification says about bodies is a refusal to decide: "The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions." Step-by-step instructions, examples of inputs and outputs, and common edge cases are recommendations there, not requirements. A reader who wants the fields explained the way an author meets them has what agent skills are.

The four fields that are optional

license "Specifies the license applied to the skill", kept short as a license name or the name of a bundled license file. compatibility "Must be 1-500 characters if provided" and exists for a skill with an environment requirement; the specification says "Most skills do not need the compatibility field." metadata is "A map from string keys to string values" that a client fills with its own bookkeeping, and the specification asks for unique key names so two tools do not collide. allowed-tools takes "A space-separated string of tools that are pre-approved to run" and carries the note "Experimental. Support for this field may vary between agent implementations".

Each field earns its line on a different question: license when the folder may leave your repository, compatibility when the steps need a package or a network, metadata when your tooling keeps its own bookkeeping, and allowed-tools when the author wants a stated intent that a client may read or leave alone.

What the standard leaves to the client

Two skills can pass the same validator and still mean different things by finished. That gap belongs to the format's design. The specification says the agent "will load this entire file once it's decided to activate a skill" and stops there. Nothing in it defines the decision.

Three questions stay with each client. Whether a skill triggers comes from how that client compares text against a description: no threshold or matching rule appears in the specification. What a finished task looks like comes from the body, which has no required section and no completion signal, so a file can end with "write the summary and stop" or with nothing. Which tools a skill may call comes from a string marked experimental, with no list of tool names in the standard to check it against.

Storage is the same kind of silence. The specification fixes a folder and says nothing about installation, versioning, registries or distribution. Its three load tiers are written as a budget: metadata at roughly 100 tokens, the body under 5,000 recommended, bundled files read only when a step reaches for them. A client can keep that budget and still choose its own moment to spend it, which makes the three load tiers a cost model rather than a contract.

Portability therefore buys a file and a rule about when its first tier is available. It does not buy the behavior of the skill, because the behavior lives in sentences the format declines to shape.

Who holds the pen now

Provenance sits on the repository's front page: "The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." Anthropic's announcement records where the format went next. Anthropic donated the name and logo, the GitHub organization and the agentskills.io domain to the Agentic AI Foundation, under the Linux Foundation, which Anthropic co-founded with Block and OpenAI. David Soria Parra and Mahesh Murag are Lead Maintainers. The same announcement reports the reach of the format: "1 million skills have been published and nearly 280 million installed" (October 2026).

The repository also keeps two licenses apart in one line: "Code in this repository is licensed under Apache 2.0. Documentation is licensed under CC-BY-4.0." A team that bundles the reference library takes the code license; one that reproduces the specification page quotes documentation.

The donation moved the name, the logo, the organization and the domain. It did not move the part that makes two clients behave differently, because the loading rule was never in the standard. Governance decides what the next revision of the text says. It does not decide what your client does with a file this afternoon.

What a team adopting the format should pin

Four things are worth writing down before the first skill lands in a repository.

The revision. Record the date you read the specification beside the folder it governs, since a skill written to an older reading is not wrong until somebody cites a newer line.

The validator. skills-ref validate ./my-skill checks the frontmatter and the naming conventions, and the validator comparison covers what each one adds past that check. Validation settles legality. What a skill should do stays with a reviewer.

The definition of done. The format carries no completion signal, so a body that ends without one leaves the agent to invent an ending. Write the exit criterion as a line somebody else can check against the output.

The reach. In a Kortix project a skill lives at skills/<name>/SKILL.md, and the skills table in kortix.yaml maps a skill name to a repository folder. A registered folder reaches no agent until an agent's skills line names it, because an omitted key grants nothing, and a folder with no SKILL.md or a name: that is not the skill name makes kortix validate exit 1 (kortix.yaml reference). The path from an empty folder to a granted skill is in how to write a SKILL.md.

A team that pins those four reads a valid file as the beginning of a review. The folder travels and the wrapper is agreed; the part the standard cannot check is the part your team writes. Kortix runs on this format, with every skill a file in a git repo you own. Open source. Read it, fork it, audit it.