# File Structure for a Skill in the PM Skills Marketplace: The SKILL.md Standard

> Learn the standard SKILL.md file structure for the PM Skills Marketplace. Discover how to organize your skills efficiently in the phuryn/pm-skills repository.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: api-reference
- Published: 2026-06-21

---

**A skill in the PM Skills Marketplace is a self-contained unit requiring exactly one file—[`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md)—placed inside a directory matching the skill's `name` frontmatter field within a plugin's `skills/` folder.**

The `phuryn/pm-skills` repository defines a strict contract for how AI agents discover and load capabilities. Understanding the canonical file structure for a skill ensures your plugin integrates correctly with the Claude ecosystem and maintains compatibility with the marketplace manifest system.

## Canonical Directory Layout for a PM Skill

According to the repository's [CLAUDE.md](https://github.com/phuryn/pm-skills/blob/main/CLAUDE.md) specification (see lines 25-30), the PM Skills Marketplace organizes plugins and skills hierarchically. Each skill lives as an isolated directory inside its parent plugin:

```text
pm-skills/
├── .claude-plugin/
│   └── marketplace.json                # Marketplace manifest listing all plugins

├── pm-{plugin-name}/                    # One folder per plugin (9 total)

│   ├── .claude-plugin/
│   │   └── plugin.json                 # Per-plugin manifest

│   ├── skills/
│   │   └── {skill-name}/               # **One folder per skill**

│   │       └── SKILL.md                # Skill definition (frontmatter + body)

│   ├── commands/
│   │   └── {command}.md                # Optional commands that invoke skills

│   └── README.md                       # Plugin-level documentation

└── ... (root files such as README, LICENSE)

```

The path `pm-{plugin-name}/skills/{skill-name}/SKILL.md` represents the only mandatory file. The repository contains nine plugin folders following this pattern, each potentially housing multiple skill subdirectories.

## Inside SKILL.md: Frontmatter and Body Structure

The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file follows a strict two-part architecture: a YAML frontmatter block followed by markdown content. Unlike command files, skills contain **no placeholders**—they read all required context directly from the conversation.

### Required Frontmatter Fields

The frontmatter block (delimited by triple dashes `---`) must contain exactly two metadata fields:

- **`name`**: Must match the parent directory name exactly (`{skill-name}`)
- **`description`**: A one-sentence summary displayed in skill lists and marketplace UIs

### Body Content Standards

Everything below the closing `---` comprises the skill logic readable by AI agents. The CLAUDE.md specification recommends including:

- **Purpose**: Clear explanation of when to invoke the skill
- **Input Arguments**: Reserved for command-mediated invocations; standard skills normally declare none
- **Response Structure**: Detailed specification of expected output format

## Real-World Example: review-resume

The repository provides a concrete implementation at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md). This skill demonstrates the canonical layout in practice:

- **Folder**: `pm-toolkit/skills/review-resume/`
- **File**: [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) containing frontmatter with `name: review-resume` and detailed markdown instructions for resume analysis

As implemented in `phuryn/pm-skills`, this example verifies that the directory name (`review-resume`) matches the frontmatter `name` field exactly, satisfying the marketplace's validation requirements.

## Plugin Context and Optional Components

While skills are self-contained, they operate within a broader plugin context. The file `pm-{plugin-name}/.claude-plugin/plugin.json` serves as the per-plugin manifest that lists available skills and commands. Additionally, developers may include optional `commands/{command}.md` files that invoke skills indirectly, though these remain separate from the skill definition itself.

## Creating a New Skill: Minimal Template

To create a compliant skill, establish the directory `pm-{plugin-name}/skills/{your-skill}/` and populate [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) with the following template:

```markdown
---
name: my-skill
description: One-sentence summary shown in skill lists
---

# My Skill Title

## Purpose

Explain what the skill does and when to use it.

## Input Arguments

(Only needed for commands; skills normally have none.)

## Response Structure

Describe the expected output format for the AI agent.

```

Ensure the directory name matches the `name` field exactly to prevent loading errors.

## Summary

- **Single File Requirement**: A skill requires only [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) inside its named directory—no additional configuration files or code blobs.
- **Strict Naming**: The directory name must identical to the `name` frontmatter field within [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md).
- **Lean Frontmatter**: Only `name` and `description` fields are permitted in the YAML header; all logic resides in the markdown body.
- **No Placeholders**: Skills read conversation context directly rather than using templated variables or placeholders.
- **Plugin Boundary**: Skills live under `pm-{plugin-name}/skills/`, with plugin metadata defined separately in [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json).

## Frequently Asked Questions

### What files are required to create a skill in the PM Skills Marketplace?

Only one file is strictly required: [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) placed inside a directory named after the skill. According to the CLAUDE.md specification, this file must contain YAML frontmatter with `name` and `description` fields followed by the skill's markdown body. No [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) modifications or separate configuration files are needed at the skill level.

### Does the skill directory name matter?

Yes, the directory name must exactly match the `name` field in the SKILL.md frontmatter. The PM Skills Marketplace uses this convention for auto-discovery and validation. For example, the skill at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) declares `name: review-resume` in its frontmatter.

### Can a skill have multiple markdown files or subdirectories?

No. The specification defines a skill as a single-file unit. While the parent plugin may contain `commands/` subdirectories with additional markdown files, the skill itself is self-contained within its single [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. The repository structure enforces this simplicity to ensure agents can load skill definitions atomically.

### What is the difference between skills and commands in the file structure?

Skills reside in `skills/{skill-name}/SKILL.md` and represent capabilities the AI can invoke directly based on conversation context. Commands reside in `commands/{command}.md` and provide explicit invocation triggers that may reference one or more skills. Skills have no placeholders and read context from conversation, while commands may define specific argument structures.