The Annotated Skill.md: Line-by-Line Breakdown

Why One Small File Decides Your Agent's Success or Security

Every line in a SKILL.md file is doing two jobs at once: it's an instruction that shapes how well your AI agent performs, and it's a potential opening for someone who wants to exploit that agent. That dual nature is what makes line-level literacy in skill files matter — whether you're a developer shipping skills or a business owner deploying agents that handle real work.

The performance case is well documented. Microsoft Research's SkillOpt work treats skill files as trainable parameters outside a frozen model, and the results are striking: optimized skills lifted a six-benchmark average on GPT-5.5 from 58.8 to 82.3 — a +23.5-point absolute gain. In one transfer test, a spreadsheet skill trained in one harness and dropped unchanged into another lifted the baseline from 22.1 to 81.8.

But the same lines carry risk. The first large-scale security study of the ecosystem analyzed 31,132 unique skills and found that 26.1% contain at least one vulnerability — spanning prompt injection, data exfiltration, privilege escalation, and supply chain patterns. Snyk's separate ToxicSkills audit of 3,984 skills found 13.4% carried at least one critical-level issue, and confirmed 76 malicious payloads in the wild.

The reason a plain text file can be this dangerous comes down to how agents work. Skills "can instruct agents to perform malicious actions in natural language, bypassing code-level detection," according to the academic study. A December 2025 demonstration showed a seemingly benign "GIF Creator" skill silently downloading and executing ransomware. The publishing barrier is minimal — Snyk notes it takes just a SKILL.md file and a week-old GitHub account, with no code signing or security review.

That's why reading a skill line by line isn't a style exercise — it's a security necessity. The frontmatter lines decide when a skill triggers; body lines tell the agent what to download, which URLs to fetch, and how to handle credentials. Snyk found hardcoded secrets in 10.9% of ClawHub skills and suspicious download instructions in another 10.9%.

• Frontmatter lines control routing — a vague description makes a skill invisible or, worse, triggers it in the wrong context.
• Body lines are executable intent — instructions to fetch files, run scripts, or connect to external services are attack vectors in plain English.
• Bundled files expand the surface — skills with executable scripts are 2.12× more likely to contain vulnerabilities than instruction-only skills.

This is exactly the gap SkillzBench is being built to close: a free, independent directory that pins versions, runs security scans, and benchmarks every skill with and without it — so you can see both the lift and the risk before anything touches your agent. If you want skills that help rather than harm, they need to be proven, not just published.

The Anatomy of a SKILL.md: Frontmatter, Body, and Bundled Files

A SKILL.md looks deceptively simple: a few lines of YAML, some instructions, a folder of extras. But those lines are doing three very different jobs, and each one carries real stakes — both for how well the skill performs and how safely it behaves.

Anthropic's design principle is progressive disclosure: the agent loads a skill in three levels, only as needed.

• Level 1 — Frontmatter: the YAML metadata the agent pre-loads into its system prompt at startup.
• Level 2 — Body: the full SKILL.md instructions, read only if the agent decides the skill is relevant.
• Level 3 — Bundled files: scripts, references, and assets, opened just-in-time when the instructions tell the agent to.

The frontmatter is the highest-stakes part of the file. According to practitioner guidance from Minko Gechev, the name and description are the only fields the agent sees before triggering a skill — if they aren't specific enough, your skill is effectively invisible. The constraints are strict: the name must be 1–64 characters (lowercase letters, numbers, hyphens) and exactly match the parent directory name. The description allows up to 1,024 characters, written in third person, and should include negative triggers — explicit statements like "Don't use it for Vue, Svelte, or vanilla CSS projects" that prevent false activations.

The body is the brain, and brevity is a feature: keep it under 500 lines, use numbered steps and concrete templates (agents pattern-match exceptionally well), and write in imperative voice — "Extract the text," not "You should extract." Bundled files should sit exactly one level deep (references/schema.md, not references/db/v1/schema.md), with instructions telling the agent precisely when to read each one.

The recommended layout:

skill-name/
├── SKILL.md        # Metadata + core instructions (<500 lines)
├── scripts/        # Executable helpers, designed as tiny CLIs
├── references/     # Schemas, cheatsheets, supplementary context
└── assets/         # Templates or static output files

One principle ties it together: skills are for agents, not humans. Skip the README, changelog, and installation guide — the agent doesn't need them, and every redundant line competes for context.

And every line deserves scrutiny, because the same natural-language instructions that boost performance can also bypass code-level security detection. A large-scale study of 31,132 skills found 26.1% contain at least one vulnerability. That's why SkillzBench is building free security scanning, version pinning, and benchmarking into its skills directory — so you can judge every line before an agent ever reads it.

The Security Mirror: Reading the Same Lines as an Attacker

Now read those same lines the way an attacker does. The features that make a skill powerful — plain-English instructions, bundled scripts, one-click approval — are exactly what makes it dangerous.

The core problem is that a SKILL.md is just text. Skills "can instruct agents to perform malicious actions in natural language, bypassing code-level detection," as researchers behind a study of 31,132 skills found — and 26.1% of those skills contained at least one vulnerability (the study). Your antivirus sees nothing, because the weapon is a sentence.

Snyk's audit of ClawHub and skills.sh makes the exposure concrete. Of 3,984 skills, 13.4% carried at least one critical issue, and human review confirmed 76 malicious payloads — 8 still live at publication. The publishing barrier? A SKILL.md file and a GitHub account one week old, with no code signing or security review (Snyk's ToxicSkills report).

Map each authoring line to its attack counterpart:

• "Download this file and run it" — suspicious downloads appear in 10.9% of ClawHub skills. The GIF Creator demo showed a benign-looking skill silently installing MedusaLocker ransomware.
• "Fetch the latest schema from this URL" — third-party content exposure hits 17.7%, opening the door to injected instructions.
• "Read your API keys to authenticate" — credential handling shows up in 7.1%, and hardcoded secrets in another 10.9%.
• Bundled scripts: skills that ship executable code are 2.12× more likely to contain vulnerabilities than instruction-only skills.

Then there's the consent gap: once you approve a skill, it holds persistent permissions to read files, write files, download code, and open network connections — no further prompts. Ninety-one percent of confirmed malicious skills pair this with prompt injection that primes the agent to accept code it would normally reject.

This is why SkillzBench is building verification into every layer — pinning each skill to a commit SHA, running security scans, and benchmarking in a sandbox before you ever install it. The directory and MCP connector will be free, so you can choose skills with evidence rather than trust.

Write and Validate Skills That Actually Lift Performance

Writing a skill is easy; writing one that measurably improves your agent is not. Microsoft's SkillOpt research found that a "perfectly reasonable" revision can quietly degrade task performance — which is why disciplined validation, not intuition, separates skills that help from skills that hurt.

The recommended workflow has four stages. Discovery validation tests the frontmatter in isolation, checking whether the name and description trigger the skill when they should — and, just as importantly, when they shouldn't. Logic validation simulates execution and flags "Execution Blockers" before they reach a real agent. Edge-case testing puts a ruthless QA tester's hat on, probing for inputs the instructions never anticipated. Finally, architecture refinement enforces progressive disclosure and adds an explicit error-handling section.

The payoff is real. In a controlled, validated process, optimized skills lifted a six-benchmark average from 58.8 to 82.3 on GPT-5.5, and a spreadsheet skill trained in Codex and dropped into Claude Code with no further tuning raised the baseline from 22.1 to 81.8 — a +59.7-point transfer gain. Notably, the winning skills were small and auditable: a median of roughly 920 tokens, with only 1–4 accepted edits per file. A smaller model (GPT-5.4-mini) with optimized skills even outperformed the larger GPT-5.4 running without them.

What does good versus bad look like at the line level?

• Bad frontmatter: a description like "React skills" — too vague for the agent to route on, rendering the skill effectively invisible.
• Good frontmatter: "Creates and builds React components using Tailwind CSS. Use when the user wants to update component styles or UI logic. Don't use it for Vue, Svelte, or vanilla CSS projects." Specific, third-person, with negative triggers.
• Bad instruction: "You should extract the text from the document." Passive, second-person, and easy for the agent to misinterpret.
• Good instruction: "Extract the text from the document, then check the output against references/schema.md." Imperative voice, concrete template, and an explicit just-in-time file reference.

Validation also has a security dimension. With roughly 26% of analyzed skills carrying at least one vulnerability, and malicious instructions operating in natural language that bypasses code-level detection, every line you write — or install — deserves scrutiny. That's the gap SkillzBench is building to close: a free directory that will version-pin, security-scan, and benchmark skills so you can see the lift before you trust the lines.

Skills, proven. Join the SkillzBench waitlist and be first to browse, verify, and benchmark agent skills for free.

How to Trust Someone Else's SKILL.md Without Reading Every Line

Most teams will never read every line of the skills they install — and that is exactly the problem. Anthropic's own guidance is blunt: install skills only from trusted sources, and audit files, dependencies, bundled resources, and any instructions that connect to untrusted external network sources. Yet Snyk's ToxicSkills audit found the publishing barrier is minimal — a SKILL.md file and a GitHub account one week old, with no code signing, no security review, and no sandbox by default.

The stakes are measurable. A large-scale study of 31,132 skills found 26.1% carry at least one vulnerability, and skills bundling executable scripts are 2.12× more likely to contain one. The same research calls for mandatory security vetting before installation — because natural-language instructions can direct an agent toward malicious actions while bypassing code-level detection entirely.

Manual line-by-line review does not scale when daily skill submissions jumped from under 50 in mid-January 2026 to over 500 by early February. So verification has to become infrastructure, not willpower.

That is what SkillzBench is building: a free, independent directory where every skill version is pinned to a commit SHA, validated, license-checked, security-scanned, and quality-judged — then benchmarked in a sandbox with the same model, with and without the skill, so the Lift is published in percentage points. A free MCP connector lets you equip agents with only the skills you choose.

• Version pinning to a commit SHA, so what you install cannot silently change
• Security scanning and license checks before anything reaches your agent
• Sandboxed benchmarking that reports Lift separately from trust scores
• Continuous re-scanning and alerts when an upstream skill changes

Everything on the platform is free — the directory, the MCP connector, benchmarks, and alerts — funded by advertising that never touches scores or listings. Skills, proven. Join the waitlist and be first to browse, verify, and benchmark agent skills for free.