In October 2025, Anthropic introduced Agent Skills — a simple, file-based way to package instructional knowledge that travels with the model. A Skill is a folder. The folder contains a SKILL.md file with YAML frontmatter and Markdown body, plus optional attached resources (scripts, templates, reference docs). By February 2026, Codex CLI had adopted the same SKILL.md shape; by April 2026, Google announced Gemini would support the format as well. As of May 2026, SKILL.md is a cross-vendor open standard that runs unchanged inside Claude Desktop, Claude Code, Claude.ai, Codex CLI, Gemini, and a growing list of third-party hosts. This lesson is how to write your first SKILL.md — manifest, instructions, and attached resources — including the failure mode that makes operators write Skills that bloat the system prompt and degrade the model rather than help it. We end with a recipe library you can adopt.

What a Skill Actually Is

A Skill, in 2026 vocabulary, is instructional packaging. It is not code (that's a tool or an MCP server). It is not a prompt template (that's static text inserted at runtime). It is a folder of guidance and resources that the model loads into context when the user does something that matches the Skill's described trigger.

The simplest valid Skill is a single SKILL.md file:

---
name: Anonymize Customer Names
description: When the user asks to anonymize customer names in a document, replace each unique name with a consistent pseudonym (Customer A, Customer B). Preserve case, role, and contextual references.
---

# Anonymize Customer Names

When invoked, you are operating on a document the user has provided. Follow these rules:

1. Identify all unique full names of customers.
2. Map each unique name to a sequential pseudonym: first to "Customer A," second to "Customer B," and so on.
3. Replace every occurrence of each name with its pseudonym.
4. Preserve case, role qualifiers ("Mr.", "Dr."), and contextual references ("their team", "his decision").
5. After the document, output a mapping table the user can use to reverse the anonymization later.

That's a complete Skill. The frontmatter is the manifest. The body is the instructions. The model loads this Skill when the user's request matches the description, executes the instructions in context, and produces a transformed document plus the mapping table.

A more elaborate Skill might add attached resources: a Python script that runs the anonymization deterministically when invoked from a CLI agent like Claude Code; a reference list of common name patterns; an example anonymized document. Those attached files live in the same folder as SKILL.md and the model decides at runtime which (if any) to read.

A Skill is "what to do when this kind of request arrives." Tools are "what calls to make." MCP servers are "where the credentials live." Skills are the instructional layer that ties the other two together for a specific category of work.

The Three Structural Parts of a Skill

One: the manifest (YAML frontmatter)

Every SKILL.md begins with YAML frontmatter that names the Skill and describes when it should be used. The two required fields are name and description. Optional fields include version, author, tags, and (for Skills with attached resources) resources with paths.

The description field is the most consequential thing you'll write in a Skill. It is what the host shows to the model when listing available Skills, and it is what the model uses to decide whether this Skill matches the current request. A description that says "anonymize customer names" matches a much narrower set of queries than one that says "anything related to anonymization or PII redaction." Write the description to match the actual triggers, not aspirations.

A pattern we've seen work consistently: the description starts with the verb-noun trigger ("When the user asks to..." or "Use this when the user wants to...") and ends with the differentiator ("...for documents in customer-facing communications, not internal logs"). Specific triggers beat broad triggers.

Two: the instructions (Markdown body)

The body of SKILL.md is the actual procedural guidance the model follows. This is where the Skill's value lives. Patterns that work:

• Lead with the goal. One sentence: "Your job, when this Skill is invoked, is to..." Lets the model orient before reading detail.
• Numbered steps. The model executes steps better than prose-only instructions. Numbered steps with explicit ordering reduce skipping and reordering errors.
• Inline examples. When a rule is subtle, show a one-line input + output example. Anchoring on a concrete case beats abstract description.
• Edge case section. "What to do if..." — explicit handling of the common edge cases (e.g., what to do if a name appears as part of an email address, what to do if a name is a common word).
• Termination criterion. When is the Skill "done"? An explicit completion signal prevents the model from continuing past the actual task.

The body should be terse, not exhaustive. Skills are loaded into context at invocation time; long Skills eat token budget and degrade model focus. Aim for under 500 words in the body when possible; pull longer guidance into attached resources that the model reads on demand.

Three: attached resources

Anything the Skill needs but doesn't fit in 500 words of body. Common attached resources:

• Reference documents. A markdown file with detailed style guide, taxonomy, or domain glossary the Skill should consult when needed.
• Scripts. Python, JavaScript, Bash. Useful in CLI agents (Claude Code, Codex CLI) where the model can invoke a script to do something deterministically (parse a CSV, run a regex transform, generate a deterministic output). The body of SKILL.md says "for high-volume cases, run the script attached as ./scripts/anonymize.py."
• Templates. Example output documents the Skill should match in shape. A "QBR deck template," a "release notes template," a "PR description template."
• Test cases. Optional examples for verifying the Skill's behavior. These don't run automatically; they're guidance for the author and reviewer.

Resources live in the Skill's folder. The model reads a resource only when its instructions tell it to, which means resources don't consume context budget unless they're actually needed for the current task.

Writing Your First Skill End-to-End

We walk through a real Skill from start to finish. The task: write a Skill that converts an internal Linear ticket into a customer-facing changelog entry.

Step one: decide whether this is a Skill

Before writing a Skill, ask: is this a category of work the agent will be asked to do repeatedly? If yes, a Skill amortizes the instructional cost. If it's a one-off, a prompt is enough. For our example, "convert Linear tickets to changelog entries" is a repeated task — every release. Worth a Skill.

Step two: write the description

Draft: "When the user provides a Linear ticket and asks for a changelog entry, transform the ticket's technical title and description into a customer-facing entry: a short, user-benefit-framed title and a 1-2 sentence body that emphasizes what the user can now do, not what was changed internally."

Test the description by reading it without the rest of the Skill and asking: "Would the model select this Skill for a request like 'turn LIN-3847 into a changelog entry'?" Yes. "Would it select for 'summarize this Linear ticket'?" Probably not — the description is changelog-specific. Good.

Step three: write the instructions

# Linear Ticket to Changelog Entry

Your job, when this Skill is invoked, is to transform an internal Linear ticket into a customer-facing changelog entry.

Steps:

1. Read the Linear ticket's title and description.
2. Identify the user-facing benefit: what can the customer now do, see, or avoid that they couldn't before?
3. Write a short title (under 8 words) framed around the benefit. NOT "Refactored auth flow" — YES "Sign in 3x faster on slow networks."
4. Write a 1-2 sentence body that says what the customer can do and (if relevant) when they'll see it (e.g., "starting today" or "rolling out this week").
5. Strip all internal references — engineer names, ticket IDs, internal codenames, sprint references. The customer doesn't need them.
6. If the ticket is a bug fix that doesn't have a customer-visible benefit, output the marker "INTERNAL ONLY" and do not write a changelog entry.

Style:
- Active voice. Present tense.
- No marketing language ("revolutionary", "best-in-class").
- No future-tense vague promises ("soon", "eventually").

Termination:
- Output the changelog entry as a code block (so the user can copy it directly into the changelog tool).
- Then ask: "Want me to draft another?"

Step four: add resources if needed

For this Skill, attached resources might include: a style guide (longer guidance for tricky cases), a reference set of past good and bad changelog entries, and optionally a script that posts directly to the team's changelog tool. Or none — if the body covers the cases the team encounters, the Skill is complete.

Step five: test the Skill

Run the Skill against 10 real Linear tickets. Read the outputs. Adjust the body for anything the Skill got wrong (a too-vague trigger, missing edge case, wrong style note). Iterate. The first version is rarely the final one; expect 2-4 revision passes.

Step six: ship

Place the Skill in the folder your agent host loads Skills from. For Claude Desktop, that's typically ~/.claude/skills/<skill-name>/. For Codex CLI, the analog. For Gemini, similar. The Skill is now available the next time the host starts.

The Bloated System Prompt Failure Mode

The most common Skills failure mode in 2026, observed across many operator teams, is the over-eager Skill author who writes a Skill body that runs 3,000 words long, packed with edge cases, examples, and meta-commentary. The Skill works fine in isolation. The problem appears when the user's host has 15 such Skills loaded — the model now sees 45,000 words of Skill manifests just to know what's available. Two consequences:

1. Context budget pressure. Less room for actual task context (the user's documents, the conversation history, the retrieved knowledge). The model has to drop something to make room.
2. Focus dilution. Even when a specific Skill is invoked, the surrounding noise from other Skills' manifests reduces the model's sharpness on the task at hand. Anthropic's internal benchmarks (published February 2026) showed task-completion quality declining ~3-4% per extra 10K tokens of unused-but-loaded Skill manifests.

The fix is to write Skills with two layers:

• Manifest (loaded always): Short. Description in 1-3 sentences. The model reads this to decide whether to invoke the Skill. Should fit in roughly 80-150 tokens.
• Body (loaded only when invoked): The detailed procedural guidance. Loaded into context only when the Skill is selected, not as part of the always-on manifest list.

Most hosts implement this two-layer pattern correctly. The author's job is to make sure the manifest is tight. A test: read just your description aloud. Does it convey the Skill's purpose in under 15 seconds? If not, trim.

A Skill that's too verbose is a Skill that quietly degrades every other Skill on the system. The author who writes the most comprehensive Skill is often the author whose teammates' Skills perform slightly worse afterward.

Cross-Vendor Portability in May 2026

One reason SKILL.md is interesting is that the same file works across hosts. As of May 2026:

• Claude Desktop, Claude Code, Claude.ai. Anthropic's hosts. Original SKILL.md spec; full feature support.
• Codex CLI. OpenAI's CLI host. Adopted SKILL.md in February 2026. Compatible with the manifest and body; resource invocation works for scripts.
• Gemini. Google announced SKILL.md support in April 2026 at Google I/O. Full support targeted by July 2026. Pre-release behavior already accepts SKILL.md.
• Third-party hosts. Cursor, Windsurf, Continue, and several internal-enterprise agent frameworks have community Skill loaders.

The portability is real but not absolute. Three caveats:

1. Resource invocation conventions vary slightly. Claude Code reads scripts under the Skill folder freely; Codex CLI requires a slightly different invocation path. Test resource-heavy Skills on each host you target.
2. Trigger sensitivity varies. Different model families pick up Skill triggers with different probability. A description that reliably triggers Claude Sonnet 4.5 may need adjustment to reliably trigger Gemini 2.5 Pro. Test before shipping multi-vendor.
3. Frontmatter extensions are not portable. Stick to the documented standard fields. Vendor-specific extensions reduce portability.

Five Skill Recipes You Can Adopt

Reference patterns, each with description, brief body sketch, and use case.

One: Slack-style code review reply

Description: "When the user pastes a code diff or PR description and asks for a reviewer-style reply for Slack, write a friendly, specific comment that points to the most important question or concern, frames it as a question not a directive, and is under 4 sentences."

Body sketch: Read diff; identify the single highest-impact question; phrase as a question; check tone; output as a code block.

Two: meeting-notes to action-items extraction

Description: "When the user provides meeting notes and asks for action items, extract clear, owner-bound, deadline-bound tasks. Each item: who, what, when. Group by owner. Output as a checklist."

Body sketch: Scan transcript; identify decision points and follow-ups; resolve "Sarah will handle" to {owner: Sarah, action: ..., due: ...}; group by owner; output checklist.

Three: contract-clause comparison

Description: "When the user provides two versions of a contract clause and asks for a diff, produce a clause-by-clause comparison that calls out substantive changes (rights, obligations, liability, dollar amounts) vs. cosmetic changes (renumbering, formatting)."

Body sketch: Tokenize clauses; pair by position and topic; classify each diff as substantive vs cosmetic; flag substantive with severity; output as a table.

Four: incident postmortem template fill

Description: "When the user provides incident details and asks for a postmortem draft, fill the team's standard postmortem template (summary, timeline, root cause, impact, action items). Use direct, blame-free language."

Body sketch: Read incident details; populate each section using the attached template file; use guidelines from attached style guide; mark unfilled sections as TODO; output ready-to-edit draft.

Five: research-paper triage

Description: "When the user pastes an arXiv abstract or PDF and asks 'should I read this,' produce a 3-line triage: relevance to the user's stated focus, what's novel, and what's the recommended action (read full, skim, skip)."

Body sketch: Read abstract; compare against user's research focus (from conversation); identify novel claim; recommend action with one-line justification.

Skills vs. Prompts vs. Tools

A clean mental model:

• Prompt: Static text that goes into every turn. System prompt, persona, base instructions. Cost: always loaded. Use for cross-cutting always-on guidance.
• Skill: Folder of guidance loaded conditionally on a matching request. Cost: manifest always loaded, body only on invocation. Use for repeated category-of-work guidance.
• Tool: Callable function the model invokes to take action. Cost: schema always loaded, executed on demand. Use for actions on systems.
• MCP server: Hosted bundle of tools published by a system owner. Cost: tools' schemas loaded; calls go over MCP transport. Use for reusable cross-team system access.

You will use all four together. The Skill describes what to do; the tool/MCP describes how to act on external systems; the prompt sets persona and high-level constraints. Lesson 4 of this chapter is the decision tree for picking the right one.

Auditing and Versioning Skills

Skills are files. Treat them like code:

• Source-control your Skills folder. Git or equivalent. Every Skill update is a commit; every commit has a message explaining why.
• Code-review Skill changes. A change to a widely-used Skill can shift behavior across the whole team. Review same as any code.
• Versioning in the manifest. Add a version field to the frontmatter; bump on changes. Roll back is easy when versions are visible.
• Eval Skills on real tasks. Maintain an eval set of 10-30 representative inputs per Skill. After every change, run the eval and confirm outputs are at least as good as the previous version.
• Skill catalog. A team-readable list of all installed Skills with one-line descriptions. Useful for onboarding and for catching duplicates or near-duplicates that should be merged.

The Skill Anti-Patterns to Avoid

• Vague descriptions. "Use this for documents" is too broad. The model will over-invoke. Tighten the trigger.
• Overlapping descriptions. Two Skills with descriptions that both plausibly match the same request. The model picks one based on subtle bias, behavior becomes unpredictable. Either merge or disambiguate.
• Stuffing. Putting everything you know about a topic into one Skill. Long Skills are slow Skills; split by sub-task.
• Hidden assumptions. A Skill that assumes the user is logged into a specific vendor with specific scopes will fail confusingly. Document assumptions in the body's first paragraph.
• No examples. A Skill without inline examples works half the time. Examples take five extra minutes and double consistency.
• No termination. Skills without explicit completion criteria run on, hallucinating extra steps. Always include "the Skill is done when..." guidance.

Key Takeaways

• A Skill is instructional packaging: a folder with SKILL.md (YAML frontmatter manifest + Markdown body of instructions) and optional attached resources. Loaded into model context conditionally when its description matches the request.
• Three structural parts: manifest (always-loaded short description), body (loaded on invocation, procedural instructions), attached resources (reference docs, scripts, templates loaded on demand).
• Cross-vendor portability in May 2026: SKILL.md runs unchanged inside Claude Desktop, Claude Code, Claude.ai; Codex CLI adopted in February 2026; Gemini support announced April 2026; community Skill loaders in Cursor, Windsurf, Continue. Resource invocation paths vary slightly across hosts; test before shipping multi-vendor.
• The bloated-system-prompt failure mode. Long Skill manifests load on every turn; 15 Skills × 3,000 words = 45,000 tokens of always-on overhead. Anthropic's February 2026 benchmark: task quality declines ~3-4% per extra 10K tokens of unused-but-loaded Skill manifests. Keep manifests under 150 tokens.
• Description-writing is the highest-leverage authoring step. Specific verb-noun triggers beat broad ones. "When the user asks to..." + the differentiator clause.
• Instructions pattern that works: lead with the goal, numbered steps, inline examples for subtle rules, edge-case section, explicit termination criterion. Under 500 words in the body when possible; push detail into attached resources.
• Five reference Skill recipes: Slack-style code review reply, meeting-notes to action-items extraction, contract-clause comparison, incident postmortem template fill, research-paper triage.
• The clean mental model. Prompt: always-on. Skill: conditional on request match. Tool: callable action. MCP server: hosted bundle of tools with vendor-specific implementation. Use all four together.
• Treat Skills like code: source-control, code-review changes, version in the manifest, maintain a 10-30 input eval set per Skill, document the team's full Skill catalog.
• Anti-patterns to avoid: vague descriptions, overlapping descriptions, stuffing, hidden assumptions, no inline examples, no explicit termination criterion.