Skip to main content

​
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

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
Main heading using the skill name:
# skill-name
General instructions for the agent:
Instructions for the agent to follow when this skill is activated.
Describes scenarios where the skill should be invoked:
## When to use

Describe when this skill should be used.
Step-by-step guide for the agent:
## Instructions

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

​
Examples

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

# Output:
# ✓ Initialized skill: my-skill
# 
# Created:
#   my-skill/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:
For repositories with one skill:
my-repo/
├── SKILL.md
├── README.md
└── package.json

cd my-repo
skills init

Build docs developers (and LLMs) love

Get started for freeTalk to us