Why Your Skill Gets Silently Ignored

Your agent isn't ignoring your skill out of spite — it never saw it. Before an agent loads a single line of your SKILL.md body, it routes on the frontmatter description alone, and a weak description makes your skill functionally invisible.

The name and description fields are the only things the agent sees before triggering a skill, so if they aren't optimized for discoverability, practitioners are blunt about the consequence: your skill simply doesn't exist as far as the agent is concerned. The description is a trigger, not documentation — it must say what the skill does and when to use it.

The most instructive failure case comes from hands-on testing. An author wrote a description that explained the workflow — the "how" — and the agent, feeling it already understood the task, skipped loading the skill body entirely. Instead of the intended multi-pass review flow, the agent produced a single cursory review. The skill was technically installed, correctly formatted, and completely bypassed.

Even a well-written description faces a second threat: token budgets. Skills load through progressive disclosure — Level 1 metadata runs roughly 100 tokens per skill and is always loaded at startup, per the Claude platform docs. But agents cap how much skill metadata they'll carry:

• Claude Code sizes its skill listing at about 1% of the context window, tunable via `skillListingBudgetFraction`, with a 1,536-character cap per entry.
• When the listing overflows, Claude Code drops descriptions of the least-invoked skills first.
• Codex limits its listing to 2% of the context window or 8,000 characters, whichever binds first.

This is the part most authors miss: installing more skills doesn't just cost more tokens — past a threshold, it silently deletes the descriptions that make your skills discoverable. Your carefully crafted trigger text can vanish without any error, warning, or log entry. The skill directory is still there; the agent just routes around it.

The failure is also silent at load time. According to VS Code's documentation, invalid characters in the name field cause a skill to fail loading without complaint.

This is why one-shot validation isn't enough. SkillzBench, AIQ Labs' independent testing lab for agent skills, is being built around exactly this problem: continuously re-scanning and re-benchmarking skills as agents, budgets, and upstream changes evolve, so you learn a skill stopped being followed before your workflow quietly degrades.

The Three-Tier Architecture: Metadata, Instructions, Resources

Most agent skills fail not because their instructions are bad, but because their structure fights the way agents actually load context. The fix is progressive disclosure — what Anthropic calls "the core design principle that makes Agent Skills flexible and scalable."

The architecture has three tiers. Level 1 is the metadata: the name and description fields in YAML frontmatter, which cost roughly 100 tokens per skill and are always loaded at startup. Level 2 is the SKILL.md body itself, loaded only when the agent activates the skill — it should stay under 500 lines and around 5,000 tokens. Level 3 is everything else: scripts/, references/, and assets/ subdirectories that consume zero context until the agent explicitly reads them. Because files don't load until accessed, the amount of context a skill can bundle is effectively unbounded.

One structural point trips up many first-time authors: a skill is a directory, not a file. The SKILL.md acts as the "brain" — high-level logic and navigation — while dense reference material lives in subdirectories exactly one level deep, referenced via relative paths. Any reference file longer than 100 lines should open with a table of contents so the agent can read selectively rather than ingest everything.

The reason this discipline matters is token economics. As the official best-practices guide puts it, "the context window is a public good" — every loaded token competes with the system prompt, conversation history, other skills' metadata, and the user's actual request. That competition is quantifiable: a concise instruction costs about 50 tokens while its verbose equivalent costs around 150, a 3x difference for identical guidance. Conciseness here is a design requirement, not a style preference.

The same pressure applies at the listing level. Claude Code sizes its skill listing at roughly 1% of the context window with a 1,536-character cap per entry, dropping descriptions of least-invoked skills first — so installing more skills past a threshold starts silently deleting the metadata that makes your remaining skills discoverable. This is one reason SkillzBench is building per-agent loadouts, where an agent only sees the skills explicitly enabled for it rather than everything installed.

A well-structured skill directory looks like this:

• SKILL.md — frontmatter plus a body under 500 lines, serving as the entry point and navigation layer
• scripts/ — executable code for deterministic or fragile operations, loaded only on demand
• references/ — dense documentation the agent reads selectively when it needs detail
• assets/ — templates and files the agent copies or patterns from rather than regenerating from prose

Structure also carries security weight. Since roughly 26% of published skills carry at least one vulnerability, knowing exactly what lives at each level — and what loads when — makes skills auditable. That's the kind of structural scrutiny SkillzBench's verification pipeline is being built to apply: version pinning, security scanning, and quality judgment on every skill it indexes. A skill that respects the three-tier architecture isn't just cheaper to run; it's easier to trust.

Writing Frontmatter and Instructions That Trigger Correctly

A skill that never triggers is indistinguishable from a skill that doesn't exist — and the frontmatter is almost always why. The name and description fields are the only parts of your SKILL.md the agent sees before deciding whether to load anything else, so they function as a routing trigger, not documentation.

Start with the name. The agentskills.io specification requires 1–64 characters, lowercase letters, numbers, and hyphens only, and the name must match the parent directory. This isn't stylistic advice: VS Code's documentation confirms that invalid characters cause skills to silently fail to load. No error, no warning — your skill just vanishes.

The description carries more weight. It's capped at 1,024 characters, and most sources recommend 2–4 sentences covering two things: what the skill does and when to use it. Front-load concrete trigger keywords and synonyms, because the agent pattern-matches against this text to decide activation. Then add explicit negative triggers — "Do NOT use for…" clauses — which GitBook's analysis notes are powerful for LLMs because they reduce subtle mistakes.

One documented failure mode deserves emphasis: never explain the workflow in the description. A practitioner case study describes a description that revealed the "how," causing the agent to skip loading the body entirely and produce a single cursory pass instead of the intended multi-pass flow. Describe the job, not the method.

Once triggering works, match instruction rigidity to task fragility:

• High freedom: free-text instructions for tasks with many valid approaches, like code review.
• Medium freedom: pseudocode or parameterized scripts when a preferred pattern exists.
• Low freedom: exact, no-parameter scripts for fragile operations like database migrations — "Do not modify the command or add additional flags."

This framework comes straight from Anthropic's best-practices guidance, which pairs it with a useful economy: a concise instruction costs roughly 50 tokens versus 150 for a verbose equivalent — a 3x gap for identical behavior.

Finally, let assets do the describing. As the skills-best-practices guide puts it, agents pattern-match exceptionally well: instead of paragraphs describing a JSON shape, drop a template in assets/ and tell the agent to copy its structure. Since these files load only on demand, you get precision without burning context. SkillzBench is building its verification pipeline around exactly this kind of structural quality signal — validating that skills load, trigger, and behave before anyone equips them.

Validate, Test, and Stay Portable Across Agents

A well-structured SKILL.md is only half the job — the other half is proving it works before your users find out it doesn't. Anthropic's own guidance closes the authoring loop with evaluation: start by testing, then iterate with the agent to discover what context it actually needs.

The practitioner-documented validation workflow is straightforward and worth adopting as habit:

• Test discovery in a fresh chat — ask a question your skill should answer and see whether the agent actually loads it.
• Simulate execution — walk through the full workflow and watch where the agent deviates or stalls.
• Run edge-case attacks — malformed inputs, ambiguous requests, boundary conditions that break fragile instructions.
• Run evals on every change to prevent regressions, and repeat the whole loop with every model you plan to use, since effectiveness varies by underlying model.

Portability demands its own discipline. Stick to the spec-required name and description fields for maximum compatibility, because agent implementations diverge on everything else. Practitioner testing found that Gemini CLI parses only those two fields and silently discards non-spec frontmatter, while Codex uses a sidecar agents/openai.yaml instead. A field like disable-model-invocation works in Claude Code, VS Code Copilot, Cursor, and Zed — but it is not in the spec, so treat it as agent-specific.

The security dimension is harder to solve alone. Anthropic warns that skills from untrusted sources can introduce vulnerabilities or direct agents to exfiltrate data, and recommends auditing bundled files, code dependencies, and any instructions that connect to external network sources. This is where individual authoring hits a wall: continuous scanning, version-pinned validation, and re-benchmarking after upstream changes is a full-time job. SkillzBench is being built to carry that load — pinning every skill version to a commit SHA, security-scanning continuously, and benchmarking skills in a sandbox to measure the Lift they actually deliver, so no single author has to sustain validation alone.

That last point matters more than authors like to admit. Because listing pressure can silently kill discoverability as skill collections grow — Claude Code caps entries at 1,536 characters and drops descriptions of least-invoked skills first — a skill that works today can quietly degrade tomorrow. Validation isn't a launch task; it's an ongoing commitment.