What Are Skills? The Complete Guide to AI Agent Extensions

A skill is a markdown file (SKILL.md) that teaches AI agents how to perform specific tasks. It contains metadata in YAML frontmatter (name, description, author, tags) and instructions in the body. Skills are modular, shareable, and version-controlled. They solve the problem of repeatedly explaining the same context to AI assistants by encoding domain knowledge once and reusing it across sessions and projects.

You have used AI assistants. You know the drill. Every new conversation starts from scratch. Every project requires the same explanations. Every integration means walking through the same documentation again.

Skills change that equation entirely.

The Core Idea: Reusable AI Knowledge

Think about how you work with code. You do not rewrite utility functions from scratch every time. You import them. You share them. You version them.

Skills bring this same pattern to AI interactions. Instead of explaining your Slack workspace configuration in every chat, you encode it once in a skill file. Instead of walking Claude through your PostHog setup repeatedly, you create a skill that captures the context.

A skill is simply a markdown file with a specific structure. That is it. No complex tooling. No proprietary formats. Just markdown that AI agents can read and apply.

What Makes Up a Skill?

Every skill lives in a single file: SKILL.md. The structure is deliberate:

---
name: slack-integration
description: Configure and manage Slack workspace integrations. Use when building Slack bots, sending notifications, or managing channels.
author: Your Name
tags: [slack, integration, notifications, api]
---

# Slack Integration Skill

Instructions for the AI agent...

The frontmatter (the section between --- markers) contains metadata. The body contains actual instructions.

The Frontmatter

Four fields matter:

name: The identifier. Keep it lowercase, use hyphens. This becomes how others reference your skill.

description: Not just a summary. This is the trigger mechanism. AI agents read this field to decide whether to activate the skill. A good description says both what the skill does AND when to use it.

author: Your name or organization. Skills can be traced back to their creators.

tags: Keywords for discovery. When someone searches the registry, these tags determine whether your skill surfaces.

The Body

This is where you actually teach the AI. Write it like you are explaining to a capable colleague who needs specific context. Include:

• Key concepts the agent needs to know
• Step-by-step workflows
• Code snippets and examples
• Common pitfalls to avoid
• Edge cases worth mentioning

What you leave out matters too. Skip basic programming concepts. Skip generic explanations of well-known tools. Focus on the specific knowledge that makes your skill valuable.

Why Skills Beat Copy-Paste

You might wonder: why not just paste instructions into every conversation?

Three reasons:

Consistency: A skill file stays the same. Copy-paste degrades over time. You forget details. You skip steps when you are in a hurry. Skills encode your best practices permanently.

Shareability: Skills are files. Files go in repos. Repos get shared. Your entire team uses the same skill file. Updates propagate automatically.

Discovery: Skills in a registry are searchable. When you need a PostHog integration, you search for it. You do not reinvent the wheel wondering if someone already solved this.

The Skill Lifecycle

Skills follow a clear lifecycle:

1. Creation: You identify repeating context. You write a SKILL.md file.

2. Local testing: You drop the skill into .claude/your-skill/SKILL.md in your project. You verify it works as intended.

3. Publishing: You submit to the registry. Others can now discover and use your skill.

4. Installation: Users run sr install your-skill-name and get your skill in their project.

5. Evolution: You update the skill. Users reinstall to get improvements.

This lifecycle mirrors package management. That is intentional. Skills are packages of knowledge.

Where Skills Live

Skills can exist in several locations:

Project-local: The .claude/ directory in your project. Skills here apply only to that project.

User-level: A shared directory that applies across all your projects.

Registry: The public Skill Registry at skillregistry.io. Anyone can search and install.

When an AI agent starts working, it scans for available skills. It reads their descriptions. It activates relevant ones based on your request.

Bundled Resources

Sometimes instructions are not enough. Some skills include additional files:

my-skill/
├── SKILL.md           # Required: main instructions
├── scripts/           # Optional: executable code
│   └── setup.py
├── references/        # Optional: documentation
│   └── api-spec.md
└── assets/            # Optional: templates
    └── config.json

Scripts: Code the agent can run. Useful for complex setup tasks or API interactions.

References: Extended documentation the agent can consult. Keep SKILL.md focused; put detailed specs here.

Assets: Templates, configuration files, or other resources.

The SKILL.md file remains the entry point. Everything else supports it.

What Makes a Good Skill

Good skills share certain qualities:

Focused scope: One skill, one domain. A Slack skill handles Slack. It does not also configure your database.

Clear triggers: The description tells agents exactly when to activate. “Use when” clauses work well.

Concise instructions: Context windows are precious. Every word should earn its place.

Practical examples: Show, do not just tell. Include snippets that agents can adapt.

Honest limitations: If something does not work well, say so. Agents make better decisions with complete information.

The Registry Ecosystem

SkillRegistry exists because skills need a home. Scattered skills in random repos help no one. A central registry with search, categories, and curation makes skills actually useful.

The registry handles:

• Discovery: Search by keyword, category, or use case
• Quality: Reviewed skills that meet standards
• Versioning: Track skill evolution
• Installation: One command to add any skill

Think of it like npm for AI knowledge. The parallel is intentional.

Getting Started

Ready to try skills? Two paths:

Use existing skills: Browse the registry. Find something relevant. Install it. Watch your AI assistant get smarter.

Create your own: Identify context you repeat. Write a SKILL.md file. Test it locally. Submit to the registry.

Both paths lead to the same place: AI interactions that build on accumulated knowledge rather than starting from zero every time.