Create a skill

Step 1: Create the directory

mkdir my-skill && cd my-skill

Step 2: Write SKILL.md

Every skill starts with a SKILL.md file. This is what the agent reads to understand your skill.

# My Skill Name

One-line description of what this skill does.

## Description

A longer explanation if needed. Include context about
when this skill is useful and any prerequisites.

## When to use

- Trigger condition 1
- Trigger condition 2

## Usage

\`\`\`bash
./run.sh <argument>
\`\`\`

## Examples

\`\`\`bash
# Example: do the thing
./run.sh "hello world"
# Output: Hello, World!
\`\`\`

## Notes

Any caveats, limitations, or important details.

Writing good descriptions

The description is the most important part. It’s how the agent decides whether to use your skill. Be specific:

# ❌ Vague
Search the internet for information.

# ✅ Specific
Search Hacker News for recent posts matching a query.
Returns top 5 results with title, score, and URL.

Step 3: Add a script (optional)

If your skill needs to run code, add an executable:

#!/bin/bash
# run.sh — Search Hacker News
QUERY="${1:?Usage: run.sh <query>}"
curl -s "https://hn.algolia.com/api/v1/search?query=${QUERY}&hitsPerPage=5" \
  | jq -r '.hits[] | "[\(.points)] \(.title)\n  \(.url)\n"'

chmod +x run.sh

Any language works. Use whatever makes sense:

#!/usr/bin/env python3
# run.py
import sys
print(f"Hello, {sys.argv[1]}!")

Step 4: Test locally

# Just run it
./run.sh "test query"

That’s the whole debugging experience. No inspector needed. No protocol trace to parse.

Step 5: Install it

skills add ./my-skill

The skill is now available to any SCP-compatible agent on your system.

Directory structure reference

my-skill/
  SKILL.md          # Required: description + usage
  run.sh            # Optional: main executable
  config.json       # Optional: structured metadata
  lib/              # Optional: supporting code
  templates/        # Optional: template files
  examples/         # Optional: usage examples
  README.md         # Optional: human docs (not read by agent)

The only required file is SKILL.md. Everything else is optional and depends on what your skill needs to do.

Get Started

Core Concepts

Build

Registry

Community

Step 1: Create the directory

Step 2: Write SKILL.md

Writing good descriptions

Step 3: Add a script (optional)

Step 4: Test locally

Step 5: Install it

Directory structure reference

​Step 1: Create the directory

​Step 2: Write SKILL.md

​Writing good descriptions

​Step 3: Add a script (optional)

​Step 4: Test locally

​Step 5: Install it

​Directory structure reference

Step 1: Create the directory

Step 2: Write SKILL.md

Writing good descriptions

Step 3: Add a script (optional)

Step 4: Test locally

Step 5: Install it

Directory structure reference