# What ships beside SKILL.md: 70,893 skill folders counted

By markdownregistry. Published October 6, 2026. Updated October 6, 2026.

Almost half of agent skills are a SKILL.md and nothing else. Of 70,893 skill folders in public GitHub repositories, 46.2% hold only SKILL.md, 30.2% keep reference documents in a `references/` folder, and 18.2% ship code files, most often Python. A skill that ships code can run that code on your machine when an agent follows it, and that code is not in SKILL.md.

| The skill folder holds | Skills | Share |
| --- | --- | --- |
| SKILL.md and nothing else | 32,729 | 46.2% |
| A references/ folder | 21,438 | 30.2% |
| Code files, by extension or marked executable | 12,927 | 18.2% |
| A scripts/ folder | 10,534 | 14.9% |
| An agents/openai.yaml file | 6,018 | 8.5% |
| An assets/ folder | 3,100 | 4.4% |
| An evals/evals.json file | 2,443 | 3.4% |

70,893 agent skill folders in public GitHub repositories, each read from its repository's default branch on October 6, 2026. A folder can hold more than one of these. How each was counted is under How we counted.

Counted from the registry's own crawl of public GitHub and each repository's file tree, read on October 6, 2026, against [the Agent Skills specification](https://agentskills.io/specification) as it read that day.

## What sits beside SKILL.md

The Agent Skills specification describes a skill as a directory with a SKILL.md file and, optionally, three folders: `scripts/` for executable code that agents can run, `references/` for documentation agents read when they need it, and `assets/` for templates and other static files. It allows any other files too.

The median skill folder holds 2 files, and nine in ten hold 10 or fewer. 32,729 skills (46.2%) are SKILL.md alone, which is all the format requires. Of the three folders the specification names, `references/` is the most used, in 21,438 skills (30.2%), then `scripts/` in 10,534 (14.9%) and `assets/` in 3,100 (4.4%).

## Skills that ship code

12,927 skills (18.2%) hold at least one code file: a file with a programming language's extension, or one git marks as executable. By language, 8,599 hold Python, 2,853 shell scripts, 2,185 JavaScript, 869 TypeScript and 475 PowerShell; a skill can hold more than one. 4,613 skills (6.5%) hold a file marked executable, and 4,315 (6.1%) keep code somewhere other than `scripts/`, such as the folder's root or a `tools/` folder.

The code matters because of how skills load. An agent reads SKILL.md once it decides to use the skill, and SKILL.md can tell it to run a script; Anthropic's authoring guide recommends exactly that for steps that must not vary, so a script's output reaches the agent without its source. The source is the part a reader of SKILL.md does not see. The registry's audit, and [the checker](https://markdownregistry.com/check), read one agent file such as SKILL.md, not the scripts beside it.

## Files other tools add

Two files beyond the specification appear often enough to count. 6,018 skills (8.5%) carry `agents/openai.yaml` (a few spell it `openai.yml`), which [OpenAI's skills documentation](https://learn.chatgpt.com/docs/build-skills) describes as optional settings for its apps: how the skill appears, whether it may be invoked without being named, and which tools it depends on. The Agent Skills specification does not define it. 2,443 skills (3.4%) carry `evals/evals.json`, where [Anthropic's skill-creator skill](https://github.com/anthropics/skills/tree/main/skills/skill-creator) saves the test prompts it uses to check a skill.

## See what a skill ships before you install it

`git ls-files -s` prints each tracked file with its mode, and git records an executable file as `100755`. Filtering on that mode and on the code extensions this study counted lists a skill folder's code files by the same rule; splitting on the tab git prints before each path keeps paths with spaces whole, and `core.quotePath=false` keeps git from quoting names with accented letters, which would hide their extension. This is the output in a scratch repository whose skill holds a Python script, an executable shell script, a reference file and a PDF template:

```
$ git -c core.quotePath=false ls-files -s pdf-tools | awk -F'\t' '{split($1, m, " "); p = tolower($2)} m[1] == "100755" || p ~ /\.(py|sh|bash|zsh|js|mjs|cjs|ts|rb|ps1|go|rs|php|pl|lua)$/ {print m[1], $2}'
100644 pdf-tools/scripts/fill.py
100755 pdf-tools/scripts/setup.sh
```

Read each file it lists before an agent runs it, and pin the version you read, so an update cannot swap the scripts underneath you: [how to pin an agent skill](https://markdownregistry.com/guides/pin-agent-skills) covers that, and [the skill security guide](https://markdownregistry.com/guides/agent-skill-security) covers what to look for. Skills from other projects are on [the SKILL.md page](https://markdownregistry.com/kind/skill), most starred first. To start a new one from a file that passes every check the registry runs, use [the SKILL.md starter on mdpantry](https://mdpantry.com/s/st_shjaxurgoqng23jq), which says what to change in it.

## How we counted

The registry collects agent markdown from public GitHub repositories. We took every SKILL.md it holds inside a skill directory below the repository root, the path ending in `/SKILL.md`, 73,326 in 3,036 repositories; a SKILL.md at a repository's root is not counted. We read each repository's file tree for its default branch through GitHub's API on October 6, 2026. A file belongs to a skill when it sits under the skill's directory and not under a deeper directory with its own SKILL.md, which counts as a skill of its own. 623 skills whose SKILL.md was no longer on the branch were left out, and so were the 1,810 skills in 34 repositories whose tree GitHub did not return in full (12 trees too large to list, 22 not found), which leaves 70,893. A code file is one ending in .py, .sh, .bash, .zsh, .js, .mjs, .cjs, .ts, .rb, .ps1, .go, .rs, .php, .pl or .lua, or one git records with mode 100755, extensions compared in lower case. A JavaScript or TypeScript file can be part of a template rather than something an agent runs, and a file can be marked executable without being code, so read the code share as an upper bound on skills that ship runnable code. `agents/openai.yml` is counted with `agents/openai.yaml`. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

## Sources

- [Agent Skills specification: the skill directory and its optional folders](https://agentskills.io/specification)
- [OpenAI: build skills, agents/openai.yaml](https://learn.chatgpt.com/docs/build-skills)
- [Anthropic: the skill-creator skill and its evals](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
- [Anthropic: skill authoring best practices, utility scripts](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

Last checked October 6, 2026. The page: https://markdownregistry.com/blog/what-ships-beside-skill-md