Designing Skill Names and Descriptions Agents Can Find

The Metadata Trap: Why Agents Ignore Your Skill

The most expensive failure in agent development is silent. Your skill loads perfectly, yet the agent never activates it. This happens because modern agents rely on a mechanism called progressive disclosure.

At startup, the agent does not read your entire codebase or instruction file. It only pre-loads the name and description fields into its system prompt. This lightweight tier costs approximately 100 tokens per skill, keeping context usage low. The full body of the skill remains dormant until the agent decides to trigger it.

This design creates a high-stakes bottleneck. The description acts as the sole router for your skill. If the agent’s internal matching logic fails to connect a user’s request with your description text, the skill never loads. There is no error message, no warning, and no fallback. The agent simply proceeds with its baseline tools, unaware that your specialized capability exists.

Practitioners emphasize that the description is not documentation; it is a trigger mechanism. It must answer two questions: what the skill does and when to use it. Writing this field last, after the skill’s behavior is fully defined, ensures accuracy.

Consider the risks of a poorly crafted description:

• Under-specified text prevents the skill from triggering during valid use cases.
• Over-broad text causes false positives, cluttering the agent’s context with irrelevant tools.
• Vague phrasing fails to match the specific keywords users actually type in their requests.
• Technical jargon can obscure the practical application, hiding the skill from the agent’s matcher.

The stakes extend beyond efficiency. A recent security incident demonstrated that a fake skill with a plausible name and description passed multiple security scanners. It reportedly reached 26,000 agents by mimicking legitimate patterns. This proves that metadata is also a trust surface. If your description is ambiguous, you risk both invisibility and exploitation.

To mitigate this, developers must test discoverability rigorously. The recommended approach involves running a small set of labeled queries through the agent. You measure whether the skill triggers for relevant tasks and stays dormant for irrelevant ones. This iterative process ensures your description aligns with actual user intent rather than theoretical expectations.

SkillzBench is building infrastructure to address these challenges. By verifying skill metadata and benchmarking performance, the platform helps ensure that skills are not just well-written, but actually effective. Joining the waitlist provides early access to these verification tools, allowing you to validate your skill’s discoverability before you publish it to the broader ecosystem.

The 'What + When' Formula for High-Trigger Descriptions

A skill that never fires is a skill that doesn't exist. When an agent starts up, it loads only each skill's name and description into its context — roughly 50 to 100 tokens per skill — and matches incoming requests against that tiny snippet to decide whether the full skill is worth loading. The description, as the agentskills.io optimization guide puts it, "carries the entire burden of triggering."

That's why nearly every authoritative source converges on the same formula: state what the skill does, then state when to use it — in the words a user would actually type. Anthropic's documentation is explicit that the description must say both what the skill does and when to use it, because that's what the agent matches your request against when deciding whether to trigger it. Official examples follow the pattern consistently, like "Reviews pull requests for code quality. Use when reviewing PRs or checking code changes."

The practitioner framing is even sharper. Alejandro Saucedo of the Ethical Institute treats the description as a router, not documentation — it exists to match the words a user types, and descriptions that only describe what a skill is tend not to fire because nothing in them matches actual user phrasing. He writes descriptions last, once the skill's real behavior is known, and writes them "for the router rather than for the reader."

There's also a balance to strike between under-specifying and over-broadening:

• Too narrow, and the skill won't trigger when it should — the user's phrasing never matches.
• Too broad, and it fires when it shouldn't, hijacking tasks the agent handles fine on its own.
• Remember that agents only consult skills for tasks beyond their baseline capabilities, so simple one-step requests may never trigger even a matching skill.
• When optimizing after failed queries, address the general concept rather than pasting in specific keywords — that's overfitting.

The name matters too. Names are commands in tools like Claude Code — the directory name or frontmatter name becomes what you type — and must follow strict constraints: lowercase letters, numbers and hyphens, 64 characters or fewer, matching the parent directory name. Descriptions cap out at 1,024 characters, a limit that tends to get pressured during optimization.

One final note worth taking seriously: this same metadata is a trust surface. A fake skill named brand-landingpage with a plausible description reportedly passed major security scanners and reached around 26,000 agents — a reminder that well-written descriptions can carry risky skills just as easily as good ones. That's part of why SkillzBench is building independent verification — pinning every skill version to a commit SHA, security-scanning, and benchmarking — so the descriptions you rely on describe skills you can actually trust.

Technical Constraints and the Trust Surface

Skill names look like harmless labels, but they are actually executable metadata. In Claude Code, the directory name or frontmatter name becomes the command you type to invoke the skill, which is why the spec treats names as commands rather than branding.

The technical constraints are strict, and they trip up new skill authors constantly. Per the official Agent Skills documentation, the name field allows a maximum of 64 characters, restricted to lowercase letters, numbers, and hyphens.

• No consecutive hyphens, and the name cannot start or end with a hyphen.
• The name must match the parent directory name exactly, or the skill will not load.
• Zero-width spaces and characters like `<` prevent a skill from loading at all.
• Reserved folder names like `synced` and `anthropic-skills` will not load as authored skills.

Descriptions carry their own ceiling: 1024 characters, non-empty, with no XML tags. That limit tends to get pressured during optimization, because a good description lists every trigger context in the words a user would type, and those words add up fast. Plan for the squeeze rather than discovering it at publish time.

Here is the uncomfortable part: the same metadata that makes a skill findable also makes it dangerous. Names and descriptions are the trust surface of the skill ecosystem, and they are trivially easy to fake. In a security experiment reported by The Hacker News, a fake skill named brand-landingpage with a plausible description passed Cisco's, NVIDIA's, and all three skills.sh scanners, and reportedly reached around 26,000 agents, including some on corporate accounts. The skill borrowed credibility by riding inside a marketplace repo with roughly 36,000 stars.

The failure was not sloppiness on the scanners' part. As Trail of Bits put it, "a scanner checks a fixed package, while an attacker can keep tweaking the payload until it passes." A plausible name and description are exactly the camouflage an attacker needs, because scanners read what ships inside a package while humans trust what the label says. The Hacker News analysis draws the right conclusion: "Treat skills as software, not text. Vet what a skill points to, not just what ships inside it." Anthropic's own engineering guidance warns that malicious skills can introduce vulnerabilities or direct an agent to exfiltrate data and take unintended actions.

This is why verification infrastructure matters more than any naming convention. SkillzBench is being built to pin every skill version to a commit SHA, run security scans and license checks, and publish trust scores from security, quality, and maintenance signals, so a well-written description stops being the only evidence a skill is safe. The full picture, including how descriptions get tested against real queries, is covered in the Anthropic engineering blog.

For skill authors, the takeaway is simple: respect the constraints from day one, and never assume that a skill which loads correctly is a skill that behaves correctly.

Testing Discoverability and Verifying Integrity

A skill that never triggers is indistinguishable from a skill that doesn't exist. Before you publish, you need evidence that your description actually routes the requests you intend — and evidence that the skill behind it is what it claims to be.

Start with a small labeled eval set. The agentskills.io optimization guide recommends roughly 20 realistic queries: 8–10 that should trigger the skill and 8–10 near-misses that share keywords but need something different. Run each query at least three times — around 60 invocations total — and track trigger rates.

The pass thresholds are simple:

• Should-trigger queries must fire more than 50% of the time
• Should-not-trigger queries must fire less than 50% of the time
• Split queries roughly 60/40 between tuning and validation, then finish with 5–10 fresh queries as a generalization check

When a query fails, resist the temptation to paste its exact keywords into your description. The guide warns that this is overfitting — instead, identify the general concept the failed queries represent and address that. Most descriptions converge within about five iterations.

One practitioner tip sharpens the test itself. Alejandro Saucedo of the Ethical Institute argues that "a cheap model is a more honest test, as it will fall into every hole that a strong model steps over." If your description triggers reliably on a weaker model, a stronger one will almost certainly find it too.

Testing discoverability, however, only verifies one half of the equation. A description can be perfectly tuned and still describe a skill that isn't safe to install. The brand-landingpage experiment proved this: a fake skill with a plausible name and description passed Cisco's, NVIDIA's, and all three skills.sh scanners, reportedly reaching around 26,000 agents. As Trail of Bits noted, "a scanner checks a fixed package, while an attacker can keep tweaking the payload until it passes."

This is why independent verification matters as much as description tuning. SkillzBench is being built to pin every skill version to a commit SHA, run security scans and license checks, and benchmark each skill in a sandbox with the same model — with and without the skill — so you can see the measured Lift rather than trusting a description's promises. Alongside its free directory and MCP connector, that verification layer turns "this skill sounds useful" into "this skill, at this exact version, demonstrably helps."