Designing Skill Categories That Survive 10,000 Skills

The Hidden Problem: Skills Have No Category Field

Your agent skill library is growing faster than your ability to organize it — and the standard you're building on has no place to put a category. That's not a minor schema gap; it's the central design constraint that will determine whether your skill ecosystem scales gracefully or collapses into noise.

Agent skills — SKILL.md instruction packages now supported across Claude Code, Codex, Cursor, Gemini CLI and chat-app agents — have exploded since Anthropic made the specification an open standard in December 2025. Yet the canonical schema contains exactly two required frontmatter fields: name and description. No tags. No categories. No hierarchy. As Anthropic's documentation confirms, the description is what the agent matches your request against when deciding whether to trigger a skill — discovery is description-driven, not taxonomy-driven.

Why does the standard skip categories entirely? Because of how skills load. Every major implementation uses progressive disclosure: roughly 50–100 tokens of metadata per skill sit in context at startup, with full instructions (under 5,000 tokens) loading only on trigger. A folder-tree taxonomy adds structure for humans but does nothing for the agent — the model never browses your directories. It reads a name capped at 64 characters and a description capped at 1,024 characters, then decides.

Traditional taxonomies also break down at scale for reasons anyone running a large library will recognize:

• Irrelevant skills actively mislead — they don't sit idle, per Red Hat's production findings, which peg optimal granularity at just 1–3 skills per task.
• Categories go stale as models improve — skills patching model gaps deprecate, while skills encoding institutional workflows endure.
• Folder structures don't sync across surfaces; Anthropic documents that custom skills must be managed separately on each platform.

The uncomfortable implication: when discovery depends on a 1,024-character description, the quality of that description — and the trustworthiness of the skill behind it — becomes your real sorting mechanism. A skill with a vague description is functionally uncategorizable, no matter how well-written its instructions are.

This is why SkillzBench is being built around verification and benchmarking rather than taxonomy alone — security-scanning every skill, pinning versions to commit SHAs, and testing each one in a sandbox to measure real Lift. When published research finds roughly 26% of skills carry at least one vulnerability, knowing which skills are safe and effective matters more than knowing which folder they belong in.

Progressive Disclosure: The Architecture That Makes Scale Possible

The skill ecosystem faces a paradox: the same architecture that lets agents carry 10,000 skills without context bloat is the architecture that makes traditional categorization impossible.

Every major platform now converges on the same three-tier loading model. At the base layer, roughly 100 tokens of metadata per skill — just the name and description — stay permanently loaded in the agent's context window. The full instruction body, capped at under 5,000 tokens, loads only when the agent determines a skill is relevant to the current task. Bundled resources, scripts, and reference files carry zero token cost until they're actually accessed.

This design is why scale becomes feasible. An agent with 10,000 installed skills burns roughly one million tokens on metadata alone — manageable for modern context windows, and a fraction of what loading every full instruction would cost. Anthropic's documentation confirms the intent: you can install many Skills without context penalty, because until a Skill is triggered, only its name and description occupy context.

But the architecture carries a hidden cost. The dominant SKILL.md schema contains exactly two required fields — name and description. There is no category field, no tag taxonomy, no hierarchy. Discovery happens entirely through the model matching the user's request against that 1,024-character description string. Red Hat's ACE Team calls L1 descriptions the skill's "discoverability bottleneck" — and warns that generic summaries get overlooked entirely.

The implication reshapes how categories must work at scale:

• No folder structure or explicit tag survives — the schema simply doesn't carry one
• Naming conventions become the only stable taxonomy signal visible at startup
• Description language must encode both what a skill does and when to trigger it
• Negative constraints ("do NOT use this skill for X") become essential disambiguation tools
• Irrelevant skills don't sit idle — they actively mislead the agent, per Red Hat's findings

When every skill competes for the same ~100-token slot in the model's attention, description quality is the sorting mechanism. A vague description means a skill is functionally invisible — regardless of how well it actually performs. This is precisely why a directory like SkillzBench treats verification and benchmarking as inseparable from discovery: at scale, you cannot separate "what a skill claims to do" from "what it actually does" without breaking the entire architecture.

Categories That Actually Work: Namespacing, Durability, and Granularity

The awkward truth about skill categories is that the standard skill format doesn't have any. The documented schema contains only two required fields — name and description — with no category, tag, or hierarchy field at all, per Anthropic's official documentation. Discovery is description-driven, not taxonomy-driven.

That means "categories" that survive at scale aren't folders. They're conventions encoded into the name, the description text, and the boundaries you draw around each skill. Red Hat's ACE team recommends three concrete tactics: namespacing skills by domain, adding negative constraints to descriptions ("do NOT use this skill for X"), and lightweight router skills for handoffs between skills. Their reasoning is blunt: "L1 descriptions are your skill's discoverability bottleneck," and generic summaries get overlooked (Red Hat ACE Team).

The constraint is tight. The name field allows a maximum of 64 characters — lowercase letters, numbers, and hyphens only — while the description field caps at 1,024 characters. Your entire category system lives inside those limits.

A second design axis is durability. Red Hat distinguishes capability skills from preference skills. Capability skills patch gaps in the base model, so they deprecate as models improve. Preference skills encode workflows, conventions, and institutional knowledge — the things your organization does its own way — and those outlast any model generation. Their stated principle: domain knowledge over performance. If you're building a skill library meant to last, weight it toward preference skills.

The third axis is granularity, and here the finding is counterintuitive: more skills can actively hurt performance. Red Hat's practitioners put the optimal range at 1–3 skills per task, and warn that irrelevant skills don't sit idle in the background — they can actively mislead the agent. Comprehensive skills covering entire domains degrade performance, while focused skills with clearly defined scopes are more reliable. They also flag a hard ceiling inside individual skills: SKILL.md files degrade in performance around 500 lines.

For anyone curating a skill library, the practical rules follow directly:

• Namespace every skill name by domain so agents can infer scope from the name alone.
• Write descriptions that state both what the skill does and when to use it — plus what it's not for.
• Split domain-sized skills into focused ones of 1–3 per task, not one monolith.
• Favor durable preference skills over capability patches that will age out.

This is also why verification matters more than taxonomy as libraries grow. When discovery hinges on a 1,024-character description, the quality of that text — and the trustworthiness of the skill behind it — becomes the real sorting mechanism. It's the premise behind SkillzBench's directory: every skill pinned to a commit SHA, security-scanned, and benchmarked with its Lift published separately, so a crowded library is something you can prune with evidence rather than guesswork.

Why Verification Beats Taxonomy at 10,000 Skills

Here is the uncomfortable math of scale: when an agent loads a skill library, only each skill's name and description enter context — roughly 100 tokens per skill — and the agent decides what to use based almost entirely on that description. There is no category field to fall back on. The canonical skill schema requires just name and description, capped at 1,024 characters, with no tags, no hierarchy, no folder semantics at all, according to Anthropic's official skill documentation. Discovery is description-driven, which means the sorting mechanism at 10,000 skills isn't taxonomy — it's trust.

This reframes what a "well-organized" directory actually is. A perfect folder tree tells you where a skill lives; it tells you nothing about whether the skill is safe, honest about what it does, or effective. Red Hat's ACE Team puts it bluntly: "L1 descriptions are your skill's discoverability bottleneck," and a skill that only works when force-loaded is unlikely to work in production (their skills guide). Worse, published research cited in the agent-skills community found that ~26% of skills carry at least one vulnerability — at 10,000 skills, that's roughly 2,600 pieces of unvetted code your agents might execute.

The trust signals that survive scale are the ones you can measure:

• Security scanning — Anthropic itself warns that a malicious skill can direct agents to invoke tools or execute code in ways that don't match its stated purpose, and advises treating skills like installing software.
• Description-quality assessment — since a vague description makes a skill functionally invisible to the agent, description quality is a first-class signal, not a cosmetic one.
• Benchmarked Lift — testing each skill in a sandbox, with and without the skill, against the same model, and publishing the difference in percentage points.
• Granularity risk — the optimal threshold is 1–3 skills per task, and irrelevant skills don't sit idle; they can actively mislead the agent.

This is the skills-as-software-engineering mindset taking hold. Red Hat recommends versioning with no breaking changes in patch releases, Git-based review with rollback, CI regression testing, and quality gates that block merges — because "building effective AI agent skills isn't fundamentally different from building good software." A skill that ships without versioning, testing, or a security gate isn't a knowledge asset; it's unreviewed production code.

That's the bet behind SkillzBench, which is being built around exactly these signals: pinning every skill to a commit SHA, security-scanning, quality-judging descriptions, and benchmarking Lift — with Lift always shown separately from ratings, and no money ever touching scores. If you want to know which skills actually help before you load them into your agents, join the SkillzBench waitlist and follow along as the directory, benchmarks, and free MCP connector come online. Skills, proven.

Building Your Cross-Agent Control Plane

The hardest part of governing agent skills isn't choosing a taxonomy — it's that the taxonomy has nowhere to live. Anthropic's documented skill schema contains no category, tag, or hierarchy field, only name and description, so discovery happens by matching a request against a skill's description rather than by browsing a folder tree. Red Hat's ACE team calls these first-level descriptions the discoverability bottleneck: generic summaries simply get overlooked, and no amount of folder structure fixes a vague sentence.

Fragmentation compounds the problem. Custom skills do not sync across surfaces, per Anthropic's platform documentation, and sharing scopes differ by surface — individual on claude.ai, workspace-wide on the API, personal or project-based in Claude Code. With metadata costing roughly 100 tokens per skill at startup, a sprawling library quietly consumes context before any work begins.

A cross-agent control plane closes that gap with four moves:

• Per-agent loadouts: toggle skills and tools per agent so each one sees only what you chose for it.
• A free MCP connector that carries your selections across surfaces the standard itself doesn't sync.
• Directory-level discovery that crawls, dedupes, and pins every version to a commit SHA.
• Verification and benchmarking that scan, license-check, and test each skill with and without it loaded.

SkillzBench is building exactly this: a free directory plus a free MCP server, with verification, benchmarking, and per-agent loadouts as the governance layer. Published research finding that roughly 26% of skills carry at least one vulnerability makes scanning a survival feature rather than a checkbox, and Red Hat's finding that one to three skills per task is optimal means loadouts aren't just tidy — they're how you avoid misleading the agent.