# How to Create a Custom Skill for Claude Code Using SKILL.md

> Learn to create custom skills for Claude Code using SKILL.md. Follow our guide to define your skill name and description in YAML, then validate its compliance.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-06-24

---

**To create a custom skill for Claude Code, create a folder under `pm-{plugin}/skills/` containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with YAML front-matter defining `name` (matching the folder) and `description`, then run the validator to ensure compliance.**

The `phuryn/pm-skills` repository provides a structured framework for extending Claude Code with custom skills through declarative [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files. This approach allows you to define reusable capabilities without modifying core plugin manifests or writing complex configuration code. Understanding how to create a custom skill for Claude Code using [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) requires following specific architectural conventions defined in the repository's central documentation.

## Understanding the Skill Architecture

Claude Code discovers skills automatically by scanning [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files located within each plugin's `skills/` directory. Unlike traditional plugin development that requires manifest entries, this system uses filesystem conventions and front-matter validation to register new capabilities.

### Plugin Layout Requirements

Every plugin in the repository follows the `pm-{name}` naming convention and contains a dedicated `skills/` subtree. According to [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) lines 13-30, the repository expects this structure:

```text
pm-myplugin/
└─ skills/
   └─ my-custom-skill/
      └─ SKILL.md

```

The `pm-{plugin}/.claude-plugin/plugin.json` file defines the plugin itself, but **you do not modify this manifest when adding individual skills**. Skills exist as independent building blocks within the skills subdirectory.

### The SKILL.md File Structure

A valid skill requires exactly one [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file per skill folder. As defined in [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) lines 53-55, this file must contain:
- YAML front-matter with `name` and `description` fields
- Free-form markdown content containing instructions, arguments, and examples

## Step-by-Step Implementation Guide

Follow these steps to implement a new skill that Claude Code can discover and load automatically.

### Step 1: Create the Directory Structure

Create a new folder under your plugin's `skills/` directory. The folder name must match the skill identifier you intend to use:

```bash
mkdir -p pm-myplugin/skills/my-custom-skill

```

### Step 2: Write the SKILL.md Front-Matter

Create [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) with required YAML front-matter. The `name` field must exactly match the parent folder name, as enforced by the validator (see [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) line 54):

```yaml
---
name: my-custom-skill
description: "Brief one-liner that Claude uses to match trigger phrases and auto-load contexts."
---

```

The `description` field appears in Claude's skill list and drives auto-loading based on trigger phrases (see [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) line 46).

### Step 3: Add Skill Instructions

After the front-matter, add the instruction body that defines the skill's behavior:

```markdown

# My Custom Skill

You are a specialist in analyzing project management workflows.

## Input Arguments

- `$PROJECT_PATH`: Path to the project directory (required)
- `$FOCUS_AREA`: Specific aspect to analyze (optional)

## Output

Provide a structured analysis with:
1. Current workflow bottlenecks
2. Recommended optimizations
3. Implementation priority

### Example Usage

/my-custom-skill $PROJECT_PATH="./src" $FOCUS_AREA="code-review"

```

Reference the `review-resume` skill in [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) for a fully fleshed-out implementation example.

### Step 4: Validate Your Skill

Run the repository-wide validator to check naming constraints and schema compliance:

```bash
python3 validate_plugins.py

```

As documented in [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) lines 95-99, this script verifies that the front-matter `name` matches the folder name and validates other structural requirements. If you encounter a "Skill name does not match folder name" error, align the folder name with the `name` field in the YAML front-matter.

## SKILL.md Front-Matter Constraints

The front-matter section follows strict validation rules. According to the source code analysis of [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md):

- **The `name` field is required** and must equal the directory name exactly
- **The `description` field is required** and provides the auto-loading trigger context
- **No additional manifest entries are needed** — skills do not appear in [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json)

These constraints ensure that Claude Code can scan `pm-*/skills/` directories at runtime and correctly map trigger phrases to skill descriptions (see [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) lines 46-56).

## Validation and Troubleshooting

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script serves as the gatekeeper for skill integrity. It checks:

- Folder-to-name consistency
- Required front-matter fields
- File structure compliance

If validation fails, the error message indicates exactly which constraint was violated. Common issues include mismatched folder names or missing `description` fields. The validator ensures that only properly structured skills are available for Claude Code's discovery mechanism.

## Summary

- **Create a folder** under `pm-{plugin}/skills/` named after your skill
- **Write [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)** with YAML front-matter containing `name` (matching folder) and `description`
- **Add instruction content** in markdown format below the front-matter
- **Do not modify** [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) — skills auto-discover based on filesystem structure
- **Run `python3 validate_plugins.py`** to enforce naming and schema constraints
- **Reference [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md)** for architectural rules and validation requirements

## Frequently Asked Questions

### What happens if the skill name doesn't match the folder name?

The validator will reject the skill with a "Skill name does not match folder name" error. You must rename either the folder or the `name` field in the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) front-matter until they align exactly, as required by [`CLAUDE.md`](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) line 54.

### Do I need to update plugin.json when adding a new skill?

No. Skills exist independently of the plugin manifest. The [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) file (located at `pm-{plugin}/.claude-plugin/plugin.json`) defines the plugin itself, but individual skills are discovered automatically by scanning [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files in the `skills/` directory.

### How does Claude Code know when to load my custom skill?

Claude Code scans every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) under `pm-*/skills/` when the plugin loads. The `description` field in your front-matter is used for auto-loading based on trigger phrases, allowing Claude to match user queries to available skills without explicit commands.

### Can I include optional arguments in my skill definition?

Yes. You can define optional input arguments using the `$ARGUMENT_NAME` syntax in your skill instructions. Mark them as optional in the documentation section, and Claude will handle cases where users omit these parameters during invocation.