Agent skills are reusable, portable instruction packages
for AI coding tools — Markdown files that teach your AI agent how to perform
specific tasks, follow your coding conventions, or apply domain expertise.
⚡ TL;DR
An agent skill = a folder with a
SKILL.md
file. The file has a YAML frontmatter header (name, description) and a Markdown body
(the instructions). Drop it in
.claude/skills/
(or equivalent for your tool). The AI discovers it at startup and loads instructions
when you activate the skill. No servers, no build steps, no configuration.
How Agent Skills Work
Agent skills follow a three-tier progressive loading model
designed to minimize context window usage while keeping all skills available on demand:
1
🔍 Discovery at startup
The AI tool scans the skills directory and reads only the YAML frontmatter from each SKILL.md. This costs ~100 tokens per skill regardless of how long the instructions are.
2
⚡ Activation on demand
When you reference a skill by name (or the agent decides it's relevant), the full SKILL.md instruction body is loaded into context. Only then does the agent "know" the skill.
3
📂 Resources loaded lazily
Supporting files in scripts/, references/, and assets/ subdirectories are loaded only when the agent needs them for a specific step — never all at once.
Anatomy of a SKILL.md File
Every agent skill has a
SKILL.md
at its root. Here is a complete annotated example:
# TypeScript Strict Mode # body: loaded on activation
## Type Safety Rules
- Never use `any`. Use `unknown` and narrow with type guards.
- All function parameters must have explicit types.
- All function return types must be explicitly declared.
## Null Handling
- Always handle `null` and `undefined` explicitly.
- Use optional chaining `?.` and nullish coalescing `??`.
- Never use non-null assertion `!` unless unavoidable.
How to Install Agent Skills
Three ways to install an agent skill, from quickest to most maintainable:
--- name: My Skill Name description: One specific sentence about what this skill enforces or teaches. version: 1.0.0 authors: [your-github-handle] tags: [tag1, tag2] ---
# My Skill Name
## Rule Category One
- Always do X when Y.
- Never use Z for this purpose.
## Rule Category Two
- Prefer A over B because C.
- When you see D, replace with E.
✍️ Writing tip:
The description field is read at startup every session.
Make it specific enough that the AI knows exactly when to activate this skill
without reading the full body.
Bad: "Helps with code quality."
Good: "Enforces OWASP Top 10 security rules and flags SQL injection, XSS, and hardcoded secrets."
Agent skills are model-agnostic — they are plain text instructions loaded into the context window. They work with Claude, GPT-4, Gemini, or any model that the hosting platform uses. The skill standard is about file format and loading behavior, not about a specific model.
Can I use multiple agent skills at the same time? ＋
Yes. You can have dozens of skills installed and activate several in a single session. The progressive loading model ensures only the skills you actually use consume context tokens. Activating 3-5 skills simultaneously is common for complex tasks.
Are agent skills the same as system prompts? ＋
Not exactly. System prompts are set once and apply globally. Agent skills are modular — each covers one specific domain, and you choose which to activate per task. Skills are also portable: the same SKILL.md works across platforms, while system prompts are usually platform-specific configuration.
Can agent skills execute code? ＋
Agent skills themselves are static Markdown — they cannot execute code. However, skills can instruct the AI agent to use the platform's built-in tools (terminal, file editor, browser) or call MCP servers. The skill tells the agent what to do; the agent's tool calls do the actual execution.
Where can I find community agent skills? ＋
Right here — agentskills.my is the community directory. You can also find skills on GitHub by searching for repositories with the topic "agent-skills", on awesome-agent-skills, and in the official Anthropic skills repository.