SKILL.md: Agent Skill Specification

• SKILL.md is a file-level specification that combines YAML metadata with a Markdown body to package and expose agent skills.
• It functions as a discovery manifest, runtime instruction source, and governance object within LLM-based agent systems.
• Empirical studies reveal inconsistent schema adoption and security risks, underscoring the need for layered verification and defense mechanisms.

Searching arXiv for the cited SKILL.md and agent-skill papers to ground the article in current literature. to=arxiv_search.search ￣奇米json {"query":"SKILL.md agent skills (Chen et al., 15 Jun 2026, Saha et al., 12 May 2026, Kim et al., 12 Jun 2026, Hong et al., 1 Jul 2026)", "max_results": 10} SKILL.md is the principal specification artifact used to package and expose “agent skills” in contemporary LLM-based agent systems. Across the recent literature, it is consistently described as a root-level file that combines machine-readable metadata with a free-form Markdown body containing procedural instructions, usage guidance, examples, and references; it is typically colocated with scripts, assets, and auxiliary resources inside a skill directory. In practice, SKILL.md serves at least three roles simultaneously: a discovery manifest for registries, a runtime instruction source for the agent, and a governance object for scanning and verification. This convergence makes it a central abstraction for modular capability extension, but also a first-class attack surface in agentic AI ecosystems (Xu et al., 12 Feb 2026, Saha et al., 12 May 2026, Chen et al., 15 Jun 2026).

1. Definition, schema, and file-level organization

The common structural pattern is a two-part document: a YAML frontmatter or metadata block followed by a Markdown body. A survey formalizes this as a simple grammar,

$$\langle \text{skill\_file}\rangle ::= \langle \text{frontmatter}\rangle \langle \text{body}\rangle,$$

with the frontmatter carrying key–value metadata and the body carrying procedural content (Xu et al., 12 Feb 2026). Closely related descriptions appear across empirical and systems papers: a skill is a self-contained package whose center is SKILL.md, alongside optional scripts, binaries, references, templates, or other assets (Chen et al., 15 Jun 2026, Gao et al., 1 Jul 2026, Hong et al., 1 Jul 2026).

The exact metadata schema is not uniform across frameworks. The survey literature lists fields such as name, version, author, description, trigger_patterns, dependencies, interfaces, and permissions (Xu et al., 12 Feb 2026). An empirical anatomy study of 238 real-world skills identifies required keys name, version, description, author, license, and interface in its corpus model (Hong et al., 1 Jul 2026). By contrast, a large-scale mining study of registry and personal-use skills reports that name and description exhibit at least 99% conformance, while fields such as license, compatibility, and metadata appear only in 3–16% of observed skills, and fields such as version, inputs, outputs, or dependencies appear in under 10% of observed skills (Gao et al., 1 Jul 2026). These results indicate an ecosystem with a recognizable file idiom but only partial schema convergence.

The Markdown body is correspondingly heterogeneous. Studies identify recurrent sections such as description, usage or invocation, examples, workflow or steps, scripts, references, limitations, support channels, and changelogs (Hong et al., 1 Jul 2026, Gao et al., 1 Jul 2026). The flexibility of an unstructured body is repeatedly justified in the literature by expressiveness and low author friction, but that same flexibility also means that SKILL.md frequently contains operational instructions rather than passive prose (Hong et al., 1 Jul 2026, Saha et al., 12 May 2026).

2. Runtime semantics and operational role

A defining property of SKILL.md is that it participates directly in agent execution. In one formalization, the backbone model first performs skill selection,

$$\langle s^*, a \rangle = \mathcal{M}(p, \mathcal{H}, S),$$

where $p$ is the user prompt, $\mathcal{H}$ the conversation history, and $S$ the available skills, and then executes the selected skill via

$\mathcal{Y} = \mathcal{A}(s^*, a),$

with the agent consulting SKILL.md when it needs clarifications on usage (Chen et al., 15 Jun 2026). Other work models execution through progressive disclosure: metadata may be loaded first, then high-level headings and summaries, and finally full procedural details and code blocks if needed (Xu et al., 12 Feb 2026).

This runtime role is implemented differently across systems. Registry-oriented designs often expose only name and description initially, then fetch the full SKILL.md on demand to keep prompt contexts compact (Saha et al., 12 May 2026, Ouyang et al., 5 May 2026). By contrast, OpenClaw injects the full contents of every enabled SKILL.md into the system-prompt portion of each LLM API call, even if the corresponding skill is never invoked (Dong et al., 1 Mar 2026). In the SKILLS telecommunications benchmark, the entire SKILL.md is injected into the system prompt for the “with-skill” condition so that multi-API workflows follow deterministic, version-controlled guidance rather than unconstrained reasoning (Brett, 16 Mar 2026).

Because SKILL.md can encode workflow logic, API patterns, business rules, and output formats, it often functions as a declarative control layer for tool use. In telecom operations, structured skill guidance produces consistent pass-rate lift across 37 scenarios spanning 8 TM Forum Open API domains: MiniMax M2.5 reaches 81.1% with-skill with a +13.5 percentage-point lift, Nemotron 120B 78.4% with +18.9 percentage points, GLM-5 Turbo 78.4% with +5.4 percentage points, and Seed 2.0 Lite 75.7% with +18.9 percentage points (Brett, 16 Mar 2026). This establishes SKILL.md as a mechanism for externalizing procedural knowledge rather than merely annotating code.

3. Content anatomy, documentation practice, and authoring quality

Systematic study of SKILL.md as a software artifact has produced a detailed content taxonomy. A qualitative analysis of 238 skills derives 13 higher-level and 44 lower-level semantic components, covering identification, summary, interface specification, examples, configuration, dependencies, error handling, limitations and caveats, versioning and changelog, authors and support, licensing and legal, references, and appendix material (Hong et al., 1 Jul 2026). A separate thematic analysis of 180 skills groups content into six broader themes: scoping and orchestrating the task; running the execution lifecycle; ensuring output quality; governing agent conduct; grounding domain knowledge; and user/agent coordination (Gao et al., 1 Jul 2026).

Best-practice guidance in the literature emphasizes explicitness and predictable layout. A multivocal review of 29 sources recommends section ordering beginning with Summary, Interface, and Examples; Markdown tables for inputs and outputs; both minimal snippets and end-to-end scenarios; explicit error contracts; semantic versioning with a human-readable changelog; and visible license and support information (Hong et al., 1 Jul 2026). Contractual-skill work generalizes this into a richer task-contract view in which goals, input boundaries, permissions, human approval points, evidence requirements, output contracts, quality bars, verification steps, and handoff rules become named sections within the skill artifact (Liu, 21 May 2026).

Empirical evidence suggests that real SKILL.md quality often falls short of these recommendations. A rule-based detector applied to 238 skills finds that 99.2% contain at least one “skill smell,” with a mean of 3.8 smells per file; the top three are Missing Summary (86%), No Usage Example (72%), and Ambiguous Interface (68%) (Hong et al., 1 Jul 2026). A user-comprehension study over 878 cybersecurity skills measures four “comprehension anchors”: operational basis, output contract, boundary disclosure, and example capability demonstration. Operational basis cues are present in 809 of 878 skills (92.1%), output contract in 553 (63.0%), boundary disclosure in 451 (51.4%), example demonstration in only 167 (19.0%), and all four anchors in only 20 skills (2.3%) (Wen, 19 May 2026). The DNS/C2 subset in that study further reports that only one of six skills included a concrete JSON example, while the others required helper-code inspection to recover command arguments or output fields (Wen, 19 May 2026).

Large-scale maintenance studies show that SKILL.md also behaves like a conventional reusable artifact. Across 18,463 public-registry skills and 23,199 personal-use skills mined from 5,876 GitHub repositories, 3,709 reuse links are identified; most reused skills remain near-verbatim, 53% are never modified after adoption, and subsequent local maintenance is overwhelmingly additive (Gao et al., 1 Jul 2026). A plausible implication is that the initial structure and wording of SKILL.md often persist downstream with little correction, increasing the long-term significance of early authoring choices.

4. Security model and attack surface

The security literature treats SKILL.md as a structural risk factor because it collapses the boundary between declarative metadata, human-readable documentation, and executable instruction text. A lifecycle analysis organizes the attack surface across Creation, Distribution, Deployment, and Execution, and derives a threat taxonomy of seven categories and seventeen scenarios across three layers: delivery and trust establishment, runtime attack, and persistence and lateral impact (Li et al., 3 Apr 2026). The same work argues that the most severe threats arise from architectural properties of the framework itself, including the absence of a data-instruction boundary, a single-approval persistent trust model, and the lack of mandatory marketplace security review (Li et al., 3 Apr 2026).

Registry-facing attacks demonstrate that SKILL.md can be manipulated before runtime. In Discovery, short beam-searched trigger sequences appended to SKILL.md improve embedding-based visibility, achieving an 86.14% pairwise win rate, an average boost of approximately 16.4%, and Top-10 placement of 80.0% under OpenAI embedding search; in Selection, description-only framing biases agents toward adversarial variants in 77.6% of paired trials on average; in Governance, semantic evasion yields avoidance of a blocking verdict in 36.5% to 100% of cases depending on technique, with context-window overflow reaching 87.1% clean and 0% malicious in that setting (Saha et al., 12 May 2026). These results show that SKILL.md affects admission, surfacing, selection, and review before any helper code runs.

Execution-time attacks exploit the same file as operational prompt material. “Dynamic Malicious Skills” show that if malicious instructions are injected into SKILL.md, the agent can be induced to edit benign code into a malicious version at runtime. Across 300 real-world Python skills, OpenHands and Claude Code, and backbones including Qwen3-8B, Qwen3.6-35B, GPT-4o-mini, GPT-5, and Sonnet 4.6, the attack obtains average ASR values of 18.7%, 41.6%, 41.8%, 43.7%, and 19.0%, respectively; simple loop-based exploits such as Response Time Amplification consistently exceed 60% ASR on most large models (Chen et al., 15 Jun 2026). The same paper isolates three prompt-engineering components—prerequisite framing, entry-script grounding, and wrapper-pierce—and reports that removing the wrapper-pierce component drops ASR from 31.1% to 7.8% in the cited ablation (Chen et al., 15 Jun 2026).

Other attacks target cost and availability rather than code mutation. Clawdrain embeds a “Segmented Verification Protocol” in SKILL.md and uses a companion tool that emits PROGRESS, REPAIR, and TERMINAL, producing 6–7x token amplification over a benign baseline on Gemini 2.5 Pro, with a failure configuration reaching approximately 9x (Dong et al., 1 Mar 2026). The paper also identifies SKILL.md prompt bloat, persistent tool-output pollution, cron or heartbeat frequency amplification, and behavioral instruction injection as additional production vectors in OpenClaw (Dong et al., 1 Mar 2026).

Cross-modal attacks further widen the threat model. SkillMutator treats the skill as a language-and-code joint object and shows that attacks emerging from discrepancies between SKILL.md and bundled code are poorly detected by existing scanners: open-source and commercial skill scanners detect only 2%–8% and 9%–17% of such attacks, respectively, on the benchmarked settings (Kim et al., 12 Jun 2026). This is important because many malicious behaviors are not visible from code-only or prompt-only inspection in isolation.

5. Governance, verification, and defense mechanisms

The dominant conclusion of the defensive literature is that no single scanner or prompt policy suffices. A sanitized corpus of 67,453 latest public OpenClaw skill versions shows strong scanner disagreement: 35,600 skills are flagged by at least one scanner, yet any scanner pair overlaps on at most 10.4% of their combined positives, only 0.69% of skills are flagged by all three scanners, and 81.9% of flagged skills are identified by exactly one scanner (Koc et al., 31 May 2026). SkillSpector is positive for 19,209 of 25,504 suspicious rows (75.3%) but only 14 of 206 malicious rows (6.8%), whereas VirusTotal is positive for 150 of 206 malicious rows (72.8%) (Koc et al., 31 May 2026). The implication drawn in that paper is explicit: skill-security requires layered governance, not single-scanner allow/block decisions.

Several papers therefore propose multi-stage governance. The survey literature describes four sequential verification gates—static analysis and dependency scanning, LLM-based intent-versus-implementation checks, sandbox behavioral testing, and permission manifest validation—mapped to four trust tiers that control how much of a skill is loaded and what authority it receives (Xu et al., 12 Feb 2026). Contractual skills reinterpret SKILL.md as a governance layer rather than a standalone safety mechanism, and in a public-skill A/B expansion over eight public skills, forty-eight synthetic tasks, and six models, contractual rewrites raise mean quality from 4.692 to 4.914 and reduce critical-error rate from 0.083 to 0.013 (Liu, 21 May 2026). This does not eliminate runtime risk, but it makes intent, boundaries, and acceptance criteria explicit enough for downstream tooling.

At the detection layer, SkillMutator introduces a four-phase reasoning-trajectory distillation framework for install-time scanning. On the strongest subset of its benchmark ($n=76$), a distilled Qwen2.5-Coder-7B-Instruct scanner improves detection from 17.1% to 88.2%, surpassing GPT-4o-mini at 23.7% and GPT-5.4-mini at 79.0%, and slightly exceeding GPT-5.4 at 86.8% in the reported evaluation (Kim et al., 12 Jun 2026). Formal-verification work pushes further by defining capability containment over a two-sided semantics and composing three mechanisms—abstract interpretation over script-side effects, refinement types for tool-call envelopes, and SMT-bounded model checking—into a proof-carrying bundle attached to the skill artifact (Metere, 9 May 2026).

System hardening is particularly effective when it prevents mutation rather than merely instructing the model not to mutate. In the dynamic-malicious-skills setting, a prompt-based “IMPORTANT SECURITY POLICY” reduces average ASR from 41.6% to 21.4%, but some behaviors still succeed 47% of the time; an OS-level defense using Bubblewrap read-only mounts plus a copy monitor reduces ASR for every malicious behavior to 0% and preserves SHA-256 equality of the skill code before and after execution (Chen et al., 15 Jun 2026). This difference is consistent with the broader literature: architectural controls outperform instruction-only controls when SKILL.md itself is the injected authority surface.

6. Compilation, learned representations, maintenance, and research directions

Recent work increasingly treats SKILL.md not as a fixed text file but as a compilable or learnable intermediate artifact. SkCC introduces a compiler pipeline that lowers SKILL.md into a strongly typed intermediate representation, SkIR, then emits platform-specific variants for Claude Code, Codex, Gemini, and Kimi. The paper argues that this reduces adaptation work from $O(m \times n)$ to $O(m + n)$, and reports pass-rate improvements from 21.1% to 33.3% on Claude Code and from 35.1% to 48.7% on Kimi CLI, with 10–46% runtime token savings, mean compilation latency of 8.93 ms, and a 94.8% compile-time security trigger rate on the evaluated corpus (Ouyang et al., 5 May 2026). This line of work treats the semantic content of SKILL.md as portable IR rather than framework-specific prompt text.

A complementary direction compresses behavior rather than formatting. Skill-to-LoRA converts a skill’s procedural effect into a skill-specific adapter learned offline from synthetic demonstrations generated using the full SKILL.md. On a 21-skill subset of SWE-Skills-Bench with Qwen3.6-27B, the no-skill baseline passes 59 of 210 tasks (28.1%), Full Skill Text prompting passes 54 of 210 (25.7%), and Skill-to-LoRA passes 65 of 210 (31.0%); Full Skill Text increases per-step token cost by 13.39% relative to vanilla, while Skill-to-LoRA lowers it by 4.89%, yielding an approximately 6.6% saving relative to Full Skill Text prompting (Zhang et al., 15 Jun 2026). The reported Wrong-LoRA and Shared-LoRA controls indicate that the benefit depends on skill-specific alignment rather than generic parameter adaptation (Zhang et al., 15 Jun 2026).

Automatic generation of SKILL.md from interaction data remains less mature. A trajectory-mining pipeline for computer-using agents can discover readable clusters—five of eight clusters reach at least 0.95 purity against InteraSkill Workflows labels—but downstream policy gains are weak: GRPO improves IW skill-step accuracy only from 18.5% to 20.5%, underperforms trivial frequency priors on key source-domain metrics, and degrades transfer on WebArena from 55.8% to 44.2% (Hao et al., 18 Jun 2026). This suggests that inspectable skill structure can be mined from trajectories, but current segmentation, representation, and reward models are insufficient for robust transfer.

The broader research agenda now spans portability, capability-scoped permissions, verification, automated vetting, and maintenance tooling (Xu et al., 12 Feb 2026, Li et al., 3 Apr 2026). Empirical maintenance studies show that behavioral contracts embedded in SKILL.md—how a skill interacts with users, monitors runtime state, and recovers from failures—are almost untouched after reuse, while most edits target project-specific bindings, knowledge accretion, or presentation (Gao et al., 1 Jul 2026). This suggests that future tooling may profitably separate stable behavioral contracts from volatile environment-specific parameters, while retaining the readability and auditability that made SKILL.md attractive in the first place.