Why Your First SKILL.md Matters More Than Your Next Line of Code

In roughly 90 days between October and December 2025, Agent Skills went from an Anthropic-only feature to a de facto industry standard. OpenAI adopted the format in mid-December, Microsoft followed within hours across GitHub Copilot and VS Code, and Google had already launched a parallel system — making the SKILL.md file a cross-platform capability for Claude Code, Codex, Cursor, and Gemini CLI alike.

That speed is why your first skill matters more than your next line of code. Practitioners are noticing the shift: as one engineer put it, he now does most of his work "not writing a single line of code, but defining the SKILL.md," calling it possibly the most important skill to learn. Instruction-writing is becoming a core developer capability in its own right.

Here's the problem, though. The format looks trivially simple — a directory, a SKILL.md with YAML frontmatter, some instructions. But every skill you write competes for a shared, scarce resource: the context window. Anthropic's own best-practices guidance is blunt about this: "The context window is a public good." Your skill's metadata loads into every session, whether it's relevant or not.

A poorly written skill fails in one of two ways, and both hurt:

• It gets ignored. Claude may be choosing among potentially 100+ skills using nothing but the description field. Vague or bloated descriptions mean your skill never triggers.
• It pollutes everything. A verbose body that should be under 5,000 tokens, or reference files that dump 150 tokens where 50 would do, drags down every session it touches.

There's a third risk that's less obvious: skills are an attack surface. Installing a skill typically grants it full local user privileges with minimal scrutiny, and a peer-reviewed study of 98,380 skills confirmed 157 malicious ones carrying 632 labeled vulnerabilities. Anthropic itself warns that a malicious skill can direct an agent to invoke tools in ways that don't match its stated purpose — which is why it recommends using skills only from trusted sources, and why SkillzBench is building verification and benchmarking infrastructure to separate helpful skills from risky ones.

So treat your first SKILL.md the way Anthropic suggests you treat onboarding: as a guide for a new hire who is already very smart. Write only what the agent doesn't already know, and make every token earn its place. That discipline is the difference between a skill that quietly helps and one that quietly costs you.

The Anatomy of a Skill: Progressive Disclosure and the Copy-Paste Template

Strip a skill down to its essentials and you'll find something refreshingly small: a folder, one markdown file, and a design principle borrowed from good API design. Anthropic calls building a skill "like putting together an onboarding guide for a new hire" — and the minimal viable structure proves it.

Your first skill is a directory containing a single SKILL.md file. That file has two parts: YAML frontmatter with name and description fields, followed by an instruction body written in plain markdown. Three optional folders round out the format — scripts/ for executable code, references/ for documentation, and assets/ for templates and files the agent can copy. Per the official spec, the frontmatter constraints are strict:

• name — max 64 characters, lowercase letters, numbers, and hyphens only (and it can't contain "anthropic" or "claude")
• description — max 1024 characters, non-empty, and it must say both what the skill does and when to use it
• Body — keep it under 500 lines; reference files over 100 lines need a table of contents

The description field deserves extra care. Claude may be choosing among potentially 100+ installed skills, and descriptions are the only signal it gets at selection time. A vague description means your skill never fires; a precise one is the difference between a skill that works and one that's dead weight.

What makes skills scalable is progressive disclosure — the loading model that keeps token costs near zero until a skill is actually needed. Per Anthropic's best-practices guidance, it works in three levels: the metadata (name + description) costs roughly 100 tokens and is always loaded; the body stays under 5k tokens and loads only when triggered; and resources in scripts/, references/, and assets/ cost zero tokens until the agent actually opens them.

This is why the frontmatter constraints matter so much. Every skill you install taxes the context window with ~100 tokens whether you use it or not — and as Anthropic puts it, "the context window is a public good." A concise example description runs about 50 tokens; a verbose one runs 150. Multiply that across a loaded agent and sloppy descriptions get expensive fast.

---
name: my-first-skill
description: Use when the user asks to [do X] in [context Y].
  Produces [specific output]. Requires [tool/condition].
---

One paragraph: what this skill does and when to use it.

1. Step one
2. Step two
3. Step three

<!-- One worked example, kept short -->

Before shipping, apply the test that separates good skills from bloat: does every line justify its token cost? Anthropic's default assumption is that "Claude is already very smart — only add context Claude doesn't already have." If a line restates something the model knows, delete it.

That same discipline applies to what you install, not just what you write. Given that skills execute with full user privileges, SkillzBench is building verification and benchmarking workflows so authors and users alike can see which skills genuinely earn their place — measured in Lift, always kept separate from trust scores. Write lean, verify everything.

Writing the Description That Gets Your Skill Actually Used

Your skill might never run — not because it's bad, but because its description failed to win the argument. Agents choose among potentially 100+ installed skills using descriptions alone, so this one field functions as your skill's entire discovery engine.

Anthropic's authoring best practices are explicit: the description must state both what the skill does and when to use it. A description that only covers the "what" leaves the agent guessing about triggers; one that covers both gives the agent a clear matching rule. Keep it within the 1024-character limit, and remember that metadata costs roughly 100 tokens per skill and is always loaded — the context window is a public good, so every word must earn its place.

The same "only add what's missing" principle governs the body. Anthropic's default assumption is that Claude is already very smart — only add context Claude doesn't already have. Skip explanations of general concepts; include only your company's conventions, obscure constraints, and hard-won specifics.

Match degrees of freedom to task fragility:

• High freedom: plain text instructions for tasks with many valid approaches, like writing reports or summarizing documents.
• Low freedom: exact scripts with no parameters for fragile operations, such as database migrations, where improvisation causes damage.
• Middle ground: parameterized scripts when some variation is valid but the core sequence must hold.

Conciseness applies to examples too. Anthropic's guidance shows a concise example costs about 50 tokens while a verbose one costs about 150 — a threefold difference that compounds across every skill load. Keep the SKILL.md body under 500 lines and push longer reference material into files loaded on demand.

One caveat: a well-written description is a quality signal, not a safety guarantee. Security research analyzing 98,380 skills confirmed 157 malicious ones, and static analysis alone achieves only ≤1.1% precision at distinguishing malice from mistakes versus 99.6% for behavioral verification. That gap is exactly why SkillzBench is building behavioral benchmarking — testing each skill in a sandbox with the same model, with and without it, and publishing the Lift in percentage points alongside a trust score.

Write the description as if a busy new hire will read it in one glance — because functionally, that's what it is.

Write It Safe: Avoiding the Patterns That Make Skills Look Malicious

Writing your first skill is easy. Writing one that doesn't look like malware takes deliberate care — because skills run with full user privileges the moment they're installed, with minimal scrutiny or interactive confirmation, according to peer-reviewed security research.

The scale of the problem is real. That study analyzed 98,380 skills across two major registries and confirmed 157 as malicious, carrying 632 labeled vulnerabilities — an average of 4.03 vulnerabilities per malicious skill. Earlier static scans have flagged roughly 26% of skills as risky. Even Anthropic warns that a malicious skill can direct an agent to invoke tools or execute code in ways that don't match its stated purpose.

If you're a first-time author, the practical takeaway is simple: don't accidentally mimic the patterns security researchers associate with attacks. The two dominant archetypes in the wild are Data Thieves (credential theft) and Agent Hijackers (instruction-level manipulation). Avoid anything that resembles either:

• Reading credential files, environment secrets, or auth tokens without an obvious, documented reason.
• Pipe-to-shell one-liners like curl ... | bash, which scanners treat as a red flag regardless of intent.
• Base64-encoded payloads or other obfuscation — if a reviewer can't read it, they'll assume the worst.
• Instructions referencing external exfiltration endpoints or "send results to this URL" steps.

Here's the harder truth for honest authors: even a clean, well-intentioned skill can look suspicious. The same research found that static analysis alone achieves at most 1.1% precision in distinguishing malicious skills from benign ones, because it can't tell a developer mistake from malice. Behavioral verification, by contrast, reached 99.6% precision.

That gap is why verification and benchmarking matter for authors, not just users. If you want your skill trusted, you want it examined the way a skeptical evaluator would examine it — sandboxed, tested with the same model with and without the skill, and pinned to a specific commit so anyone can confirm what they're running.

This is the problem SkillzBench is being built to solve: an independent lab that verifies, security-scans, and benchmarks skills so quality authors can prove — not just claim — that their work is safe and effective. Skills, proven. If you're writing your first skill and want it to stand out, join the waitlist and be among the first authors whose skills get independently tested.

From First Skill to Proven Skill: Test, Iterate, and Publish

A working SKILL.md is a draft, not a finished skill. Anthropic's own authoring workflow treats shipping as the beginning of a loop: start with evaluation, structure for scale, and iterate with the agent itself — because Anthropic's engineering guidance describes skill-building as "putting together an onboarding guide for a new hire," and new hires only prove themselves on the job.

Before you publish, run your skill through a pre-flight review:

• Pin a version — record the exact commit SHA so users know what they reviewed.
• Check the license — confirm every reference and dependency permits redistribution.
• Quality-review the body — under 500 lines, references one level deep, no context Claude already has.
• Measure lift — same task, same model, run with and without the skill.

That last step matters more than most authors realize. A skill that "feels helpful" can quietly degrade performance if its instructions crowd out better reasoning — and per Anthropic's best-practices docs, "the context window is a public good." Every token your skill spends must justify itself against a baseline you can actually measure.

Security review is non-negotiable, too. Peer-reviewed security research analyzed 98,380 skills and behaviorally confirmed 157 as malicious, with an average of 4.03 vulnerabilities each — and installing a skill typically grants it full local user privileges. Authors who avoid credential access, pipe-to-shell patterns, and obfuscated payloads protect not just users but their own reputation.

This is exactly the gap SkillzBench is being built to close: an independent lab that pins every skill version to a commit SHA, runs license checks and security scans, and benchmarks each skill in a sandbox — same model, same task, with and without the skill — publishing the Lift in percentage points. Behavioral verification is the standard that matters here: research shows it reaches 99.6% precision versus at most 1.1% for static analysis alone.

Your first skill is the start of a craft. Prove it works before you ask anyone to trust it.

Skills, proven. Join the SkillzBench waitlist at skillzbench.com and be first in line when the lab opens.