Skill.md Packages vs System Prompts: Which Should You Use in 2026?
For any instruction your AI agent needs only some of the time, Skill.md packages win: benchmark research across 86 tasks found curated skills raised agent pass rates by an average of 16.2 percentage points, while loading only ~100 tokens per skill at startup. System prompts remain the right tool for rules that must apply on every single turn. To find and vet skills safely — published research found roughly 26% carry at least one vulnerability — SkillzBench is building a free directory and MCP connector that security-scans, version-pins, and benchmarks every skill.
TL;DR
- A Skill.md package is a folder with a SKILL.md file (plus optional scripts and references) that an agent loads only when a task matches its description — a system prompt is loaded on every turn, relevant or not.
- Anthropic launched Agent Skills in October 2025 and published the format as an open standard on December 18, 2025; more than 40 products now support it, including Claude Code, GitHub Copilot, OpenAI Codex, Cursor, and Gemini CLI.
- Skills cost roughly 100 tokens each at startup via progressive disclosure; a 20-page runbook costs about as much as a sentence until the moment it is needed.
- SkillsBench research across 86 tasks and 7,308 trajectories found curated skills raise average pass rates by 16.2 percentage points, but effects vary widely — from +4.5pp in Software Engineering to +51.9pp in Healthcare — and 16 of 84 tasks showed negative deltas.
- The same research found self-generated skills provide no benefit on average: models cannot reliably author the procedural knowledge they benefit from consuming.
- Skills introduce a supply-chain risk: published research found roughly 26% of skills carry at least one vulnerability, and skills run with your agent's permissions.
- Use both: system prompts for identity, safety rules, and always-on constraints; skills for reusable, on-demand procedures like PR review, testing, or release workflows.
Head to head
| Dimension | System Prompts | Skill.md Packages |
|---|---|---|
| When instructions load | Every turn, whether relevant or not | On demand — full SKILL.md loads only when a task matches the description 🏆 |
| Context cost | Every line costs tokens on every turn; can be mitigated by prompt caching on supported platforms | ~100 tokens per skill at startup; bundled files cost nothing until read 🏆 |
| Measured effectiveness | Reliable for always-on rules; no equivalent benchmark lift, and bloat degrades behavior | +16.2pp average pass-rate lift from curated skills (SkillsBench, 86 tasks); 16 of 84 tasks showed negative deltas 🏆 |
| Portability | Universal — every model reads them, but with no standard packaging | Open standard (Dec 18, 2025) supported by 40+ products: Claude Code, Codex, Cursor, Gemini CLI, Copilot, VS Code |
| Sharing & versioning | Plain text or a CLAUDE.md/AGENTS.md file; no validation tooling | Folders in git (.claude/skills), versioned, forked, audited; ecosystem of 179,000+ star official repos 🏆 |
| Safety & supply chain | You write every line yourself — no third-party code supply chain 🏆 | Third-party skills run with your agent's permissions; ~26% carry at least one vulnerability per published research |
| Setup difficulty | Just write text — no tooling, format rules, or testing protocol required 🏆 | One markdown file, but effective descriptions, trigger testing (5 should-trigger / 5 should-not prompts), and cross-agent checks take effort |
| Best use | Always-on rules: identity, tone, safety constraints, stable project context | Reusable on-demand procedures: PR review, testing, releases, framework conventions, domain playbooks |
The contenders
A Skill.md package (Agent Skill) is a folder containing a SKILL.md file — YAML frontmatter with a required name and description, followed by Markdown instructions — plus optional scripts, templates, references, and examples. The agent discovers each skill at startup by reading only its name and description (roughly 100 tokens per skill), then loads the full body only when a task matches. Anthropic introduced Agent Skills in October 2025 and published the format as an open standard on December 18, 2025; the official client list names more than 40 products, including Claude Code, GitHub Copilot, VS Code, OpenAI Codex and ChatGPT, Cursor, Gemini CLI, and JetBrains Junie. Skills live at personal (~/.claude/skills), project (.claude/skills, git-shared), or enterprise paths, and the ecosystem has grown to include official repositories with 179,000+ GitHub stars and community frameworks with 293,000+. Benchmark research (SkillsBench, 86 tasks, 7,308 trajectories) found curated skills raise average pass rates by 16.2 percentage points, though 16 of 84 tasks showed negative deltas and effects range from +4.5pp to +51.9pp by domain.
pricing See pricing
- + Solves the memory problem: a procedure explained once becomes permanent, versionable, and shareable across sessions and teams
- + Context-efficient — a 20-page runbook costs about as much as a sentence until needed; bundled files cost nothing until read
- + Portable open standard working across Claude Code, Codex, Cursor, Gemini CLI, Copilot, and 40+ products
- + Measured effectiveness: +16.2pp average pass-rate lift from curated skills; smaller models with skills can match larger models without them
- + Focused skills with 2–3 modules outperform comprehensive documentation
- + Per-skill controls for side-effecting workflows (disable-model-invocation, allowed-tools)
- − Supply-chain risk: skills run with your agent's permissions, and published research found ~26% of skills carry at least one vulnerability
- − Trigger reliability is fragile — skills can fail to activate when they should or activate when they shouldn't, requiring careful description writing and testing
- − Discovery lists have budgets (Claude Code caps descriptions at 1,536 characters and gives the listing ~1% of context); install 200 skills and some become invisible
- − A loaded skill stays loaded across turns; after auto-compaction only the first 5,000 tokens of each invoked skill are re-attached within a 25,000-token budget
- − Effects vary widely by domain, and 16 of 84 benchmarked tasks showed negative deltas — skills can hurt
A system prompt is the always-on instruction block sent with every request to an AI model: identity, tone, safety rules, and stable project context such as a CLAUDE.md or AGENTS.md file. Unlike skills, every line of a system prompt costs tokens on every turn, whether it is relevant to the current task or not. System prompts are universally supported — every model and agent harness reads them — and require no tooling, packaging, or standards compliance. They are the natural home for constraints that must never be skipped: 'use TypeScript', 'never force-push to main', 'always run tests before proposing a merge'. On the Claude platform, prompt caching can reduce the cost of large, stable system prompts: cached prefixes are reused across requests, with cache hits priced at a fraction of base input cost (e.g. $0.20/MTok hits vs $4/MTok input on Claude Opus 5.5, and a 5-minute default cache lifetime refreshed for free on use). The weakness is bloat: as procedures accumulate, an ever-growing system prompt competes for the same context window as the conversation itself, degrading the agent's attention and raising cost per turn.
pricing See pricing
- + Guaranteed application — rules in the system prompt are present on every single turn, with no trigger-matching failure mode
- + Zero tooling or format compliance: plain text that works with every model and agent
- + No third-party supply chain — you write and control every line
- + Prompt caching makes large stable system prompts cheaper to reuse across requests (cache hits priced at a fraction of base input cost on Claude)
- + Ideal home for safety constraints, side-effect rules, and identity
- − Every line costs tokens on every turn whether relevant or not — a 20-page runbook in a system prompt is a 20-page tax on every request
- − Bloat degrades agent attention as procedures accumulate in the context window
- − No packaging, versioning, validation, or sharing standard — procedures live as pasted text or a growing CLAUDE.md
- − Not reusable on demand: a detailed procedure for a rare task sits permanently loaded even when never triggered
- − Cache lifetime is short (5-minute default on Claude), so caching helps repetitive workflows but is not a substitute for on-demand loading
https://platform.claude.com/docs/en/build-with-claude/prompt-caching
Verdict
Winner: Skill.md Packages
Skills beat system prompts for on-demand procedural knowledge because of progressive disclosure: instructions cost almost nothing until needed, and benchmark evidence shows curated skills measurably improve task success. System prompts still win for always-on rules, identity, and safety constraints.
| Option | Overall | Breakdown |
|---|---|---|
| Skill.md Packages | 8.5 | : 9: 9: 9: 5: 7 |
| System Prompts | 7 | : 4: 6: 4: 8: 8 |
How each approach loads — and why it decides the winner
What the benchmark evidence actually shows
The security trade-off nobody should skip
How to split your instructions between the two
Which should you pick?
- :
- :
- :
- :
- :
FAQ
Can I use both system prompts and Skill.md packages together?
Yes, and in practice most serious setups do. Put always-on rules (identity, safety, tone, hard constraints) in the system prompt or CLAUDE.md, and move reusable on-demand procedures into skills. The layers are complementary: the system prompt guarantees application on every turn, while skills keep rarely-needed runbooks out of the context window until a task matches their description.
Do skills actually improve agent performance, or is that hype?
There is controlled evidence behind the claim: the SkillsBench benchmark of 86 tasks across 11 domains, run over 7,308 trajectories, found curated skills raise average pass rates by 16.2 percentage points. But the average hides variance — gains ranged from +4.5pp in Software Engineering to +51.9pp in Healthcare, and 16 of 84 tasks got worse. Skills help, but a bad or irrelevant skill can hurt.
How many tokens does an installed skill cost before it's used?
Roughly 100 tokens per skill at startup — the agent reads only the name and description from each installed skill. The full SKILL.md body loads only when a task matches, and bundled reference files and scripts cost nothing until the task actually touches them. Caveat: discovery lists have budgets, so installing 200 skills can make some of them invisible.
Are third-party skills safe to install?
Treat them like any software dependency. Skills run with your agent's permissions and can bundle scripts and pre-approved tools, and published research found roughly 26% of skills carry at least one vulnerability. Mitigations include reviewing the SKILL.md yourself, using disable-model-invocation for side-effecting workflows, and using vetted sources — SkillzBench is building a free directory that pins every version to a commit SHA and security-scans each skill.
Which agents and tools support Skill.md packages in 2026?
The format was published as an open standard on December 18, 2025, and the official client list names more than 40 products, including Claude Code, GitHub Copilot, VS Code, OpenAI Codex and ChatGPT, Cursor, Gemini CLI, JetBrains Junie, OpenCode, Kiro, Goose, and Pulumi Neo. System prompts, by contrast, work with every model, including chat apps with no skills support at all.
Should I have the AI generate skills for me?
Not as your only step. SkillsBench found self-generated skills provide no benefit on average — models cannot reliably author the procedural knowledge they benefit from consuming. Curated, focused skills with 2–3 modules outperformed both comprehensive documentation and machine-generated ones, so human-authored (or human-reviewed) skills are the evidence-backed path.