Documentation

Learn to use Skills

Everything you need to know about finding, installing, creating, and sharing skills for your AI coding agents.

What Are Skills?

Skills are reusable capabilities for AI coding agents. Unlike static documentation or simple prompts, skills provide procedural knowledge—they teach your AI assistant how to do things, not just facts about things.

Think of skills like plugins for your AI

Just as browser extensions add new features to Chrome, skills add new capabilities to AI agents. They come with instructions, scripts, and configurations that enable your agent to interact with external services and automate complex workflows.

Example Skills

GitHub integration — Create issues, open PRs, manage repositories
Weather APIs — Fetch forecasts and conditions from any location
Database management — Query, backup, and migrate databases
Deployment automation — Deploy to Vercel, AWS, Railway, and more
Notification services — Send Slack messages, emails, or SMS alerts

Cross-Agent Compatibility

Skills are designed to work across multiple AI coding agents:

Claude CodeCursorCodexWindsurfAiderGitHub Copilot

Anatomy of a Skill

At minimum, every skill contains a SKILL.md file. More complex skills include additional scripts and configurations:

my-skill/
├── SKILL.md          # Required: skill definition & docs
├── scripts/
│   ├── setup.sh      # Optional: installation script
│   └── run.py        # Optional: execution script
├── config/
│   └── settings.json # Optional: configuration
└── examples/
    └── usage.md      # Optional: usage examples

Installing Skills for Claude Desktop

There are two ways to install skills in Claude Desktop: using the built-in GUI or manually placing files. Once installed, skills become available as slash commands.

Option AUsing the GUI (Recommended)

1Open Claude Desktop and go to Settings (gear icon)
2Click on Capabilities
3Scroll down to the Skills section
4Click the + button to add a new skill
5Upload the SKILL.md file (and any additional files)

Option BManual Installation

For power users, you can manually place skill files in Claude's commands directory.

Global Skills (all projects)

# Create the directory and add your skill

$ mkdir -p ~/.claude/commands

$ cp weather.md ~/.claude/commands/

Project-Specific Skills

# In your project root

$ mkdir -p .claude/commands

$ cp deploy.md .claude/commands/

Using Your Installed Skill

Once installed, type the slash command (the filename without .md) to invoke the skill:

Example usage:

/weather Pittsburgh

Claude will read the skill instructions and execute the task accordingly.

Directory Structure

~/.claude/
└── commands/           # Global skills (all projects)
    ├── weather.md      → /weather
    ├── deploy.md       → /deploy
    └── git-commit.md   → /git-commit

your-project/
└── .claude/
    └── commands/       # Project-specific skills
        └── test.md     → /test

Submitting Skills

Ready to share your skill with the community? There are two ways to submit skills to the registry.

Option A: File Upload

1Go to the Submit page
2Drag and drop your skill folder (or select files)
3Include a SKILL.md with proper frontmatter
4Additional files (scripts, configs) are bundled with your submission
5Submissions go through review before appearing in the directory

Submit a Skill

Option B: GitHub Link

Coming Soon

Soon you'll be able to link directly to a GitHub repository:

Direct linking to your public GitHub repo
Automatic syncing when your repo updates
Version tracking tied to git tags

SKILL.md Format

Every skill requires a SKILL.md file. This file uses YAML frontmatter for metadata and Markdown for documentation.

Required Fields

Field	Type	Description
`name`	string	Human-readable name of the skill
`description`	string	Brief description of what it does
`version`	string	Semantic version (e.g., "1.0.0")

Complete Example

SKILL.md

---
name: Weather API Skill
description: Fetch weather data from OpenWeatherMap API
version: 1.2.0
author: weatherapi
category: api
agents:
  - claude-code
  - cursor
  - codex
---

# Weather API Skill

This skill enables your AI agent to fetch weather data.

## Setup

1. Get an API key from OpenWeatherMap
2. Set the environment variable:
   export OPENWEATHER_API_KEY="your-api-key"

## Usage

Ask your agent:
- "What's the weather in Pittsburgh?"
- "Will it rain tomorrow in New York?"

Best Practices

Follow these guidelines to create skills that are useful, maintainable, and work well across different AI agents.

Stay Focused

Keep each skill focused on one capability. A skill that does one thing well is more reusable.

Clear Examples

Include usage examples in your SKILL.md. Show what prompts users can give.

Document Dependencies

Clearly list any environment variables, API keys, or system dependencies required.

Test Across Agents

If possible, test your skill with multiple AI agents. Note any agent-specific quirks.

Handle Errors Gracefully

Provide helpful error messages when things go wrong. Guide users to the solution.

Version Semantically

Use semantic versioning (MAJOR.MINOR.PATCH). Bump major for breaking changes.

Ready to create your first skill?

Browse existing skills for inspiration, then submit your own to share with the community.

Browse Skills Submit a Skill