36% of Public AI Agent Skills Are Broken. Here’s How to Build One That Isn’t.
Agent skills are markdown-based procedural knowledge files (SKILL.md) that teach AI agents domain-specific workflows, but their simplicity masks significant risks around triggering, accuracy, and security The description field acts as the primary trigger mechanism; it must explicitly state both what the skill does and when to use it, with a slight bias toward overselling to counteract model under-triggering tendencies Skills should be built from real hands-on expertise and documented gotchas rat
Analysis
TL;DR
- Agent skills are markdown-based procedural knowledge files (SKILL.md) that teach AI agents domain-specific workflows, but their simplicity masks significant risks around triggering, accuracy, and security
- The description field acts as the primary trigger mechanism; it must explicitly state both what the skill does and when to use it, with a slight bias toward overselling to counteract model under-triggering tendencies
- Skills should be built from real hands-on expertise and documented gotchas rather than generic LLM-generated content, with body text kept under ~500 lines/5,000 tokens using progressive disclosure via a references/ folder
- Fragile, correctness-critical steps should be offloaded to deterministic scripts in a scripts/ directory rather than left to probabilistic model reasoning, eliminating entire classes of inference-based bugs
- Third-party skills must be vetted before execution; Snyk's 2026 ToxicSkills audit found 36.8% of public skills had security flaws and 13.4% contained critical vulnerabilities including prompt injections and malware
Why It Matters
Agent skills represent a rapidly adopting open standard (agentskills.io) that is becoming a primary mechanism for extending AI agent capabilities, making how they're built and secured a critical concern for anyone deploying agentic systems. The gap between a skill's simplicity on paper and the real-world risks of mis-triggering, incorrect outputs, and supply chain compromise means practitioners need disciplined authoring and review processes before integrating skills into production workflows.
Technical Details
- Skills follow the agentskills.io open standard: a SKILL.md file with a YAML frontmatter header (name max 64 chars, description max 1,024 chars) followed by a markdown body, organized in folders that may contain references/ and scripts/ subdirectories
- At agent startup, only skill names and descriptions are loaded into context; the full body is loaded only when a skill is selected, enabling progressive disclosure of detailed reference materials on demand
- Deterministic scripts in the scripts/ directory are excluded from the context window entirely, reducing token consumption while replacing probabilistic model reasoning with explicit code execution for fragile operations (e.g., numerical reconciliation with tolerance-based validation)
- The Snyk ToxicSkills audit (February 2026) analyzed 3,984 public agent skills, finding 1,467 with security flaws and 534 with critical issues including prompt injection vectors and malicious payloads capable of accessing local file systems and API keys
- The recommended skill body size ceiling is approximately 500 lines or 5,000 tokens; beyond that, content should be split into the references/ folder to avoid context window contention with other active information
Industry Insight
- Organizations adopting agent skills should establish internal review checklists modeled on dependency scanning practices from traditional software engineering, treating third-party skills with the same scrutiny as open-source packages before deployment
- The shift from probabilistic to deterministic execution for critical steps via scripts represents a broader pattern worth adopting across agentic systems: identify fragile operations (math, validation, state mutations) and hard-code them rather than relying on LLM reasoning
- As the agentskills.io standard gains traction across platforms like Claude Code and OpenAI's Codex, expect a growing ecosystem of both high-quality community skills and supply chain attack vectors, making skill provenance and auditability a competitive differentiator for enterprise AI platforms
Disclaimer: The above content is generated by AI and is for reference only.