Create Skill Skill

Create new Claude Code agent skills that Claude invokes autonomously based on task context.

Skill Structure

Each skill lives in its own folder within skills/:

skills/
└── skill-name/
    ├── SKILL.md              # Main skill definition (required)
    ├── examples/             # Example files (optional)
    │   └── example.md
    └── templates/            # Templates (optional)
        └── template.md

SKILL.md Format

---
name: skill-name
description: When and how Claude should use this skill. Be specific about triggers and use cases.
user-invocable: false
---

# Skill Title

Detailed instructions for how to apply this skill...

Required Frontmatter Fields

Field	Description	Example
name	Unique identifier (kebab-case)	python-best-practices
description	When Claude should invoke this skill	Apply Python best practices when writing or reviewing Python code. Use for type hints, docstrings, and PEP compliance.

Optional Frontmatter Fields

Field	Description	Default	Example
user-invocable	Whether users can invoke skill with /skill-name	true	false for knowledge skills, true for action skills

Writing Effective Descriptions

The description is critical - it tells Claude when to use the skill. Include:

1. Trigger conditions: When should this skill activate?
2. Use cases: What tasks benefit from this skill?
3. Scope: What does and doesn't this skill cover?

Good Description Examples

description: Apply React best practices when creating or modifying React components. Use for hooks, state management, component structure, and performance optimization.

description: Enforce security best practices when writing code that handles user input, authentication, or sensitive data. Covers input validation, SQL injection prevention, and XSS protection.

description: Generate API documentation when creating or updating REST endpoints. Produces OpenAPI-compatible documentation with examples.

Bad Description Examples

# Too vague - Claude won't know when to use it
description: Helps with Python code

# Too broad - will trigger too often
description: Use this for all coding tasks

Skill Body Content

The body should include:

1. Context: Background information Claude needs
2. Rules/Guidelines: Specific practices to follow
3. Examples: Concrete examples of correct usage
4. Anti-patterns: What to avoid
5. Output format: How to present results

Example Skill

---
name: conventional-commits
description: Apply conventional commit message format when the user is committing code or asking about commit messages. Enforces type prefixes, scope, and message structure.
user-invocable: false
---

# Conventional Commits

Format all commit messages following the Conventional Commits specification.

## Format

[optional scope]:

[optional body]

[optional footer(s)]

## Types

| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no code change |
| `refactor` | Code restructuring |
| `perf` | Performance improvement |
| `test` | Adding tests |
| `chore` | Maintenance tasks |

## Examples

### Feature

feat(auth): add OAuth2 login support

### Bug Fix

fix(api): handle null response in user endpoint

### Breaking Change

feat(api)!: change response format for /users endpoint

BREAKING CHANGE: Response now returns array instead of object

## Rules

1. Type is required and lowercase
2. Description starts lowercase, no period at end
3. Use imperative mood ("add" not "added")
4. Keep first line under 72 characters

Adding Subfolders

Skills can include reference materials:

skills/
└── api-design/
    ├── SKILL.md
    ├── examples/
    │   ├── rest-example.md
    │   └── graphql-example.md
    └── templates/
        └── openapi-template.yaml

Reference these in your SKILL.md:

See `examples/rest-example.md` for a complete REST API example.

File Location

Save skills to:

plugins/<plugin-name>/skills/<skill-name>/SKILL.md