Overview

What Are Agent Skills

Agent Skills are modular knowledge units that extend what an AI agent can do. Each skill is a directory containing a SKILL.md file (YAML frontmatter + Markdown instructions) and optional subdirectories for reference material, templates, and scripts.

The format follows the agentskills.io specification, an open standard adopted by over 30 agent tools — Claude Code, Gemini CLI, GitHub Copilot, Cursor, JetBrains Junie, and many more. Every skill uses the same directory layout:

skill-name/
├── SKILL.md          ← YAML frontmatter + markdown instructions (required)
├── references/       ← style guides, checklists, conventions (optional)
├── assets/           ← templates and output formats (optional)
└── scripts/          ← executable scripts (optional)

Because the format is universal, a skill written for one agent tool works in any other that follows the spec. Skills are portable, shareable, and version-controllable with git.

Why You Need Skills

Three signals that say it’s time to make a skill — any one of them is enough:

You keep pasting the same playbook — every time you start a class of task, you re-paste the same steps, checklist, or style guide into the chat. This is the most direct signal: turn it into a skill and the agent recalls it on its own next time, no copy-paste required
System prompt / CLAUDE.md is bloating — it started as “what the project is” (factual content), then crept into “in scenario X, do steps Y” (procedural content). The system prompt is paid for on every call, so procedural content makes the baseline more expensive — a skill only loads when it’s needed, pushing this content off the always-on path
The same rule is reused across multiple agents / projects — one “compliance checklist” runs in 5 agents; copying it 5 times guarantees 5 drifting copies. A skill is the single-source-of-truth + cross-agent reuse carrier

Take recruiting as a worked example — here is how the three signals show up in practice:

Signal ① — recruiters paste the same outreach template every time, then hand-edit the role, comp, and tone. Turn the templates into skills (e.g. outreach-senior-eng, outreach-passive-pm) and the agent picks the right one based on the candidate profile
Signal ② — the recruiting agent’s system prompt starts with company basics, then accretes GDPR candidate data handling (EU), EEOC adverse-impact checks (US), state- or country-specific pay transparency disclosure rules, and rejection-letter compliance language (GDPR Article 22 governs automated decisions, EEOC governs discriminatory language — a double constraint). All of this is procedural compliance content that should be split into separate skills loaded on demand
Signal ③ — if the same “EEOC adverse-impact checklist” lives separately in the sourcing, screening, and offer agents, three drifting copies will exist within six months. As a skill, it becomes a single source — whoever edits it owns the change

Recruiting is just one example — any industry that combines process flow + multiple roles + compliance constraints (healthcare, legal, financial customer support, insurance) maps to the same pattern: turn each repeatedly-used procedural artifact into a skill.

A skill isn’t “another container for prompts” — it’s the tool that turns when to load from static concatenation into a runtime decision. That’s what separates skills from “stitching markdown into the system prompt.” The next section unpacks the runtime mechanism.

Progressive Disclosure: L1/L2/L3

The conventional approach packs everything into a system prompt: compliance rules, style guides, API references, and troubleshooting procedures. At ten skills, this consumes thousands of tokens on every call, regardless of relevance.

Progressive disclosure solves this by loading knowledge in three levels, each fetched only when needed:

L1 — Metadata (~100 tokens per skill): The name and description fields from SKILL.md frontmatter. Loaded at startup for all skills. This is the “menu” the agent uses to decide what is relevant.
L2 — Instructions (<5,000 tokens recommended): The full skill body. Loaded only when the agent decides a specific skill is relevant.
L3 — Resources (as needed): Files in references/, assets/, or scripts/. Loaded only when the skill’s instructions reference them.

Token Savings

For an agent with 10 skills averaging 1,000 tokens each:

Approach	Tokens per call	When loaded
Monolithic system prompt	~10,000	Every call, all skills
Progressive disclosure	~1,000 baseline	L1 always; L2/L3 on demand

Approximately 90% reduction in baseline context, with full functionality available when needed.

How It Works in Practice

The three levels map to three agent actions:

Discovery (L1) — Agent sees a lightweight listing of all available skills. Each entry is just a name and description. The agent scans this to decide which skill matches the current task.
Activation (L2) — Agent loads the full instructions for the chosen skill. This is the step-by-step guidance: what to do, in what order, with what constraints.
Deep Reference (L3) — Agent loads specific reference files when the instructions say to. A style guide, a checklist, a template — only the file needed for the current step.

Designing for Progressive Disclosure

The Description Is Your Search Index

The description field in SKILL.md frontmatter is the most important line. It is the agent’s search index — if the description is vague, the agent will not activate the skill when it should.

Good description — specific keywords that match user intent:

SEO optimization checklist for blog posts. Covers title tags,
meta descriptions, heading structure, keyword placement,
and readability best practices.

Bad description — vague, no trigger words:

A helpful checklist for content.

Splitting Content Across Levels

Content type	Where it belongs	Why
Skill identity + trigger conditions	L1 (frontmatter)	Agent needs this to decide relevance
Step-by-step workflow	L2 (instructions)	Loaded once per skill activation
Detailed reference material	L3 (references/)	Loaded per-step, keeps L2 lean
Output templates	L3 (assets/)	Only needed at generation time

The key principle: push detail down. If instructions exceed a few hundred words, move the detailed knowledge into references/ and have the instructions point to it. The agent pays the token cost for L3 only when it actually needs that specific file.

Skill Types

Skills range from simple inline definitions to self-extending meta skills. Each type uses the same SKILL.md format but differs in where it lives, how it is shared, and what it does.

Type	Source	Reusability	Best for
Inline	Code (config object, dict)	Single agent	Simple checklists, stable rules
File-based	Local directory (SKILL.md + subdirs)	Any spec-compatible agent	Complex skills with reference docs
External	Community repository	Cross-agent portable	Skills someone else already wrote
Meta	Inline + L3 resources	Self-extending	Generating new skills on demand

Inline skills embed knowledge directly in code. Use them for small, project-specific rules that will not be reused.

File-based skills live in their own directory with a SKILL.md and optional references/, assets/, and scripts/ subdirectories. The directory name must match the name field in frontmatter. The design splits knowledge across L2 (instructions that tell the agent what steps to follow) and L3 (detailed reference material for each step).

External skills are file-based skills from sources outside your project — typically community repositories. Since all skills follow the agentskills.io spec, a skill written by anyone works in any compatible agent. The workflow: find, download into your skills/ folder, review, and load.

Meta skills teach the agent how to generate new SKILL.md files. An agent equipped with a meta skill becomes self-extending: it can expand its own capabilities by writing new skill definitions at runtime.

The meta skill’s instructions (L2) define rules for generating valid SKILL.md files — naming conventions, frontmatter requirements, instruction structure. Its references (L3) contain the agentskills.io specification itself plus a working example skill.

When asked to create a new skill, the agent:

Loads the meta skill instructions
Reads the spec and example via L3 references
Generates a complete SKILL.md following the spec
Outputs the file content ready to save

Key design rules for meta skills:

Name must be kebab-case, max 64 characters
Description must be under 1024 characters, with specific trigger keywords
Instructions should be clear, step-by-step
Detail goes in references/ — keep SKILL.md under 500 lines

Generated skills follow the same agentskills.io spec — they work in any compatible agent tool. Over time, the meta skill creates new skills, those get tested and refined, and the best ones get committed to the team’s library — an agent-driven flywheel for capability building.

skill/
  SKILL.md            # Instructions: rules for generating valid SKILL.md files
  references/
    specification.md  # The agentskills.io spec
    example-skill/    # A working example skill to learn from

For content design patterns (Tool Wrapper, Generator, Reviewer, Inversion, Pipeline), see the Design Patterns page.

Multi-Skill Composition

When an agent has access to multiple skills, it can autonomously decide which to load. The L1 metadata listing acts as a menu — the agent composes skills based on the task without explicit orchestration.

For example, asked to “write a blog introduction and make it SEO-friendly,” an agent can load both a blog-writer and seo-checklist skill in parallel — without being told to load both. The L1 descriptions gave it enough context to decide both were relevant.

Equally important is the negative case: when asked about a capability it does not have, a well-designed agent checks the L1 listing and responds that no matching skill exists. No hallucination, no attempt to fake a capability.

Skill Ecosystem

Community Repositories

Repository	Focus
skills.sh	Community marketplace (86,000+ installations)
google-gemini/gemini-skills	Official Gemini API best practices
vercel-labs/agent-skills	React, Next.js, deployment patterns
supabase/agent-skills	Postgres optimization guidelines
anthropics/skills	Production document skills
awesome-claude-skills	100+ skills organized by domain

Storage Conventions

Project-level (<project>/.agents/skills/) — Team-shared skills that live with the codebase
User-level (~/.agents/skills/) — Personal skills across all projects

Skills are version-controllable with git. Teams can maintain shared skill libraries, tag releases, and load them into any agent that follows the spec. Over time, as meta skills generate new skills that get tested and refined, the library grows without manual authoring — an agent-driven flywheel for capability building.

References

Agent Skills Specification — The open standard defining SKILL.md format
What Are Agent Skills? — Conceptual overview from agentskills.io

Content in this series is adapted from Lavi Nigam’s Agent Skills articles.