SKILL.md: How AI agents learn — and stay secure.
The open standard behind modern AI agents: Progressive Disclosure, the most common mistake — and why Agent Skills are a new attack surface. From the fundamentals to governance under ISO 42001 and the EU AI Act.
Sources: Anthropic — “Agent Skills” as an open standard (Dec 18, 2025) · B. Poudel — “The SKILL.md Pattern” (Medium, Feb 2026) · OWASP — Agentic Skills Top 10 (v1.0, 2026)
What is an Agent Skill?
Not a plugin. Not an API script. A skill is like an onboarding guide for a new colleague — packaged once, used automatically.
At its core, a skill is just a folder. The only required file is SKILL.md — everything else is optional and grows with complexity.
MCP vs. Skills — the mental model
The plumbing
Defines how the agent is connected to tools, APIs, and data — which resources and actions are available in the first place.
The manual
Defines how the agent uses those tools step by step to achieve a concrete goal — the procedural knowledge.
Rule of thumb: MCP = how the model talks to tools. Skills = what those tools actually do.
Progressive Disclosure
Content is loaded only when it is needed — like a manual: first the table of contents, then the chapter, then the appendix.
Level 1 · Metadata
name + descriptionalways loaded · ~dozens of tokens per skillLevel 2 · Instructions
full SKILL.md bodyon activation · < 5,000 tokensLevel 3 · References & scripts
files + executable codeon demand · virtually unlimitedIdle cost: practically zero. Scripts run without ever being loaded into context — no matter how much a skill bundles.
The most common mistake: the description
The description is not for humans. It is the trigger condition the agent uses to decide whether to activate the skill at all.
[ What the skill does ] + [ When — with concrete trigger phrases ]
“Helps with documents.”Describes the what — but never the when.
“Creates README.md. Use when the user says ‘write a README’ or ‘document the project’.”What + when, with concrete trigger phrases.
An open standard — backed by everyone
Published by Anthropic as an open standard on December 18, 2025. Adopted within weeks by:
“The file is the contract. The platform implements the interface.”
A skill you write today is portable across all platforms. < 50 → 500+ new skills per day (Jan → Feb 2026).
A skill is code + instructions that your agent executes. That makes every skill a new attack surface — and a new governance object.
The consent gap
Once a skill is approved, it silently inherits persistent privileges — with no further prompts: reading and writing files, fetching code, opening network connections.
“From SKILL.md to shell in three lines of Markdown.” — Snyk
Persistence: Skills can poison AGENTS.md / MEMORY.md / SOUL.md — leaving backdoors that survive across sessions.
The “Lethal Trifecta”
- Private data — SSH keys, API credentials, wallets, browser data
- Untrusted content — skill instructions, memory files, incoming email
- External communication — network egress, webhooks, curl calls
When all three converge in one skill, a single hidden instruction is enough for silent data exfiltration. Most production deployments today meet all three. (Simon Willison / Palo Alto Networks, 2026)
The threat is real — Q1 2026
Agent Skills are a software supply chain — and it is already under active attack.
> 25% of 30,000+ analyzed skills contain at least one vulnerability. They demand the same diligence as npm, PyPI, and container registries.
OWASP Agentic Skills Top 10
The ten most critical risks of the “behavior layer” — an OWASP incubator project, version 1.0 (2026).
Malicious Skills
criticalSupply Chain Compromise
criticalOver-Privileged Skills
highInsecure Metadata
highUnsafe Deserialization
highWeak Isolation
highUpdate Drift
mediumPoor Scanning
mediumNo Governance
mediumCross-Platform Reuse
mediumSkills meet your governance
OWASP explicitly names GRC & compliance as an audience — with the core task of mapping skill risks onto established frameworks.
NIST AI RMF
govern · map · measure · manage
ISO/IEC 42001
AI management system
EU AI Act
documentation · change control · evidence
OWASP AIVSS
LLM & Agentic Top 10
Skills become part of your AI inventory, your risk assessment, and your audit evidence.
From risk to control
Provenance & signing
ed25519 · content_hash · Merkle verification
Least privilege
Allowlist instead of “network: true” — protect identity files
Isolation
Sandbox/container by default, host mode opt-in only
Scanning
semantic + behavior-based, not just pattern matching
Pinning
immutable hashes instead of version ranges
Honest metadata
risk_tier L0 (safe) to L3 (destructive)
The skill governance lifecycle
Six steps that turn individual skills into an auditable estate.
- 1
Inventory
Capture all skills across all platforms.
- 2
Review
Read and scan code & instructions.
- 3
Approve
Approval workflow, trusted sources.
- 4
Restrict
Enforce a least-privilege manifest.
- 5
Monitor
Audit file, network & memory activity.
- 6
Audit
Evidence for ISO 42001 / EU AI Act.
First steps for your team
For security & GRC
- Build a skill inventory across all agent platforms
- Establish an approval workflow & release policy
- Enable audit logging for all skill actions
- Govern agentic identities & permissions
- Subscribe to security advisories (platforms & registries)
For skill authors
- Minimal permission manifest (least privilege)
- Sign skills (ed25519) + declare content_hash
- Pin dependencies to immutable hashes
- Protect identity files — no write access
- Declare risk tier & scope honestly
Frequently asked questions
What is an Agent Skill — and what is SKILL.md?
An Agent Skill is a folder of procedural knowledge for AI agents — like an onboarding guide for a new colleague: packaged once, used automatically. The only required file is SKILL.md (instructions + metadata); scripts/, references/, and assets/ are optional and grow with complexity.
How do Skills differ from MCP?
MCP is the plumbing: it defines how the agent is connected to tools, APIs, and data. Skills are the manual: they define how the agent uses those tools step by step to achieve a concrete goal. Rule of thumb: MCP = how the model talks to tools. Skills = what those tools actually do.
Why doesn't my skill trigger?
The most common mistake is in the description: it is not for humans — it is the trigger condition the agent uses to decide whether to activate the skill. A strong description states the what and the when, with concrete trigger phrases. “Helps with documents” describes only the what and therefore triggers unreliably.
Are Agent Skills an open standard?
Yes. Anthropic published Agent Skills as an open standard on December 18, 2025. Within weeks it was adopted by OpenAI (Codex & ChatGPT), Google (Gemini CLI), GitHub Copilot, Cursor, and the Microsoft Agent Framework, among others. A skill you write today is portable across all platforms.
What security risks do Agent Skills introduce?
A skill is code plus instructions that your agent executes — a new attack surface and a software supply chain. Snyk audited 3,984 skills and found security flaws in 36% (13.4% critical). The OWASP Agentic Skills Top 10 systematizes the risks, from Malicious Skills (AST01) to Cross-Platform Reuse (AST10). It gets dangerous when private data, untrusted content, and external communication converge in a single skill — the “Lethal Trifecta”.
How do Skills become enterprise-ready?
With a governance lifecycle: inventory, review, approve, restrict, monitor, audit — plus technical controls such as signatures (ed25519), least-privilege manifests, sandbox isolation, and hash pinning. Skill risks can be mapped onto ISO/IEC 42001, the EU AI Act, the NIST AI RMF, and OWASP, becoming part of your AI inventory and your audit evidence.
Make agentic AI secure and auditable.
Valeri Milke — CEO | ISO 27001 & ISO 42001 LA | IEC 62443 & SAE 21434 & CRA | AI Officer (AI Act) | NIS2 & DORA Expert | BSI IT-Grundschutz Practitioner | Certified Data Protection Officer (IHK)
AI-Driven IT-Security and Compliance Experts