[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"doc-detail-82612-en":3,"doc-seo-82612-105":29,"detail-sidebar-cat-0-en-105":91},{"code":4,"msg":5,"data":6},0,"success",{"doc_id":7,"user_id":8,"nickname":9,"user_avatar":10,"doc_module":4,"category_id":11,"category_name":12,"doc_title":13,"doc_description":14,"doc_content":15,"file_id":16,"file_url":17,"file_type":18,"file_size":19,"view_count":20,"is_deleted":4,"is_public":20,"is_downloadable":20,"audit_status":20,"page_count":21,"language":22,"language_code":23,"site_id":24,"html_lang":23,"table_of_contents":25,"faqs":26,"seo_title":13,"seo_description":14,"update_tm":27,"read_time":28},82612,8796095360427,"Lucas Martin","https://ap-avatar.wpscdn.com/davatar_994ba38a5ba835b3df7d355c54d3ed8d",8,"Research & Report","From Anatomy to Smells An Empirical Study of SKILL.md in Agent Skills","Agent Skills deliver on-demand domain knowledge to LLM agents without model retraining, relying on a required SKILL.md file with metadata and an unconstrained Markdown body. Despite rapid adoption, existing work has not clarified how these files are authored or whether guidelines are followed. This study qualitatively analyzes 238 real-world skills, deriving a taxonomy of semantic components, then identifies best practices and defines “skill smells” as violations. An automated detector shows 99%+ of skills contain at least one skill smell, and smells persist as skills evolve.","From Anatomy to Smells: An Empirical Study of  \n[SKILL.md](SKILL.md) in Agent Skills  \nDavid Boram Hong  \nUniversity of California, Irvine Irvine, USA [dbhong@uci.edu](dbhong@uci.edu)  \nAaron Imani  \nUniversity of California, Irvine Irvine, USA [aaron.imani@uci.edu](aaron.imani@uci.edu)  \nIftekhar Ahmed  \nUniversity of California, Irvine Irvine, USA [iftekha@uci.edu](iftekha@uci.edu)  \narXiv :2607 .0 1456v2 [ cs . SE] 3 Jul 2026  \nAbstract—Agent Skills provide on-demand domain knowledge to LLM agents without requiring model retraining. Each Agent Skill is defined by a mandatory SKILL .md file containing metadata and an unstructured Markdown body whose contents are left entirely to the skill author. Despite the rapid adoption of Agent Skills, little is known about how these files are authored or whether existing authoring guidelines are followed in practice. In this paper, [we present the first systematic study of](we present the first systematic study of SKILL.md)[ SKILL.md](we present the first systematic study of SKILL.md)[ ](we present the first systematic study of SKILL.md)files as a software artifact. We qualitatively analyze 238 realworld skills and derive a taxonomy of 13 higher-level and 44 lower-level semantic components. We then conduct a multivocal literature review of 29 sources to identify best practices for authoring SKILL .md files and introduce skill smells as violations of these practices. Finally, we develop an automated detector and apply it to real-world skills, [finding that over 99% of](finding that over 99% of SKILL.md)[ SKILL.md](finding that over 99% of SKILL.md)[ ](finding that over 99% of SKILL.md)files contain at least one skill smell, and once introduced, skill smells rarely disappear as skills evolve. These findings reveal a substantial gap between recommended and actual authoring practices, motivating the development of automated techniques to remediate skill smells while increasing developer awareness of this emerging quality issue.  \nIndex Terms—agent skill, [SKILL.md](SKILL.md)  \nI. INTRODUCTION  \nWith the recent growth of autonomous software agents, such as Claude Code [1] and GitHub Copilot [2], that use Large Language Models (LLMs) to perform Software Engineering (SE) tasks, the ability to provide agents with task-specific and project-specific knowledge has become increasingly important. Agent Skills 1 [3] address this need by packaging procedural knowledge together with organization-, team-, and userspecific context into portable, version-controlled artifacts that agents can retrieve on demand. As evidenced by the emergence of public skill marketplaces containing more than 100,000 skills [4], [5], skills have become a widely adopted mechanism for adapting general-purpose agents to specialized tasks.  \nOriginally introduced by Anthropic [3], the Agent Skill Specification defines a skill as a directory containing a required SKILL.md file and optional scripts, references, and assets [6] . The SKILL .md file consists of frontmatter, a metadata header in YAML format [7] with a set of predefined supported fields [6], which helps agents identify and load relevant skills, and a Markdown body containing skill instructions. Figure 2 shows an excerpt [from a](from a SKILL.md)[ SKILL.md](from a SKILL.md) body alongside two  \n1We use “skill” and “Agent skill” interchangeably.  \nexcerpts from frontmatter sections. Beyond these structural requirements, skill authors are free to include any content that helps agents perform the target task effectively.  \nThe largely unconstrained nature of [SKILL.md](SKILL.md) body and content create the potential for substantial variation in skill quality. Because skills directly contribute to the context provided to agents, poorly written skills may introduce irrelevant information, omit important guidance, or present instructions in ineffective ways, ultimately resulting in suboptimal agent behavior. Such effects may impact not only task performance but also resource c","cbCainqYAQtyENTN","https://ap.wps.com/l/cbCainqYAQtyENTN","pdf",2438116,1,12,"English","en",105,"# Introduction\n## Agent Skills and the SKILL.md specification\n## Motivation: quality variation and practice gaps\n## Research question and study focus","[{\"question\":\"What is the purpose of Agent Skills and the SKILL.md file?\",\"answer\":\"Agent Skills provide procedural, task-specific knowledge to LLM agents via portable artifacts. Each skill requires a SKILL.md file that combines YAML metadata with an instruction-focused Markdown body.\"},{\"question\":\"How does the paper study real-world SKILL.md authoring practices?\",\"answer\":\"It qualitatively analyzes 238 existing skills to derive a taxonomy of semantic components. It also reviews 29 sources to extract best practices and define “skill smells.”\"},{\"question\":\"What did the automated detector reveal about skill smells?\",\"answer\":\"The detector finds that over 99% of SKILL.md files contain at least one skill smell, and once introduced, these smells rarely disappear as skills evolve.\"}]",1784181810,30,{"code":4,"msg":30,"data":31},"ok",{"site_id":24,"language":23,"slug":32,"title":13,"keywords":33,"description":14,"schema_data":34,"social_meta":86,"head_meta":88,"extra_data":90,"updated_unix":27},"from-anatomy-to-smells-an-empirical-study-of-skillmd-in-agent-skills","",{"@graph":35,"@context":85},[36,53,68],{"@type":37,"itemListElement":38},"BreadcrumbList",[39,43,47,50],{"item":40,"name":41,"@type":42,"position":20},"https://docshare.wps.com","Home","ListItem",{"item":44,"name":45,"@type":42,"position":46},"https://docshare.wps.com/document/","Document",2,{"item":48,"name":12,"@type":42,"position":49},"https://docshare.wps.com/document/research-report/",3,{"item":51,"name":13,"@type":42,"position":52},"https://docshare.wps.com/document/from-anatomy-to-smells-an-empirical-study-of-skillmd-in-agent-skills/82612/",4,{"url":51,"name":13,"@type":54,"author":55,"headline":13,"publisher":57,"fileFormat":60,"inLanguage":23,"description":14,"dateModified":61,"datePublished":62,"encodingFormat":60,"isAccessibleForFree":63,"interactionStatistic":64},"DigitalDocument",{"name":9,"@type":56},"Person",{"url":40,"name":58,"@type":59},"DocShare","Organization","application/pdf","2026-07-17","2026-07-16",true,{"@type":65,"interactionType":66,"userInteractionCount":20},"InteractionCounter",{"@type":67},"ViewAction",{"@type":69,"mainEntity":70},"FAQPage",[71,77,81],{"name":72,"@type":73,"acceptedAnswer":74},"What is the purpose of Agent Skills and the SKILL.md file?","Question",{"text":75,"@type":76},"Agent Skills provide procedural, task-specific knowledge to LLM agents via portable artifacts. Each skill requires a SKILL.md file that combines YAML metadata with an instruction-focused Markdown body.","Answer",{"name":78,"@type":73,"acceptedAnswer":79},"How does the paper study real-world SKILL.md authoring practices?",{"text":80,"@type":76},"It qualitatively analyzes 238 existing skills to derive a taxonomy of semantic components. It also reviews 29 sources to extract best practices and define “skill smells.”",{"name":82,"@type":73,"acceptedAnswer":83},"What did the automated detector reveal about skill smells?",{"text":84,"@type":76},"The detector finds that over 99% of SKILL.md files contain at least one skill smell, and once introduced, these smells rarely disappear as skills evolve.","https://schema.org",{"og:url":51,"og:type":87,"og:title":13,"og:site_name":58,"og:description":14},"article",{"robots":89,"canonical":51},"index,follow",{"doc_id":7,"site_id":24},{"code":4,"msg":5,"data":92},[93,97,101,105,110,115,120,122,127,130,134],{"id":20,"doc_module":4,"doc_module_name":45,"category_name":94,"show_sort_weight":95,"slug":96},"Story & Novel",90,"story-novel",{"id":46,"doc_module":4,"doc_module_name":45,"category_name":98,"show_sort_weight":99,"slug":100},"Literature",80,"literature",{"id":52,"doc_module":4,"doc_module_name":45,"category_name":102,"show_sort_weight":103,"slug":104},"Exam",70,"exam",{"id":106,"doc_module":4,"doc_module_name":45,"category_name":107,"show_sort_weight":108,"slug":109},5,"Comic",60,"comic",{"id":111,"doc_module":4,"doc_module_name":45,"category_name":112,"show_sort_weight":113,"slug":114},6,"Technology",50,"technology",{"id":116,"doc_module":4,"doc_module_name":45,"category_name":117,"show_sort_weight":118,"slug":119},7,"Healthcare",40,"healthcare",{"id":11,"doc_module":4,"doc_module_name":45,"category_name":12,"show_sort_weight":28,"slug":121},"research-report",{"id":123,"doc_module":4,"doc_module_name":45,"category_name":124,"show_sort_weight":125,"slug":126},9,"Religion & Spirituality",20,"religion-spirituality",{"id":125,"doc_module":4,"doc_module_name":45,"category_name":128,"show_sort_weight":125,"slug":129},"World Cup","world-cup",{"id":131,"doc_module":4,"doc_module_name":45,"category_name":132,"show_sort_weight":131,"slug":133},10,"Lifestyle","lifestyle",{"id":135,"doc_module":4,"doc_module_name":45,"category_name":136,"show_sort_weight":106,"slug":137},19,"General","general"]