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
short: Brief 5-8 word summary (optional)
description: When and how Claude should use this skill. Be specific about triggers and use cases.
when: Semantic activation trigger for index display (optional)
---

# Skill Title

Detailed instructions for how to apply this skill...

Required Frontmatter Fields

Optional Frontmatter Fields

Note: short and when are used for forge-index display. The description field is used by Claude Code for skill invocation.

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
short: Conventional commit message formatting
description: Apply conventional commit message format when the user is committing code or asking about commit messages. Enforces type prefixes, scope, and message structure.
when: User commits code, writes commit messages, or asks about commit conventions
---

# 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