## Sources

1. [Agent Skills Work but the Research Shows Most Teams Are Building Them Wrong](https://www.oreilly.com/radar/agent-skills-work-but-the-research-shows-most-teams-are-building-them-wrong/)

---

### Agent Skills Work but the Research Shows Most Teams Are Building Them Wrong – Aishwarya Naresh Reganti, Prahitha Movva, and Kiriti Badam

The source examines the emergence of **"agent skills"** as a standard for AI agents and highlights critical research findings that demonstrate how most development teams are currently mismanaging their implementation [1, 2].

**Main Arguments**
*   **Curation Over Automation:** While model-generated skills are a tempting shortcut, they consistently fail to provide the same performance benefits as **human-curated skills**, which capture specific organizational knowledge models lack [3, 4].
*   **Architecture Matters for Scaling:** A "flat" library of skills becomes unreliable as it grows, leading to **"routing collapse"** where agents cannot distinguish between similar-sounding tools [5].
*   **Skills as Code:** Agent skills should not be treated as static prompts but as maintained software artifacts that require a full lifecycle of evaluation, updates, and eventual **deprecation** [6, 7].
*   **Security is a Critical Gap:** A significant portion of community-sourced skills contain exploitable vulnerabilities, meaning importing skills without audit is a major security risk [2, 8].

**Key Takeaways**
*   **Performance Boost:** Curated skills improved agent task success rates by **16.2% on average**, with some domains like healthcare seeing gains as high as 52% [2, 3].
*   **Failure of Self-Generation:** Research shows that AI models cannot reliably author the procedural knowledge they benefit from; self-generated skills provided **no consistent benefit** across tested configurations [2, 3].
*   **The Hierarchy Solution:** To prevent retrieval errors in large libraries, skills should be organized into **hierarchical "capability trees"** rather than flat directories [9].
*   **Vulnerability Statistics:** Approximately **26.1% of community-sourced skills** contain vulnerabilities such as prompt injection, data exfiltration, or privilege escalation [2, 8].
*   **Focused Scope:** Skills with **two to three modules** consistently outperform comprehensive, broad documentation [10, 11].

**Important Details**
*   **What a Skill Is:** In practice, a skill is a folder containing a `SKILL.md` file that defines trigger conditions and step-by-step instructions, along with optional scripts [12].
*   **Progressive Disclosure:** Unlike system prompts that load everything at once, skills use **progressive disclosure**; only the name and description load at startup (~100 tokens), while full instructions load only when the skill is activated, saving context budget [13].
*   **Skills vs. MCP:** The source distinguishes between the Model Context Protocol (MCP) and skills by noting that **MCP provides the "runner" or abilities** (like API access), while **skills encode the knowledge** of how to use those abilities for specific workflows [13].
*   **Cost Implications:** Curated skills allow **smaller models** to match the performance of larger models that are running without skills, offering a potential path for cost-effective scaling [10].
*   **The Three-Step Improvement Plan:**
    1.  **Write from execution:** Build skills by manually correcting an agent during a workflow and then extracting the successful path [14].
    2.  **Description as routing:** Treat the skill description as the primary logic for triggering; if a skill fails to fire, the description is usually the problem [14].
    3.  **Lifecycle maintenance:** Regularly test if a skill is still useful; if a model's native capabilities have improved to match the skill's output, the skill should be retired to avoid overriding better native behavior [15].
*   **SkillOrchestra Concept:** In multi-agent systems, agents should maintain **"competence profiles"** based on their execution history so the system can route tasks based on proven success rates rather than just raw model capability [16].