---
title: 'SKILL.md: Agent Skill Specification'
url: https://www.emergentmind.com/topics/skill-md
type: topic
---

# SKILL.md: Agent Skill Specification

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 2606.16287 2605.11418 2606.14154 2607.01456", "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 [2602.12430][2605.11418][2606.16287].

## 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 [2602.12430]. 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 [2606.16287][2607.00911][2607.01456].

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` [2602.12430]. An empirical anatomy study of 238 real-world skills identifies required keys `name`, `version`, `description`, `author`, `license`, and `interface` in its corpus model [2607.01456]. 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 [2607.00911]. 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 [2607.01456][2607.00911]. 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 [2607.01456][2605.11418].

## 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 [2606.16287]. 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 [2602.12430].

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 [2605.11418][2605.03353]. 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 [2603.00902]. 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 [2603.15372].

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 [2603.15372]. 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 [2607.01456]. 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 [2607.00911].

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 [2607.01456]. 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 [2605.22634].

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%) [2607.01456]. 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%) [2605.19362]. 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 [2605.19362].

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 [2607.00911]. 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 [2604.02837]. 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 [2604.02837].

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 [2605.11418]. 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 [2606.16287]. 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 [2606.16287].

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 [2603.00902]. 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 [2603.00902].

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 [2606.14154]. 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 [2606.01494]. 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%) [2606.01494]. 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 [2602.12430]. 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 [2605.22634]. 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 [2606.14154]. 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 [2605.23951].

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 [2606.16287]. 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 [2605.03353]. 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 [2606.16769]. The reported Wrong-LoRA and Shared-LoRA controls indicate that the benefit depends on skill-specific alignment rather than generic parameter adaptation [2606.16769].

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% [2606.20363]. 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 [2602.12430][2604.02837]. 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 [2607.00911]. 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.

Source: https://www.emergentmind.com/topics/skill-md