How Skills Are Defined and Structured in the PM Skills Marketplace

Skills in the PM Skills Marketplace are defined as Markdown files with YAML front-matter containing metadata and instructions, organized hierarchically into category folders with a central manifest file for discovery.

The PM Skills Marketplace (phuryn/pm-skills) is an open-source repository that houses reusable prompt definitions for Claude-based plugins. Understanding how skills are defined and structured in the PM Skills Marketplace reveals a file-based architecture that prioritizes maintainability and automatic discovery without requiring code changes for new additions.

Hierarchical Organization of Skill Categories

The repository organizes skills into top-level category folders that group related capabilities by functional area. These include directories such as pm-toolkit, pm-product-strategy, pm-product-discovery, pm-marketing-growth, pm-market-research, pm-go-to-market, pm-execution, pm-data-analytics, and pm-ai-shipping.

Within each category, individual skills reside in dedicated sub-folders. For example, the review-resume skill lives at pm-toolkit/skills/review-resume/, while the value-proposition skill resides in pm-product-strategy/skills/value-proposition/. Each skill folder contains exactly one file named SKILL.md that encapsulates the complete skill definition.

Anatomy of a SKILL.md File

Every skill file follows a strict four-part structure that Claude interprets as a prompt template.

YAML Front-Matter Metadata

The file begins with YAML front-matter delimited by triple dashes. This section must contain at least the name and description fields. The name serves as the unique identifier, while the description explains the skill's purpose to users.

---
name: review-resume
description: "Comprehensive PM resume review and tailoring against 10 best practices..."
---

Human-Readable Title and Metadata Section

Following the front-matter, the file includes a Markdown title (e.g., # Resume Review for Product Managers) and a ## Metadata section that repeats the name, description, and optional trigger keywords. This redundancy ensures clarity for both human readers and parsing systems.

Instruction Body

The bulk of the file contains the Instructions section, which defines the role the AI should adopt, expected input arguments, output structure, and evaluation criteria. In pm-toolkit/skills/review-resume/SKILL.md, this section enumerates ten specific best-practice checks with concrete guidance for each.

Discovery via the Claude Marketplace

Skill registration relies on the /.claude-plugin/marketplace.json manifest file, which lists all available skill folders. When Claude loads the marketplace, it scans the repository for any SKILL.md file, parses the YAML front-matter to register the skill name, and uses the Markdown body as the prompt template.

The category folders serve only as logical grouping for maintainability; the runtime does not enforce this hierarchy. The manifest file bridges the folder structure and Claude's plugin system, allowing users to invoke skills as commands.

Programmatic Access to Skill Definitions

You can interact with the skill hierarchy programmatically using standard Python libraries. The repository structure enables straightforward parsing without custom dependencies.

import json, pathlib, yaml

repo_root = pathlib.Path("/path/to/phuryn/pm-skills")

def find_skill_files():
    """Yield all SKILL.md files in the repository."""
    for path in repo_root.rglob("SKILL.md"):
        yield path

def load_skill(path):
    """Parse the YAML front‑matter and return a dict."""
    text = path.read_text()
    fm, body = text.split("---", 2)[1:3]
    metadata = yaml.safe_load(fm)
    return {"path": str(path), "metadata": metadata, "body": body.strip()}

# Example: list all skills

for skill_path in find_skill_files():
    skill = load_skill(skill_path)
    print(f"{skill['metadata']['name']}: {skill['metadata']['description']}")

To retrieve the instruction text for a specific skill, such as the value-proposition generator:

skill = load_skill(repo_root / "pm-product-strategy/skills/value-proposition/SKILL.md")
print(skill["body"][:400])

Extending the Marketplace

Adding a new skill requires no code changes to the core system. Contributors create a new sub-folder under the appropriate category, add a SKILL.md file respecting the YAML and instructional conventions, and the marketplace automatically picks up the new file on the next scan. This file-based architecture decouples content management from runtime logic.

Summary

• Skills are Markdown files: Each skill is a single SKILL.md file containing YAML front-matter and Markdown instructions.
• Hierarchical organization: Nine top-level categories (e.g., pm-toolkit, pm-execution) contain skill sub-folders for logical grouping.
• Required metadata: Every skill must include name and description fields in the YAML front-matter.
• Automatic discovery: The /.claude-plugin/marketplace.json manifest and file scanning enable Claude to register skills without manual configuration.
• Zero-code extension: New skills are added by creating folders and files, not by modifying source code.

Frequently Asked Questions

What file format are skills stored in?

Skills are stored as Markdown files with YAML front-matter. Each skill resides in its own directory within a category folder and must be named exactly SKILL.md. This format allows the system to parse metadata while preserving the full prompt template as readable Markdown.

How does Claude discover available skills?

Claude discovers skills through the /.claude-plugin/marketplace.json manifest file, which catalogs all skill directories. At runtime, the system scans for SKILL.md files, extracts the YAML front-matter to register the skill name and description, and treats the Markdown body as the executable prompt template.

What metadata fields are required in a SKILL.md file?

Every SKILL.md file must include at least two fields in its YAML front-matter: name (the unique identifier) and description (a human-readable explanation). The file may also include optional trigger keywords in the Metadata section, but only name and description are mandatory for registration.

Can I organize skills into custom categories?

Yes. While the repository provides nine standard top-level categories like pm-toolkit and pm-data-analytics, you can create new category folders as needed. The runtime does not enforce the folder hierarchy, but maintaining logical categories improves discoverability for contributors and users browsing the repository.

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