Agent Skills Overview

What are Agent Skills, how progressive disclosure works, and how to organize skills across projects

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.

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:

ApproachTokens per callWhen loaded
Monolithic system prompt~10,000Every call, all skills
Progressive disclosure~1,000 baselineL1 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:

  1. 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.

  2. 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.

  3. 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.

Progressive Disclosure: L1 / L2 / L3 Skills load knowledge on demand, not all at once Without Skills System Prompt Approach ALL Instructions ~1,500 tokens loaded on EVERY call s1 s2 s3 ... s20 20 skills = ~20,000 tokens (all upfront) With Skills Progressive Disclosure Approach L1 Metadata name + description ~50 tok/skill L2 Instructions SKILL.md body ~1,000 tokens L3 Resources reference files, datasets ~1,000 tokens Always loaded Loaded on demand via load_skill Loaded on demand via load_skill_resource 20 skills = ~1,000 tokens (L1 only) L1 Metadata L2 Instructions L3 Resources

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 typeWhere it belongsWhy
Skill identity + trigger conditionsL1 (frontmatter)Agent needs this to decide relevance
Step-by-step workflowL2 (instructions)Loaded once per skill activation
Detailed reference materialL3 (references/)Loaded per-step, keeps L2 lean
Output templatesL3 (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.

TypeSourceReusabilityBest for
InlineCode (config object, dict)Single agentSimple checklists, stable rules
File-basedLocal directory (SKILL.md + subdirs)Any spec-compatible agentComplex skills with reference docs
ExternalCommunity repositoryCross-agent portableSkills someone else already wrote
MetaInline + L3 resourcesSelf-extendingGenerating 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.

Pattern: Meta Skill A skill that generates new SKILL.md files on demand ✎ Meta Skill skill-creator Rules for generating valid SKILL.md files L3 Reference specification.md L3 Reference example-skill.md generates ✦ New SKILL.md python-security-review Spec-compliant, portable ⚙ Any Agent self-extending Generated skills follow the same spec — portable across all compatible agents

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:

  1. Loads the meta skill instructions
  2. Reads the spec and example via L3 references
  3. Generates a complete SKILL.md following the spec
  4. 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.

Multi-Skill Composition Agent autonomously selects and composes skills from the L1 menu User Query "Blog + SEO" ☰ L1 Skill Menu blog-writer code-reviewer seo-checklist deploy-guide parallel load L2 Instructions blog-writer L2 Instructions seo-checklist ✓ Combined Output The agent decides which skills to load — no orchestration needed

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

RepositoryFocus
skills.shCommunity marketplace (86,000+ installations)
google-gemini/gemini-skillsOfficial Gemini API best practices
vercel-labs/agent-skillsReact, Next.js, deployment patterns
supabase/agent-skillsPostgres optimization guidelines
anthropics/skillsProduction document skills
awesome-claude-skills100+ 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

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

Was this page helpful?
Edit on GitHub