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

A skill in the PM Skills Marketplace is a self-contained unit requiring exactly one file—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 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:

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 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. This skill demonstrates the canonical layout in practice:

• Folder: pm-toolkit/skills/review-resume/
• File: 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 with the following template:

---
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 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.
• 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.

Frequently Asked Questions

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

Only one file is strictly required: 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}