Skill.md Template: A Copy-Paste Starting Point for 2026

Why SKILL.md Became the Standard (and Why a Template Matters Now)

Twelve months ago, SKILL.md was an Anthropic feature. Today it's the closest thing agent tooling has to a shared standard, and that shift changed how everyone should write one.

Anthropic announced Agent Skills on October 16, 2025, then released the format as an open standard on December 18, 2025, according to industry coverage. OpenAI and Microsoft adopted it shortly after. The practical payoff: a skill you write once now works across Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, and more, with official skills published by vendors ranging from Anthropic and OpenAI to Cloudflare, Vercel, and Figma.

The architecture that makes this work is progressive disclosure, and it's worth understanding before you copy any template. Per Anthropic's documentation, skills load in three stages:

• Metadata, roughly 100 tokens, always loaded at startup so the agent knows the skill exists
• Full instructions, kept under 5k tokens, loaded only when the skill is triggered
• Resources and scripts, which cost zero tokens until the agent actually opens them

Contrast that with stuffing everything into a CLAUDE.md file, where long reference material burns context on every single turn. Anthropic has claimed an equivalent workload dropped from 150,000 tokens to 2,000, a 98.7% reduction, though that figure comes from the vendor rather than independent testing. One MCP project documented in the same coverage consumed about 30,000 tokens just for tool definitions, which the author called a critical flaw limiting MCP usability.

So why start from a template instead of a blank file? Because the structure is settled. Production skills from OpenAI and Anthropic converge on the same pattern: a tight description that drives triggering, numbered workflow steps, decision trees, override rules, and a defined output format. The description field alone determines whether your skill fires at all; as one practitioner guide puts it, if a skill doesn't trigger, it's almost never the instructions, it's the description.

There's also a security reason to start from a vetted structure. A Snyk audit of 3,984 public skills found 36.82% contain at least one security flaw, and OWASP now publishes a dedicated skill development guide with least-privilege permissions and a pre-publish checklist. Anthropic itself advises treating skills like installing software.

That's why a proven template matters more than cleverness. You get the field constraints right (64-character names, 1024-character descriptions), the section conventions that production skills already use, and the security sections OWASP recommends, without reinventing any of it. If you'd rather adapt than write from scratch, SkillzBench's free directory at skillzbench.com pins every skill to a commit SHA, security-scans each one, and publishes benchmark results so you can see what a well-built skill actually looks like before you trust it.

The Template: Minimal Frontmatter Plus the Sections That Actually Work

A valid SKILL.md needs surprisingly little: two YAML fields and a Markdown body. The craft is in what you put in those fields, because one of them decides whether your skill ever runs at all.

Here's the copy-paste starting point, built from the official field constraints and the section conventions used in production skills like OpenAI's MIT-licensed security-best-practices skill:

---
name: pr-security-review
description: >
  Review a pull request for correctness, security issues, and missing
  tests. Use when asked to inspect, review, or audit a pull request
  or code change before merge.
disable-model-invocation: false
allowed-tools: ["Read", "Grep", "Bash"]
---

State the single outcome this skill produces, in one or two sentences.

1. Numbered, concrete steps the agent follows in order.
2. Keep each step actionable, not explanatory.
3. Note which steps require judgment versus mechanical checks.

Define exactly what the agent returns: structure, headings, severity levels.

What to do when a step fails, input is malformed, or context is missing.

Two fields are required. Per the official Agent Skills documentation, name allows a maximum of 64 characters using lowercase letters, numbers, and hyphens only (the words "anthropic" and "claude" are reserved), and description must be non-empty and capped at 1024 characters. Everything else in the frontmatter is optional.

That description deserves most of your writing effort. It's the trigger mechanism: the agent matches your request against it to decide whether to load the skill. As one practitioner guide puts it, if your skill doesn't fire, it's almost never the instructions, it's the description. A strong one states both what the skill does and when to use it. "Reviews code" fails on both counts.

The optional fields matter for safety. Set disable-model-invocation: true for anything with side effects like deployments, commits, or releases, so the skill runs only when explicitly requested. allowed-tools implements least privilege, which OWASP's skill development guide treats as a baseline: request only the minimum permissions the skill needs to function.

The four body sections mirror what actually ships in production. OpenAI's security-best-practices skill follows a similar arc (Overview, Workflow, Decision Tree, Report Format), and the pattern holds because it separates concerns: Objective pins the goal, Process encodes judgment, Output Format removes ambiguity about deliverables, and Error Handling keeps the agent from improvising when things go wrong.

One structural note: keep this file lean. Progressive disclosure means only about 100 tokens of metadata load at startup, with the full body loaded on demand. Push long reference material into a references/ directory, where it costs zero tokens until the agent actually opens it.

Before you install anyone else's skill rather than writing your own, vet it. A Snyk audit of 3,984 public skills found 36.82% contain at least one security flaw, and Anthropic advises treating skills like installing software. On SkillzBench's free directory, every skill is pinned to a commit SHA, security-scanned, and benchmarked with its Lift published, so you can check verified impact before anything touches your agent.

Bake In Security Before You Share the Skill

A skill you share is code someone else runs. That's not a metaphor: Anthropic's own guidance says to treat skills "like installing software" and use them only from trusted sources, because a SKILL.md file can direct an agent to read files, call tools, and execute scripts on your machine.

The numbers back up the caution. A Snyk audit of 3,984 public skills found that 36.82% contain at least one security flaw. OWASP now runs a dedicated Agentic Skills Top 10 project with a security-oriented template and a pre-publish checklist, and its advice is blunt: "Request only the minimum permissions needed for your skill to function."

So before you publish or share your template, bake three things into it.

Declare least-privilege permissions in the frontmatter. Instead of granting broad access, scope it: filesystem:read:/data for a skill that only reads data, network access limited to the specific hosts it needs. If your skill touches deployment or commits, set disable-model-invocation: true so it runs only when explicitly requested, a pattern practitioner guides recommend for side-effecting workflows.

Constrain the inputs. OWASP's example limits are a good starting point: a 1024-character maximum on input length, a 512MB memory cap, and a 30-second timeout. An agent that can accept unlimited input or run indefinitely is an agent that can be pushed into doing things you didn't intend.

Add a Security Considerations section to the body. Two or three sentences about what the skill must never do (write outside its output directory, execute downloaded code, send data to third parties) cost nothing at runtime and shape behavior when the skill triggers.

Then run the pre-publish checklist before you share anything:

• Permissions: does every declared permission map to a step the skill actually performs?
• Inputs: are length caps, timeouts, and memory limits stated explicitly?
• Side effects: could this skill modify files, commit code, or call external services without the user asking?
• Secrets: does the body or any bundled script contain keys, tokens, or paths that leak information?
• Sources: if the skill installs dependencies, is each one pinned and trusted?

OWASP frames the last point well: treat any installer as a supply-chain boundary, not ordinary setup glue. The same goes for skills you adopt from others. Since roughly a third of public skills carry at least one flaw, source them from somewhere that verifies before you install. SkillzBench security-scans every skill in its free directory, pins each version to a commit SHA, and publishes the results so you can check before an agent ever loads the file.

Security isn't a section you add at the end. It's a property of the template you started with, and the cheapest time to fix a flaw is before anyone else runs your skill.

Keep the Main File Lean, Push Detail Into references/

The biggest mistake people make with SKILL.md is treating it like a system prompt: cramming every rule, edge case, and reference table into one file. That defeats the whole point. Skills work because of progressive disclosure, and progressive disclosure only pays off if you keep the main file lean.

Here's the economics. At startup, every skill costs roughly 100 tokens of metadata, always loaded. The full instruction body loads only when triggered, at under 5k tokens. Everything else, files in references/, scripts/, and assets/, costs zero tokens until the agent actually opens them. As the Claude Code documentation puts it, unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

The standard folder structure looks like this:

• SKILL.md: the lean instruction file, under 5k tokens, covering the procedure at a high level
• references/: detailed docs, schemas, style guides, decision tables the agent reads only when the task demands it
• scripts/: executable code for deterministic steps, invoked on demand
• assets/: templates and boilerplate files the agent copies or adapts

The payoff compounds. A 100-skill library costs only about 5,000 to 10,000 tokens at startup, and Anthropic reported cutting token usage from 150,000 to 2,000 for equivalent functionality, a 98.7% reduction. Compare that to one MCP project that accumulated roughly 345 tools consuming 30,000 tokens just for tool definitions. Structure is the difference.

Two rules of thumb keep the split clean. First, skills versus CLAUDE.md: if the content states a fact or stable expectation, it belongs in CLAUDE.md. If it tells the agent how to perform a multi-step procedure, move it into a skill. Second, within the skill itself, use code for rule-based work and the model for judgment. If a step is deterministic (validate a schema, run a linter, format a report), write a script and reference it. If the step requires interpretation (decide whether this code change is safe to ship), describe the judgment criteria in prose and let the model reason. Practitioners note that CLI tools paired with a skill file also use far fewer tokens than MCP-based workflows for the same jobs.

The template in this article follows that discipline: a tight SKILL.md with Objective, Process, and Output sections, plus a references/ folder where the deep material lives. When you're ready to go beyond your own skills, browse the free SkillzBench directory, where every skill is pinned, security-scanned, and benchmarked so you can see verified impact before installing anything.

Test Your Skill Before You Trust It (or Install Someone Else's)

A skill that reads well isn't a skill that works well. The only honest way to know if your SKILL.md actually helps is to run the same task twice: once with the skill loaded, once without, and compare the output. If you can't tell the difference, your skill is decoration.

This matters more than most people expect. A Snyk audit of 3,984 public skills found 36.82% contain at least one security flaw, and that's just the vulnerabilities. Plenty of the remaining skills simply don't improve results. Anthropic's own guidance is blunt: treat skills "like installing software" and use them only from trusted sources, per the official documentation.

A simple benchmark protocol looks like this:

• Pick 5 to 10 representative tasks that the skill claims to handle.
• Run each task with the same model, twice: once bare, once with the skill enabled.
• Score both outputs against a fixed rubric you write before testing, so you're not grading your own preference in the moment.
• Record the difference. That gap, in percentage points, is your skill's real value.

If you're installing someone else's skill, the bar should be higher, because you're inheriting their judgment and their risks. OWASP's skill development guide frames an installer as a supply-chain boundary, and that's the right mental model. A skill from an unvetted repo can carry prompt injection, over-broad permissions, or silently out-of-date instructions that no longer match the tool it documents.

This is where verification infrastructure earns its keep. SkillzBench's free directory does the legwork for third-party skills: every version is pinned to a commit SHA, security-scanned, and benchmarked in a sandbox with the same model, with and without the skill installed. The resulting Lift is published in percentage points, so you can see verified impact before you commit anything to your agent. If a skill claims to improve code review by some margin and the benchmark says otherwise, you find out before it touches your workflow.

The same discipline applies to your own template. Before you share it with your team or the world, run the with-and-without test yourself. A skill that can't demonstrate a lift is a README, not a skill, and knowing which one you've written is the difference between a tool people rely on and one they quietly delete.