↓ Skip to main content
Alejandro AO
Agent Skills Explained - Full Crash Course

Agent Skills Explained - Full Crash Course

·1125 words·6 mins
Alejandro AO
Author
Alejandro AO

Software Engineer and Educator. Developer Advocate at Hugging Face 🤗

I help you build AI Apps that just work.

Table of Contents

Skills are reusable capabilities for AI agents. They provide procedural knowledge that helps agents accomplish specific tasks more effectively. Think of them as plugins that extend agent functionality—except they’re just markdown files.

In this tutorial, you’ll learn:

  • What agent skills are and why they matter
  • How to install skills using the skills.sh CLI
  • How to create your own custom skills
  • Best practices for building effective skills

What Are Skills?
#

Skills started in October 2025 when Anthropic introduced Claude Code agent skills. Since then, the format has become an open standard adopted by OpenAI Codex, Microsoft, GitHub, Cursor, and other AI agent builders.

At their core, skills are markdown files with clear, specialized instructions about something specific. They contain:

  • A YAML frontmatter with name and description fields
  • Markdown content with instructions for the agent to follow

Here’s a simple example:

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

The description field is crucial—it’s what the agent sees before loading the skill. Claude uses this to decide when the skill is relevant.

The Skills.sh CLI
#

In late December 2025, Vercel released skills.sh, a CLI tool that makes installing and managing skills effortless. Let’s see how it works.

Installing a Skill
#

To add a skill from a GitHub repository:

npx skills add owner/repo-name

The CLI will:

  1. Fetch available skills from the repository
  2. Let you select which skill to install
  3. Ask which agents you want to enable it for (Claude Code, Codex, etc.)
  4. Set the installation scope (project or global)

For example, to install the frontend-design skill:

npx skills add anthropics/skills

Then select “frontend-design” from the list. The skill is now available in your project.

Verifying Installation
#

After installation, you can verify the skill is loaded:

/skills

This shows all available skills in your current project.

Demo: Frontend Design Skill
#

Let’s see skills in action. I ran the same prompt on two Claude Code instances—one with the frontend-design skill installed, and one without.

The prompt:

Fix the style of the UI of the landing page. Make it look modern and appealing. Include a FAQ, pricing section with three plans, a hero, feature sections, and a CTA email form.

Without the skill: The result was functional but looked like typical AI-generated content—clean but generic.

With the skill: The output was significantly more polished, with thoughtful design choices that avoided the common “AI slop” aesthetic.

The only difference was loading the skill beforehand. That’s the power of teaching your agent specialized knowledge.

Creating Your Own Skills
#

Skills become truly powerful when you create custom ones for your specific workflows. Here’s how to build and share them.

Initialize a New Skill
#

First, create the skills directory structure:

mkdir -p skills
npx skills init video-editing --path skills/video-editing

This creates a SKILL.md file with the basic structure:

---
name: video-editing
description: Your skill description
---

Your instructions here...

Use the Skill Creator
#

Here’s a neat trick: use the skill-creator skill to help build your skills. It’s developed by Anthropic and teaches Claude how to create effective skills.

npx skills add anthropics/skills
# Select "skill-creator"

Now you can ask Claude to create a skill based on documentation, a GitHub repo, or your own notes.

Skill Structure
#

A complete skill can include multiple files:

skills/
└── my-skill/
    ├── SKILL.md           # Main instructions (required)
    ├── reference.md       # Detailed docs
    ├── workflows.md       # Common workflows
    ├── templates/         # Templates for generation
    └── scripts/           # Helper scripts

The SKILL.md file is the entry point. Link to additional resources from there:

---
name: video-tool
description: Video processing CLI for editing, transcribing, and uploading videos
---

# Video Tool Skill

Process videos using the video-tool CLI.

## Quick Start
- `video-tool video download -u URL` - Download from YouTube
- `video-tool generate transcript -i video.mp4` - Transcribe with Whisper

## Additional Resources
- See [workflows.md](workflows.md) for common tasks
- See [templates/](templates/) for output templates

Sharing Skills
#

To share your skill, push it to a GitHub repository. Anyone can then install it:

npx skills add your-username/your-repo

You can include skills in the same repository as your project. This is convenient when the skill is tightly coupled to the codebase—updates to the code and skill stay in sync.

Skills in Claude Code
#

Claude Code extends the agent skills standard with additional features:

Invocation Control
#

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

disable-model-invocation: true means only you can trigger the skill (not Claude automatically). Use this for workflows with side effects.

String Substitution
#

Skills support dynamic values:

---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Running /fix-issue 123 replaces $ARGUMENTS with “123”.

Subagent Execution
#

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

context: fork runs the skill in an isolated subagent context.

Best Practices
#

Based on experience building skills, here are key guidelines:

  1. Start with existing skills - Browse skills.sh and install popular skills to understand what works well.

  2. Create skills for repetitive workflows - If you find yourself explaining the same process to Claude repeatedly, that’s a skill waiting to be created.

  3. Iterate on your skills - The first version rarely works perfectly. Run the workflow, identify edge cases, and update the skill accordingly.

  4. Use clear descriptions - The description field determines when Claude loads the skill. Be specific about what it does and when to use it.

  5. Keep SKILL.md focused - Put detailed reference material in separate files. The main skill file should be under 500 lines.

  6. Use global vs project scope wisely:

    • Global: Tools you use across projects (skill-creator, frontend-design)
    • Project: Project-specific workflows (your app’s deployment process)

  7. Lock your skills - Once a skill is validated, commit it to version control to avoid accidental changes.

Where Skills Live
#

LocationPathApplies to
Personal~/.claude/skills/<name>/SKILL.mdAll your projects
Project.claude/skills/<name>/SKILL.mdThis project only
Plugin<plugin>/skills/<name>/SKILL.mdWhere plugin is enabled

Higher-priority locations win when skills share the same name.

Conclusion
#

Skills are simple but powerful: markdown files that teach AI agents specialized knowledge. They’re portable across tools, easy to create, and shareable with the community.

Start by:

  1. Installing a few popular skills from skills.sh
  2. Creating a skill for a workflow you do frequently
  3. Iterating until it handles edge cases well
  4. Sharing useful skills with the community

The agent skills ecosystem is still young. Now’s a great time to build skills for workflows you know well—they could become the go-to solutions for thousands of developers.

References
#