Claude Skills: How Agents Get Specialised in 2026

A directory and a markdown file are all it takes

A Claude Skill is a folder with a SKILL.md file containing YAML frontmatter and Markdown instructions. The frontmatter requires exactly two fields:

---
name: processing-pdfs          # max 64 chars, hyphens only, no "claude"
description: >                 # max 1,024 chars — this is the pivot point
  Use when the user asks to extract text, tables, or images from a
  PDF file. Activates for both local files and URLs.
license: MIT                   # optional
compatibility: claude-code     # optional, max 500 chars
---

## Purpose
Describe what the skill does and why it exists.

## Triggers
Exact scenarios where Claude should activate this skill.

## Steps
1. Step one
2. Step two

## Outputs
What the skill produces.

The minimum viable skill is just that single file. Optional extras include domain-specific reference files (FORMS.md, REFERENCE.md), scripts in a scripts/ subdirectory, and other assets.

The three-level architecture that keeps things fast

What makes the format practical at scale is progressive disclosure. Claude loads skills in three levels:

A workspace with dozens of installed Skills pays only the metadata cost up front. This also means the description field is the single most critical thing a skill author writes — a vague description is the most common reason a skill never fires at all.

Scripts are especially efficient: Claude executes them via bash and receives only their output, so the script code itself never enters the context window.

Four paths to build a skill

Anthropic offers four distinct creation routes, making Skills accessible well beyond the developer audience.

Writing a skill that actually fires

Best practices from official documentation and the community converge on the same principles. A recommended skill structure includes sections for Purpose, Triggers, Inputs, Steps, Outputs, and a Refusal & Escalation policy.

1. 1Write the description in third person describing the exact situation — “Use when writing a git commit message for staged changes” beats “Helps with git”
2. 2Keep the SKILL.md body under 500 lines; long reference material belongs in subdirectory files that load on demand
3. 3Name skills in gerund form: processing-pdfs, analyzing-spreadsheets, not process-pdf or pdf-tool
4. 4Include a Refusal & Escalation section — especially important for skills that coordinate MCP tools and may hit decision points you didn't anticipate
5. 5Validate before publishing: npx skills-ref validate ./my-skill
6. 6Test in at least two agents before claiming a skill is portable — agent-specific extensions like context: fork are silently ignored by other tools
7. 7Treat third-party skills exactly like npm packages: inspect the code, pin versions, install only from sources with a verifiable publication history

An open standard and a fast-growing ecosystem

The open standard — published at agentskills.io on December 18, 2025 — is technically the same SKILL.md format Anthropic already used internally, formalised with governance transferred to the Linux Foundation's Agentic AI Foundation (AAIF). OpenAI and Microsoft integrated support within 48 hours of publication — almost certainly indicating pre-announcement coordination.

By March 2026, 32+ tools had adopted the standard:

The partner skills directory launched alongside the standard with seven inaugural integrations available at claude.com/connectors:

Beyond the official directory, the community GitHub repository ComposioHQ/awesome-claude-skills reached approximately 77,000 stars within twelve months of its October 2025 creation. The independent marketplace claudemarket.ai indexes over 4,384 skills. The CLI tool skills.sh tracks 876,990 all-time installs across 20+ supported agents.

Skills are complementary to, not replacements for, MCP servers. Anthropic's own framing describes MCP as a hardware store (access to supplies) and a skill as the employee who knows which supplies to use and in what order. One skill can coordinate multiple MCP servers — for example, a meeting-prep skill might draw on a Notion MCP for documents, a Calendar connector for scheduling, and a Slack MCP for recent context.

Security risks the ecosystem is still catching up on

The ClawHavoc campaign in early 2026 is the ecosystem's most significant security event to date.

The attack surface is broader than it first appears:

• Skills inherit the agent process's full privileges — filesystem, cloud credentials, and environment variables all extend to any loaded skill
• Removal does not always clean up — some malicious skills wrote instructions into agent memory files, so backdoors persisted after deletion
• No version pinning means a clean skill at install time can be updated later with malicious code
• Static pattern-based review cannot reliably catch environment-gated payloads or logic hidden in bundled scripts

The community response has included OpenClaw Scanner (a VirusTotal integration), SecureClaw as a separate scanning tool, and the travisvn/awesome-claude-skills GitHub list, which provides editorial curation and explicit security warnings rather than automated scanning.

The OWASP Agentic Skills Top10 v0.5 is the current public reference for the full risk landscape. The practical implication for any organisation is to treat third-party skills exactly as they would treat npm packages: inspect the code, pin versions, and only install from sources with a verifiable publication history.