# The State of Agent Skills — 2026-07-06

*A census of the public `SKILL.md` ecosystem, generated by [`scripts/skill-census.mjs`](../../scripts/skill-census.mjs) from GitHub code search. Methodology and honesty notes at the bottom.*

## The headline numbers

| Signal | Files (GitHub estimate) | What it means |
|---|---:|---|
| Any `SKILL.md` | ~4,087,808 | The raw surface — includes forks, exports, experiments |
| With frontmatter `description:` | ~3,448,832 | Loadable by agents — the working definition of a skill |
| With **"Use when"** triggers | ~310,848 | Auto-discovery discipline (the convention that makes skills fire) |
| With **Anti-Patterns** | ~349,184 | Self-critical craft — the L3 signal |
| With **Quality Checks** | ~43,776 | Full self-verification (SkillSpec L3 house style) |

## The sample, actually graded (118 files, one per repo)

| SkillSpec level | Share |
|---|---:|
| **L3 Trustworthy** (verifiable: quality checks + anti-patterns) | 0% |
| **L2 Structured** (declared inputs/outputs) | 3% |
| **L1 Loadable** (frontmatter only) | 96% |
| **L0 Not loadable** (broken/absent frontmatter) | 1% |

- **"Use when" adoption in the sample:** 32% of descriptions
- **Security-pattern hits:** 0 of 118 sampled files (0%) contained instruction-override or exfiltration phrasing — the reason installers should scan before installing
- **Median skill size:** 4.3 KB · **Fork share of sample:** 0%

## Reading

1. **The ecosystem is real and large** — six figures of frontmattered skills — but conformance is a pyramid: most public skills stop at "loadable." The gap between L1 and L3 is where quality tooling matters.
2. **"Use when" won.** Trigger-condition descriptions are now the dominant convention; skills without them are increasingly invisible to auto-discovery.
3. **Verification is rare.** Only a small share of skills can check their own output (Quality Checks + Anti-Patterns). That's the difference between a prompt with a filename and a dependable tool — and it's checkable: `npx skillspec-check`.

## Methodology & honesty

- GitHub code-search totals are **approximations** and fluctuate run to run; only indexed (recently active) repos are visible, and matches are case-insensitive.
- Forks and re-exports of large libraries (including [pm-claude-skills](https://github.com/mohitagw15856/pm-claude-skills) itself) inflate raw totals; the graded sample **dedupes by repository** to limit this.
- The sample is what code search surfaces first, not a uniform random draw — treat percentages as directional.
- Grader: the same heuristics as [`skillspec-check`](../../skillspec/) (L1 frontmatter → L2 structure → L3 self-verification) plus the highest-signal security patterns. **The L2/L3 tests look for SkillSpec's named sections** — skills that declare structure under other conventions grade as L1 here, so treat L2/L3 shares as adoption of *this* standard, not as "everything else is unstructured."
- Counts fluctuate: GitHub's estimator can vary several-fold between runs for the same query. Compare trends across census runs, not absolute values.

*Regenerate anytime: `node scripts/skill-census.mjs` (needs `gh` auth; free).*
