SKILL.md Went Cross-Platform — So Did Its Malware Wave

Last updated: September 9, 2026 · 6-minute read

One folder, one Markdown file, three competing AI platforms that all read it. Agent Skills started as a Claude feature in October 2025, became an open standard in December, and by February 2026 its largest community marketplace had a confirmed malware problem — 341 malicious skills, caught by security researchers. A technology does not qualify as infrastructure until attackers depend on it too. By that standard, SKILL.md has arrived.

What a skill actually is

The spec is refreshingly boring. A skill is a directory containing a SKILL.md file — YAML frontmatter plus a Markdown body. Optional siblings include a scripts/ folder for executable code, references/ for documentation the agent loads on demand, and assets/ for templates. The design principle is progressive disclosure: the frontmatter description is always in the agent's context, while the body and reference files only load when the task actually needs them.

The frontmatter contract, straight from agentskills.io:

Two of those constraints carry more weight than they look like they do. The name-matches-directory rule kills an entire class of copy-paste drift where a folder says one thing and its metadata says another. And the description is not documentation — it is a router. The agent reads it to decide whether the skill loads at all, so "Helps with PDFs" is functionally a dead skill, while a description stuffed with the task keywords a user would actually type is what gets the skill summoned. The spec's own guidance says the same: describe both what the skill does and when to use it.

The MCP playbook, rerun

The adoption arc is a near-sequel of Model Context Protocol's. Anthropic shipped Agent Skills as a Claude feature on October 16, 2025. Two months later, on December 18, 2025, it published the spec as an open standard at agentskills.io — The New Stack's coverage at the time explicitly compared the move to the playbook that made MCP an industry standard. By 2026, industry write-ups and platform docs agree the format crossed enemy lines: OpenAI's Codex ships skills with a built-in skill-creator, and Claude Code, Codex, ChatGPT, and OpenClaw all read compatible SKILL.md files.

MCP standardized what agents can call. Skills standardize what agents know — the procedures, the style rules, the organizational quirks that never fit an API. The two compose: a skill can document when to use which MCP server, which is exactly the kind of judgment no tool schema has ever carried well. As covered in this site's MCP maturity piece, the protocol spent 2025 shedding its stateful complexity; skills are betting the same plain-files-win economics apply to knowledge.

The scale is early but real. OSSInsight counted GitHub repos mentioning "agent" and "skill" growing from 17 in 2023 to over 23,900 in the first quarter of 2026, alongside 57,000-plus AGENTS.md files. Those are single-source analytics — directionally believable, precisely unimportant.

ClawHub: the supply chain arrives early

Here is where the story stops being a spec walkthrough. In February 2026, researchers at Koi Security audited ClawHub — the community skills marketplace for OpenClaw, an open-source agent framework — and found 341 malicious skills. The Hacker News and Broadcom's security team both reported the findings: most traced to a single campaign distributing Atomic Stealer, harvesting credentials on macOS and Windows. A skill, remember, can bundle executable scripts and instruct an agent with shell access. Installing a malicious one is not like installing a bad code snippet — it is handing a prompt-and-scripts bundle to an assistant that runs things.

By June, the problem had matured rather than faded. Unit 42 published an analysis of the AI skill supply chain; Dark Reading reported OpenClaw removing five skills that carried infostealers while bypassing automated scanners. The parallels to npm's 2025 — covered in this site's npm supply chain piece — are difficult to miss: open marketplace, community uploads, trust-me branding, scanners a step behind.

The mitigations transfer too. Skills from unknown publishers deserve the same suspicion as npm packages from unknown maintainers — read the scripts before installing, prefer skills bundled in reputable repos, and treat "agent asked to run this script" as a security event, not a UX detail. None of this is unique advice; it is the npm checklist arriving two years early for a younger ecosystem.

Writing a SKILL.md that survives

Everything below comes from the spec itself and its published best practices — no proprietary magic:

1. Make the description a router. Lead with the verbs a user would type, state the trigger conditions explicitly, and use the full 1,024 characters when the skill has multiple use cases. Vague descriptions starve skills of invocations. 2. Keep the body lean, push detail to references/. Progressive disclosure means the body loads only on activation — but every token still competes for context. Long checklists belong in reference files the agent opens on demand. 3. Let scripts do the heavy lifting. Deterministic work belongs in scripts/ as executable code, not as prose instructions the model re-interprets per run. Cheaper, faster, and testable outside the agent. 4. Name hyphen-clean. Lowercase, digits, single hyphens, matching the directory — the spec rejects PDF-Processing, leading hyphens, and consecutive hyphens outright. 5. Declare allowed-tools while it is experimental. Pre-approving a minimal toolset is the cheapest sandbox a skill can ship with, and the field is likely to matter more as platforms harden.

Where the standard goes next

The honest answer: registry verification is the gap. ClawHub's incident showed what community marketplaces become without a trust layer, and the npm precedent — provenance, verified publisher badges, graduated trust — is the obvious destination. The compatibility field will also earn its keep as platforms diverge; a skill that assumes shell access needs to say so before a sandboxed web agent chokes on it. Both are inferences from documented events, not announcements — nobody has promised anything.

What is already true is enough. A format that three competing platforms read, specified in public, small enough to learn in an afternoon, is the kind of boring that infrastructure is made of. The malware is optional — and, unfortunately, already shipped.

TL;DR

• Agent Skills is a folder with a SKILL.md — YAML frontmatter plus Markdown, optional scripts/, references/, assets/, loaded via progressive disclosure.
• Anthropic launched it October 16, 2025, opened the spec December 18, 2025; Codex and other platforms now read the same format.
• The frontmatter description is a router, not docs — it decides whether the skill loads at all.
• Koi Security's February 2026 audit found 341 malicious skills on ClawHub, mostly one Atomic Stealer campaign; June brought evasive bypassers.
• Mitigations are the npm playbook: treat unknown publishers as hostile, read bundled scripts, and wait for provenance-style verification.

Keep reading

• MCP's stateless spec turned it into boring infrastructure
• Build a custom MCP server in 50 lines of Python
• AI agents — the topic hub

---

Not affiliated with Anthropic, OpenAI, or OpenClaw. Sources: agentskills.io spec, Anthropic's announcement, The New Stack, The Hacker News, Broadcom, Unit 42, Dark Reading, OSSInsight.