Available as an arXiv preprint. Journal or proceedings publication has not been verified.
Treat a skill as a software artefact.
This note connects skill authoring with software-engineering principles, including cohesion, interface design, coupling and behavioural evaluation. Its contribution is a conceptual framework and an authoring process.
Make reusable work legible and evaluable.
The practical question is which recurring task deserves a bounded, reusable skill and how the team will judge whether it works. The note supports an evaluation-led authoring approach; it does not establish a measured productivity gain.
A conceptual and practical research note.
Claude Code is used as the reference implementation. The document synthesises engineering principles and technical documentation rather than presenting a controlled comparative experiment. The full text includes diagrams and references.
Editorial context · The source paper remains the reference.
An agent skill is a software artefact: it has an interface, an implementation, dependencies and ways to fail. This research note asks what happens when we apply ordinary software-engineering discipline to authoring it.
Give each skill one coherent responsibility and a clear selection description.
Load detailed instructions and supporting resources only when they are needed.
Evaluate behaviour with representative tasks, then refine against observed failures.
A small interface with a large responsibility
The description is the interface through which an agent decides whether to select a skill. That selection is probabilistic. A useful description makes both the intended task and its boundaries explicit; instructions that are never selected cannot improve the result.
Design for the context budget
The note connects staged loading to separation of concerns. Metadata is available first, the skill body follows when selected, and supporting material can be read as needed. Keeping these layers distinct reduces the amount of context consumed before it is useful.
Evaluate before adding instructions
The proposed authoring process starts with representative tasks and success criteria. Run the skill, inspect the behaviour, and add the minimum guidance needed to address a real failure. The paper distinguishes behavioural evaluation from the repeatability expected of deterministic unit tests.
What the paper establishes
This is a conceptual and practical research note, using Claude Code as its reference implementation. It explains design principles and an authoring process; it does not report a controlled benchmark establishing a quantified productivity improvement. The supplied PDF includes the diagrams, mechanism comparisons and references.
Cite this paper
Giuseppe Destefanis. (2026). Authoring Agent Skills: A Software-Engineering Approach. Research note.
GD
University College London
Giuseppe Destefanis is an Associate Professor in UCL’s Department of Computer Science. His research spans empirical software engineering, mining software repositories and large language models. He uses data mining, machine learning and natural language processing to study how people, technical systems and economic incentives interact across digital platforms.