SKILL.md: Agent Skills Spec

• SKILL.md is a mandatory Markdown file that defines agent skills using metadata, instructions, and security controls.
• It employs a structured, progressive disclosure model to manage discovery, workflow guidance, and deep technical support.
• Research reveals that its design as a software artifact impacts agent behavior, reuse practices, and risk assessment.

SKILL.md is the canonical specification file in the emerging Agent Skills ecosystem: a mandatory Markdown-centered entry artifact inside a filesystem-backed skill directory, typically paired with YAML frontmatter and optional scripts, references, templates, or other assets. In current agent architectures, it functions simultaneously as discovery metadata, procedural guidance, a user-facing capability description, and a security-relevant control surface. Recent work therefore treats SKILL.md not merely as prompt text, but as an engineered software artifact whose structure, loading semantics, governance role, and attack surface materially influence agent behavior (Xu et al., 12 Feb 2026, Li et al., 3 Apr 2026, Wen, 19 May 2026).

1. Filesystem artifact and package structure

A skill package is typically a directory with SKILL.md at the root, plus optional executable helpers and supporting resources. The frontmatter commonly carries at least a name and description, while the Markdown body holds instructions, workflows, constraints, examples, and links to deeper assets. Empirical studies of AI coding skills describe this as a “structured context bundle” loaded on demand, usually with a short YAML header above a Markdown body; security analyses likewise treat SKILL.md as the required component of the package model (Xu et al., 12 Feb 2026, Gao et al., 1 Jul 2026, Li et al., 3 Apr 2026).

The dominant loading pattern is progressive disclosure. Level 1 exposes lightweight metadata for routing, Level 2 loads the full procedural body, and Level 3 exposes deeper assets such as scripts, references, templates, schemas, or other bundled files. This architecture is repeatedly presented as the reason skill systems can remain modular without preloading all domain knowledge into the context window (Xu et al., 12 Feb 2026, Bi et al., 12 Mar 2026).

Level	Loaded content	Role
1	metadata such as name, description, trigger conditions	discovery and routing
2	full SKILL.md instructions	workflow guidance
3	scripts, references, templates, schemas, assets	deeper technical support

This packaging model places SKILL.md between prompts and tools. It is not merely retrieved text, because it encodes procedural knowledge and sometimes permission assumptions; it is not merely a tool, because it prepares the agent to solve a class of tasks rather than executing a single function call (Xu et al., 12 Feb 2026).

2. Runtime semantics and behavioral role

At runtime, SKILL.md is the agent-visible layer that tells the model what to do. In software-engineering settings, the file shapes how the model searches repositories, chooses files, edits code, runs commands, and verifies completion. The same literature emphasizes that long skill documents repeatedly consume context budget, compete with repository evidence, and can introduce irrelevant or mismatched procedural bias when injected on every step of an agent loop (Zhang et al., 15 Jun 2026).

The runtime consequence is visible in domain benchmarks. In telecommunications operations, a portable SKILL.md is injected as system context in the with-skill condition and supplies prerequisites, ordered workflow steps, API call patterns, business rules, error handling guidance, and required output format. On the SKILLS benchmark, which spans 37 telecom operations scenarios across 8 TM Forum Open API domains, every evaluated model improves with skill augmentation, and the largest gains appear on the Complex tier, where logic is not inferable from schema alone (Brett, 16 Mar 2026).

The same loading semantics can also become an economic and control-flow liability. OpenClaw injects a skill’s Markdown documentation into the model’s system-prompt-level context whenever the skill is enabled, even if the skill is not invoked. Clawdrain exploits this by embedding a multi-turn “Segmented Verification Protocol” in a Trojanized SKILL.md, producing 6-7x token amplification over a benign baseline, with a costly failure configuration reaching approximately 9x (Dong et al., 1 Mar 2026).

3. Content, comprehension, and maintenance as a software artifact

Empirical work now studies SKILL.md as a software artifact rather than as incidental documentation. One qualitative analysis of 238 real-world skills derives a taxonomy of 13 higher-level and 44 lower-level semantic components, then combines that taxonomy with a multivocal literature review of 29 sources to define “skill smells” as violations of authoring best practices. Its automated detector finds that over 99% of SKILL.md files contain at least one skill smell, and that once introduced, skill smells rarely disappear as skills evolve (Hong et al., 1 Jul 2026).

A larger study of reuse and maintenance reinforces that characterization. It mines 18,463 skills from skills.sh and 23,199 personal-use skills from 5,876 GitHub repositories, identifying 3,709 reuse links. Reuse is largely a one-time copy operation: most reused skills remain near-verbatim, 70.3% of linked pairs have similarity at least 0.99, 53% are never modified after adoption, and additions outnumber removals by 2.7 to 1 (586 vs. 221). Across customization and evolution, the most stable element is a behavioral contract governing interaction with users, runtime-state monitoring, and failure recovery (Gao et al., 1 Jul 2026).

The user-facing side is often thinner than the agent-facing side. Across 878 cybersecurity skills, rule-based coding finds cues for operational basis in 92.1% of specifications, named output contracts in 63.0%, boundary disclosure in 51.4%, and example capability demonstration in only 19.0%; just 2.3% exhibit all four anchors together. The paper’s interpretation is explicit: many skills reveal what evidence or tools they rely on, but far fewer provide the bounded expectations and concrete first checks that help a person understand what the skill consumes, produces, and covers (Wen, 19 May 2026).

4. Transformations: prompting, compilation, and learned behavior

One line of research treats SKILL.md as supervision rather than as persistent runtime payload. Skill-to-LoRA (S2L) replaces the prompt-based form $y = M(x \oplus t_i)$ with adapter-conditioned inference $\hat{y}_i = (M + A_s)(x_i)$: the full SKILL.md is used offline to synthesize demonstrations, train a skill-specific LoRA adapter, and then omitted online while the corresponding adapter is dynamically loaded. On Qwen3.6-27B over a 21-skill subset of SWE-Skills-Bench, Vanilla LLM solves 59/210 tasks, Full Skill Text solves 54/210, and S2L solves 65/210; S2L also reduces token cost by 4.89% relative to Vanilla and by 6.6% relative to Full Skill Text (Zhang et al., 15 Jun 2026).

A second line treats SKILL.md as a compilable source artifact. SkCC introduces SkIR, a strongly-typed intermediate representation that separates skill semantics from platform-specific formatting, reduces adaptation complexity from $O(m \times n)$ to $O(m + n)$, and applies compile-time hardening through Anti-Skill Injection. On SkillsBench, compiled skills improve pass rates from 21.1% to 33.3% on Claude Code and from 35.1% to 48.7% on Kimi CLI, while achieving sub-10ms compilation latency, a 94.8% proactive security trigger rate, and 10-46% runtime token savings across platforms (Ouyang et al., 5 May 2026).

Automation can also synthesize SKILL.md from behavior traces. A three-stage pipeline for computer-using agents segments GUI trajectories, clusters segments into candidate skills, and trains a skill-aware policy from the resulting annotations. The resulting clusters are readable on the source benchmark—five of eight clusters have at least 0.95 purity against InteraSkill Workflows labels—but readability does not imply policy transfer: GRPO improves IW skill-step accuracy only from 18.5% to 20.5%, leaves BrowseComp+ essentially unchanged, and underperforms trivial frequency priors on key source-domain metrics (Hao et al., 18 Jun 2026).

5. Governance, disclosure, and contractual structuring

Recent enterprise-oriented work reframes SKILL.md as a readable task contract. The contractual-skills framework recommends organizing the body around sections such as When To Use, Goal, Audience, Inputs, Context, Workflow, Permissions, Human Gates, Constraints, Evidence, Output, Quality Bar, Verification, and Handoff, while keeping frontmatter light for discovery and preserving progressive loading. In this formulation, SKILL.md becomes a governance layer that makes boundaries, evidence requirements, and acceptance criteria explicit (Liu, 21 May 2026).

The empirical motivation is pragmatic rather than purely stylistic. In a public-skill A/B expansion, contractual rewrites raise mean quality from 4.692 to 4.914 and reduce critical-error rate from 0.083 to 0.013. An offline tool-calling challenge further suggests that contractual skills can reduce risky tool attempts, but should not be interpreted as a standalone safety mechanism; the paper is explicit that instructions express intent, whereas adapters and guardrails enforce it (Liu, 21 May 2026).

This governance view aligns with the argument that SKILL.md should be evaluated as a capability disclosure for users as well as an instruction container for agents. The central question becomes whether a reader can form bounded expectations about what a skill consumes, what it produces, what is outside scope, and how to construct a first local check from the specification itself (Wen, 19 May 2026).

6. Security, auditing, and formal verification

Security research treats SKILL.md as a first-class attack surface. A foundational threat analysis argues that the most severe risks arise from structural properties of the framework itself, notably the absence of a data-instruction boundary, a single-approval persistent trust model, and the lack of mandatory marketplace security review. It models the Agent Skill lifecycle across Creation, Distribution, Deployment, and Execution, and derives seven threat categories with seventeen scenarios, including typosquatting, repository hijacking, prompt injection, malicious script execution, credential harvesting, memory file poisoning, and prompt infection (Li et al., 3 Apr 2026).

SKILL.md-only manipulation can already alter the supply chain before execution. In registry discovery, short textual triggers can improve adversarial visibility, achieving 86.14% pairwise win rate and 80.00% Top-10 placement in the strongest setting. In paired selection, description-only framing causes functionally equivalent adversarial variants to be selected in 77.6% of trials on average. In governance, semantic evasion strategies allow malicious skills to avoid a blocking verdict in 36.5%-100% of cases, showing that natural-language edits alone can affect admission, surfacing, and review (Saha et al., 12 May 2026).

Execution-time attacks exploit the fact that documentation is part of the agent’s decision context. DyMalSkill embeds malicious instructions in SKILL.md so that the agent dynamically edits otherwise benign code during execution; across 12 malicious behaviors, average Attack Success Rate ranges from 18.7% on Qwen3-8B to 43.7% on GPT-5. A system-level defense based on OS kernel-enforced read-only mounts plus copy blocking reduces ASR to 0.0% while preserving successful task completion for all 300 benign skills (Chen et al., 15 Jun 2026). Cross-modal attacks go further by distributing malicious intent between language and code: on the strongest SkillMutator subset ($n=76$), open-source and commercial scanners detect only 2%-8% and 9%-17% of attacks, whereas a distilled Qwen2.5-Coder-7B-Instruct scanner reaches 88.2% detection (Kim et al., 12 Jun 2026).

Ecosystem-scale auditing remains difficult because security signals disagree and repository context changes interpretation. In ClawHub Security Signals, only 0.69% of 67,453 latest public OpenClaw skill versions are flagged by all three scanner families, and 81.9% of flagged skills are identified by a single scanner (Koc et al., 31 May 2026). Repository-aware reanalysis of 238,180 unique skills suggests that text-only classification overstates maliciousness: only 0.52% of 2,887 scanner-flagged skills remain in repositories that still look malicious in context, while 96% are embedded in repositories whose documentation and codebase align with the claimed skill functionality (Holzbauer et al., 17 Mar 2026).

Recent defenses accordingly move from single-file filtering toward package-level reasoning and proof-carrying artifacts. SkillGuard-Robust audits skills as structured packages over skill-md, script, reference, and repo-context roles, reaching 97.30% overall exact match and 98.33% malicious-risk recall on the 404-package held-out aggregate (Lv et al., 28 Apr 2026). At the strongest end of assurance, formal verification work defines the target property as capability containment, $\Pi_C(\tau(\mathit{sess})) \subseteq D$, and composes abstract interpretation, refinement typing of tool-call envelopes, and SMT-bounded model checking into a mechanically checkable proof bundle that extends the existing SKILL.md convention (Metere, 9 May 2026).

The resulting picture is that SKILL.md has become a central abstraction layer in agent systems precisely because it is both lightweight and expressive. That same combination makes it unusually consequential: it is an operational interface, a reusable knowledge package, a user-facing disclosure, and a semantic security boundary. Current research increasingly converges on a common conclusion: any adequate account of agent skills must treat SKILL.md as software, documentation, policy, and attack surface at once.