Authoring Agent Skills: A Software-Engineering Approach | AI Paper Digest

TL;DR Highlight

Treating skills as software clarifies selection, staged loading, and when to use hooks instead.

Who Should Read

A developer whose Claude Code skills don't trigger automatically or get ignored once loaded.

Core Mechanics

A skill is software
- A skill is version-controllable files: SKILL.md plus scripts and reference docs.
- The description is the interface, and the body plus bundled files are the implementation.
The description is the trigger
- The model picks a skill based only on name and description.
- Write it in third person, stating what it does, when to use it, and concrete terms.
Loading happens in three stages
- At session start only metadata loads, about 100 tokens per skill.
- The body loads on selection, and reference files or scripts load only when needed.
Put must-hold rules in hooks
- Skills are probabilistic, so the model may skip them.
- Hooks run on runtime events every time, and PreToolUse hooks can block actions.
Judge skills by pass rate
- A skill only works with a model, so testing is integration-style rather than unit testing.

Evidence

No quantitative experiments
- This is a conceptual note, with no benchmark or accuracy numbers in the source.
Constraints and thresholds cited
- name is at most 64 characters and description at most 1024 characters.
- Metadata costs about 100 tokens per skill, and bodies should stay under about 500 lines.
Reference file guidance
- Add a table of contents to reference files over about 100 lines.
- Link references only one level deep from SKILL.md.

How to Apply

Rewrite your skill descriptions first
- Rewrite each description in third person with what it does, when to use it, and terms from real requests.
- Change 'Handles releases' into 'Drafts release notes from… Use when…'.
Move must-hold rules into hooks
Find rules in skill bodies that say 'must always'.
Register rules like pre-commit validation or post-write formatting as hooks in .claude/settings.json. Block dangerous commands in PreToolUse with exit code 2.
Write evaluations before the skill
- Run representative tasks without the skill, record failures, and turn them into test cases.
- Write the minimum instructions to pass them, then check triggering with a fresh instance and iterate.
Vet third-party skills before installing
- Read SKILL.md, bundled scripts, referenced resources, and external URLs against the stated purpose.
- Be extra careful with skills that read local files or send data outside.

Try It

copy & run

# Paste into Claude or Claude Code: simplified version of the paper's method (skill description audit)

Review the frontmatter and body of the SKILL.md below.

{{full SKILL.md content}}

Checklist:
1. Is the description in third person?
2. Does it state both what it does and when to use it?
3. Does it include concrete terms a real request would contain?
4. Is name at most 64 characters, using only lowercase letters, numbers, and hyphens?
5. Is the body within about 500 lines with no explanations of things the model already knows?
6. Are reference files linked only one level deep from SKILL.md?
7. Flag any must-hold rules written in the body as candidates to move into hooks.

Mark each item pass/fail and suggest rewritten text for failures.

Next step: generate 5 requests that should trigger this skill and 5 that should not.

Terminology

Agent SkillA folder of task instructions an agent loads on demand. It consists of one SKILL.md file plus optional supporting files.

Progressive disclosure (staged loading)Like opening a book's table of contents, then chapter, then appendix only when needed. Metadata, body, and bundled files enter context in that order.

HookA shell command the runtime always runs at fixed points like before or after a tool call. It runs regardless of what the model decides.

PreToolUseA hook event that fires right before the agent runs a tool. It can inspect the action and block dangerous ones.

MCPA cross-vendor protocol for connecting agents to external services and data.

Related Papers

Original Abstract (Expand)

Agent Skills are an emerging way to extend large language model agents with reusable procedural knowledge that the agent loads on demand. Anthropic introduced Agent Skills and published the format as an open specification supported across several agent tools. This note argues that a skill is a software artefact and that its construction should follow software-engineering principles, with qualifications: single responsibility, separation of interface from implementation, low coupling, and economy in a shared token budget, together with behavioural evaluation in place of deterministic testing. Using Claude Code as the reference implementation, it describes how a skill is structured, how its contents are loaded in stages, and how to write the description on which selection depends. It places skills against the other mechanisms a developer can use to shape agent behaviour, like project memory files, slash commands, subagents, external tool connections, and hooks, and gives a rule for choosing between them based on who decides that a mechanism runs and what guarantee it provides. It then sets out an evaluation-driven authoring process, a set of patterns and faults commonly encountered in authoring, and the trust question raised by using skills from third parties. We illustrate the comparison drawn in UML class style, the loading model, the anatomy of a skill, the relative position of each mechanism, and the points at which skills and hooks act during a session.