From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained

Abstract: AI coding agents increasingly rely on skills: structured context bundles, typically a SKILL$.$md file with a YAML header and Markdown body, loaded on demand for domain knowledge, workflows, and scripts. Public registries such as skills$.$sh now host tens of thousands of skills, making them an emerging unit of reuse in agent-based software engineering. Yet skills have largely been viewed as agent capabilities rather than software artefacts whose content and evolution shape agent behaviour. We present the first empirical study of AI agent skills as engineered artefacts that are authored, reused, customised and maintained, across public registries and personal-use repositories. We mined 18,463 skills from skills$.$sh and 23,199 personal-use skills from 5,876 GitHub repositories, identifying 3,709 reuse links. LLM-based classification into SWEBOK knowledge areas (KAs) shows Software Construction dominates alongside a long tail of specialised areas. A thematic analysis of 180 skills identifies six content categories. Qualitative coding of 444 modifications reveals six themes, of which reworking operational specifications and adapting knowledge and resources are the primary target of change. Our findings show that reuse is largely a one-time copy operation: most reused skills remain near-verbatim, 53% are never modified after adoption, and subsequent local maintenance is overwhelmingly additive. Customisation primarily adapts skills to local environments, whereas evolution accretes new inline domain knowledge. Across both, a stable behavioural contract - how a skill interacts with users, monitors runtime state, and recovers from failures - remains almost untouched. These results suggest maintenance effort should focus on project-specific bindings, and that registries and tool support should enable consolidating the domain knowledge skills re-author in isolation.

• The paper presents a large-scale empirical analysis of AI agent skills, revealing that 70.3% of local skills are adopted verbatim and remain largely unchanged.
• The study categorizes skills using SWEBOK, showing Software Construction dominates and centralised skills are more systematically packaged than local ones.
• The paper's analysis uncovers that maintenance of skills is primarily additive, emphasizing the need for improved tools to manage divergence in evolving agent contracts.

An Empirical Analysis of Authoring, Reuse, and Maintenance of AI Agent Skills

Study Design and Dataset Construction

The paper presents a large-scale empirical investigation into AI agent skills, focusing on their lifecycle as structured, reusable artifacts that are written, adapted, and maintained across centralised skill registries and individual software repositories. Agent skills are typically encapsulated as SKILL.md documents, pairing YAML-based metadata with markdown instructions and, optionally, scripts and assets. The study targets three primary questions: classification of software engineering knowledge (via SWEBOK KAs), characterization of skill packaging and content, and analysis of maintenance patterns during skill customisation and evolution.

The authors mined 18,463 centralised skills from the skills.sh registry and 23,199 personal-use skills from 5,876 GitHub repositories, constructing 3,709 reuse links between registry-published and locally used skills. The schema for dataset collection and subsequent RQ analysis is summarised below.

Figure 1: Study design encompassing dataset collection, SWEBOK classification (RQ1), packaging/content analysis (RQ2), and evolution/customisation analysis (RQ3).

Software Engineering Knowledge Areas in Skills

The SWEBOK classification of both centralised and personal-use skills reveals that Software Construction constitutes the largest category, capturing 28.3% of registry skills and 22.1% of personal-use skills. Domains such as Software Engineering Operations, Software Testing, and Software Configuration Management also appear, though less frequently. Notably, 28–30% of skills fall outside traditional SWEBOK areas, indicating a significant proportion of non-SE usage, including tasks such as speech synthesis.

A key finding is that centralised registries are enriched with broadly applicable, general-purpose skills covering construction, design, and architecture, whereas project-local skills focus on configuration, testing, and other phases tied directly to the host repository. This dichotomy is visualized in the KA distributions below.

Figure 2: SWEBOK knowledge-area breakdown of centralised and personal-use agent skills, highlighting the dominance of Software Construction and differing long-tail patterns.

Packaging and Content of AI Agent Skills

Analysis of SKILL.md packaging shows centralised skills are systematically longer (median 1,678 tokens) and more structured (median 19 headers) compared to their personal-use analogs (median 1,114 tokens, 13 headers). Personal-use skills display looser conformance: lower rates of directory-name/skill-name alignment and sparser inclusion of optional fields (e.g., license, compatibility). Centralised skills more frequently utilize reference, asset, and script directories, reflecting higher packaging discipline.

Figure 3: Statistical comparison of SKILL.md file lengths and header counts between centralised and personal-use skills.

Thematic analysis stratified over SWEBOK KAs identifies six stable content categories for agent skills:

• Scoping and orchestrating (universal: 100%),
• Running execution lifecycle,
• Ensuring output quality,
• Governing agent conduct,
• Grounding domain knowledge,
• User/agent coordination.

Most skills address the orchestration of tasks, execution specifics, conduct norms, and domain background. Output quality and user/agent interaction are more variable, featuring prominently in requirements engineering and less so in lower-level operational skills.

Adaptation, Customisation, and Maintenance Patterns

Empirical analysis of maintenance patterns shows that skill reuse predominantly operates as a one-off copy: 70.3% of personal-use skills linked to registries are adopted verbatim ($\geq$0.99 similarity), and 53% are never subsequently modified. When centralised and local skills both change post-adoption, 62.3% diverge independently rather than recombining, resulting in drift.

Qualitative coding of 444 skill diffs (customisation and evolution cases) yields six principal change categories:

1. Configuring skill metadata,
2. Reworking operational specifications (dominant target in evolution, p < 0.01),
3. Recalibrating behavioural constraints (more frequent during evolution, p < 0.05),
4. Adapting knowledge and resources,
5. Maintaining skill compatibility,
6. Polishing presentation and wording (more common during customisation, p < 0.01).

Operational edits are overwhelmingly additive; net change favors additions over removals by 2.7:1, and for evolution, by 6.1:1. Customisation focuses on aligning the skill with project realities (e.g., adapting references, removing registry metadata, refactoring for local tools), whereas evolution expands core knowledge and workflows, tuning constraints and updating inline explanatory content. The contract-like components—agent interaction, runtime monitoring, failure recovery—are rarely edited after initial skill adoption, indicating high behavioral stability.

Implications and Prospects

The distinction between centralised and local skills has actionable implications for both software engineering practice and tool/ecosystem design. Maintenance effort should prioritise local bindings and context specification, since these are the elements most frequently customized and likely to become out-of-date as surrounding infrastructure evolves. Registry providers should invest in agent-neutral packaging standards and prefilled templates, while research in automatic documentation mining, skill activation tracing, and balancing deterministic scripting versus natural-language expressivity becomes central to future tool support.

The convergence of domain-specific, project-bound skill evolution and predominantly static behavioral contracts suggests opportunities in both process mining (tracking and standardizing evolving SE knowledge) and LLM agent safety (guaranteeing contract stability under drift). The low rate of re-incorporation of upstream changes further distinguishes skill maintenance from conventional library evolution and dependency management, motivating renewed focus on downstream update dissemination for this artifact class.

Conclusion

This work provides the first systematic, empirical characterization of AI agent skill engineering, tracing the interplay between structured packaging, SWEBOK knowledge coverage, and concrete evolution patterns across more than 40,000 skills. Strong numerical findings include the prevalence of one-off copy reuse, predominance of additive local maintenance, and behavioral contract stability. These results establish agent skill artifacts as a distinct unit of engineering and reuse, driving new technical and research directions for both SE automation and agent ecosystem development.