# How Skills Are Defined and Structured in the PM Skills Marketplace

> Discover how skills are defined and structured in the PM Skills Marketplace. Learn about Markdown files YAML front-matter category folders and manifest files for organized skill discovery.

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

---

**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`](https://github.com/phuryn/pm-skills/blob/main/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.

```yaml
---
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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main//.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`](https://github.com/phuryn/pm-skills/blob/main/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.

```python
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:

```python
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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main//.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main//.claude-plugin/marketplace.json) manifest file, which catalogs all skill directories. At runtime, the system scans for [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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.