# The open source agent skills specification, and what it leaves open > The agent skills specification fixes a folder, a SKILL.md, two required fields and their limits, and leaves triggering and finished work to each client. Kortix is the open-source CompanyOS: your agents, their skills, your company memory, and every connector in one git repo you own, with the agents working on real cloud computers. URL: https://agentskillsguide.dev/agent-skills-specification ## The directory the specification asks for `my-skill/` ``` my-skill/ ├── SKILL.md # Required: metadata + instructions ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation ├── assets/ # Optional: templates, resources └── ... # Any additional files or directories ``` Source: https://github.com/agentskills/agentskills One required file and three optional folders, with any other file or directory allowed beside them. ## A minimal valid skill, and the two lines that register it One file written to the specification's rules, then the manifest entry that maps it and the grant that lets one agent load it. The first file is an example for a repeated release task. The second is the manifest that goes with it, in the shape the reference documents, where a registered skill reaches no agent until a grant line names it. ### SKILL.md `skills/release-notes/SKILL.md` ``` --- name: release-notes description: Draft the release notes for one merged change set, grouped by what a reader will notice. Use when a version is tagged, or when someone asks what changed since the last release. --- # Release notes 1. Read the commits between the last tag and HEAD. 2. Group them under Added, Changed and Fixed. 3. Name the change a reader can see. Leave refactors out. 4. Stop when the range is empty, and say so. ``` ### kortix.yaml `kortix.yaml` ```yaml kortix_version: 3 skills: release-notes: skills/release-notes agents: support: description: Answers help desk tickets. mode: primary prompt_file: agents/support.md skills: [release-notes, kortix-cli] ``` ## A folder, a file name and two fields The [specification](https://agentskills.io/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](https://github.com/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](/what-are-agent-skills). ## 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](/progressive-disclosure) 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](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) 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](/validate-a-skill-md) 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//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](https://kortix.com/docs/developers#kortixyaml-reference)). The path from an empty folder to a granted skill is in [how to write a SKILL.md](/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. ## Questions a team asks before adopting the format Ownership, portability and the fields, in the order a decision needs them. ### Is the agent skills specification owned by Anthropic or a foundation? A foundation. Anthropic donated the format to the Agentic AI Foundation under the Linux Foundation, including the name, logo, GitHub organization and the agentskills.io domain. Anthropic developed the format and released it as an open standard, and the standard now belongs to the foundation. ### Does a skill written for one client work in another? The file travels, and the behavior may not. A valid folder loads in any client that supports the format, but each client decides when to load it and which tools it can call. Test the skill in the client you run. ### Are all the frontmatter fields required? No. Only `name` and `description` are required. `license`, `compatibility`, `metadata` and `allowed-tools` are optional, and `allowed-tools` is marked experimental, so a client may ignore it. ### Does the specification say anything about how a skill is stored? Not past the folder. The specification requires a directory containing a `SKILL.md` and says nothing about installation, versioning, registries or distribution. Each client, and each project such as Kortix, decides how a skill is registered and granted. ## Adopt the format, then write down what it does not carry. Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. [Try Kortix](https://kortix.com) · [Read the docs](https://kortix.com/docs/guide#skills) Session work reaches main through a change request · Merge is default-deny for agents