skills init

Create a new skill with SKILL.md template

Usage

skills init [name]

Description

The init command creates a new skill by generating a SKILL.md file with proper frontmatter and structure. It provides a starting template that follows the Agent Skills specification.

Arguments

name · string

Optional skill name. Determines the skill directory and default skill name.

• With name: Creates <name>/SKILL.md
• Without name: Creates SKILL.md in current directory (uses current directory name as skill name)

Examples:

• skills init my-skill → Creates my-skill/SKILL.md
• skills init → Creates SKILL.md (in current directory)

Generated Template

The command generates a SKILL.md file with this structure:

---
name: skill-name
description: A brief description of what this skill does
---

# skill-name

Instructions for the agent to follow when this skill is activated.

## When to use

Describe when this skill should be used.

## Instructions

1. First step
2. Second step
3. Additional steps as needed

Template Components

Frontmatter (YAML)

The frontmatter contains metadata:

---
name: skill-name
description: A brief description of what this skill does
---

Required fields:

• name: Unique identifier (lowercase, hyphens allowed)
• description: Brief explanation of the skill’s purpose

Title

Main heading using the skill name:

# skill-name

Overview

General instructions for the agent:

Instructions for the agent to follow when this skill is activated.

When to use

Describes scenarios where the skill should be invoked:

## When to use

Describe when this skill should be used.

Instructions

Step-by-step guide for the agent:

## Instructions

1. First step
2. Second step
3. Additional steps as needed

Examples

Create in Subdirectory

# Create my-skill/SKILL.md
skills init my-skill

# Output:
# ✓ Initialized skill: my-skill
# 
# Created:
#   my-skill/SKILL.md

# Create SKILL.md in current directory
# (uses current directory name as skill name)
skills init

# Output:
# ✓ Initialized skill: current-dir-name
# 
# Created:
#   SKILL.md

Output Example

$ skills init web-scraper

███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
███████╗█████╔╝ ██║██║     ██║     ███████╗
╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
███████║██║  ██╗██║███████╗███████╗███████║
╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝

✓ Initialized skill: web-scraper

Created:
  web-scraper/SKILL.md

Next steps:
  1. Edit web-scraper/SKILL.md to define your skill instructions
  2. Update the name and description in the frontmatter

Publishing:
  GitHub:  Push to a repo, then npx skills add <owner>/<repo>
  URL:     Host the file, then npx skills add https://example.com/web-scraper/SKILL.md

Browse existing skills for inspiration at https://skills.sh/

Next Steps

After creating a skill:

1. Edit SKILL.md

   Open the generated file and customize:

   • Update name in frontmatter
   • Write a clear description
   • Add detailed instructions
   • Document when the skill should be used

   # Edit the file
   code my-skill/SKILL.md
   # or
   vim SKILL.md
   
2. Test Locally

   Install the skill locally to test:

   # From parent directory:
   skills add ./my-skill
   
   # Or if SKILL.md is in current directory:
   skills add ./
   
3. Publish (Optional)

   Share your skill:

   Option 1: GitHub

   # Push to a repo
   git add my-skill/
   git commit -m "Add web-scraper skill"
   git push
   
   # Others can install:
   # npx skills add owner/repo
   

   Option 2: Direct URL

   # Host the SKILL.md file
   # Others can install:
   # npx skills add https://example.com/my-skill/SKILL.md
   

Skill Naming Best Practices

Use Kebab Case

Name skills with lowercase and hyphens:

✅ web-scraper ✅ pr-review ✅ commit-message

❌ WebScraper ❌ pr_review ❌ commit message

Be Descriptive

Choose names that clearly indicate purpose:

✅ frontend-design-guidelines ✅ typescript-best-practices ✅ api-documentation

❌ skill1 ❌ helper ❌ utils

Keep It Concise

Prefer shorter names when possible:

✅ pr-review ✅ web-design ✅ commit-msg

⚠️ pull-request-review-and-approval ⚠️ comprehensive-web-design-guidelines

Avoid Conflicts

Check existing skills to avoid name collisions:

# Search for similar names
skills find "web design"

Advanced Frontmatter

You can extend the generated frontmatter with additional fields:

---
name: my-skill
description: Brief description
metadata:
  internal: true  # Hide from discovery
  version: "1.0.0"
  author: "Your Name"
  tags:
    - web
    - scraping
allowed-tools:
  - read
  - write
  - bash
context: fork  # Claude Code only
---

See the Skills Specification for all available fields.

File Already Exists

If SKILL.md already exists at the target path:

$ skills init my-skill

✓ Skill already exists at my-skill/SKILL.md

The command will not overwrite existing files. To reinitialize:

# Remove existing file
rm my-skill/SKILL.md

# Recreate
skills init my-skill

Repository Structure

When creating skills for a repository, follow these patterns:

Single Skill

For repositories with one skill:

my-repo/
├── SKILL.md
├── README.md
└── package.json

cd my-repo
skills init

Multiple Skills

For repositories with multiple skills:

my-repo/
├── skills/
│   ├── web-scraper/
│   │   └── SKILL.md
│   ├── pr-review/
│   │   └── SKILL.md
│   └── commit-msg/
│       └── SKILL.md
├── README.md
└── package.json

cd my-repo/skills
skills init web-scraper
skills init pr-review
skills init commit-msg

Plugin Manifest

For Claude Code plugin marketplace:

my-repo/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   └── my-plugin/
│       └── skills/
│           ├── skill1/
│           │   └── SKILL.md
│           └── skill2/
│               └── SKILL.md
└── package.json

cd my-repo/plugins/my-plugin/skills
skills init skill1
skills init skill2

Related Resources

• Skills Specification - Full specification for SKILL.md format
• Skills Directory - Browse existing skills for inspiration
• skills add - Install and test your skill
• skills find - Search for existing skills