# How to List Available Skills in the pm-skills Repository

> Discover how to list available skills in the phuryn/pm-skills repository. Explore methods like checking the README, running validate_plugins.py, or creating a custom file walker.

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

---

**You can list available skills in the pm-skills repository by reading the README file, executing the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script, or writing a custom file walker that scans the `<plugin>/skills/<skill>/SKILL.md` pattern.**

The **pm-skills** repository organizes product management capabilities as a collection of plugins, where each plugin resides in its own top-level folder and contains a `skills/` directory with individual skill definitions. Because the catalogue is entirely file-based, you can programmatically discover every available skill by traversing the consistent folder structure. This guide covers three methods to generate a complete inventory of skills, from quick manual checks to automated Python solutions.

## How the pm-skills Repository Is Organized

The repository follows a strict **plugin-based architecture**. Each plugin (such as `pm-toolkit`, `pm-product-discovery`, or `pm-marketing-growth`) functions as a standalone module containing a `skills/` subdirectory.

Inside each `skills/` folder, individual skills exist as sub-folders containing a single [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file. This markdown file includes YAML front-matter defining the skill's `name`, `description`, and other metadata required by AI assistants like Claude, OpenCode, and Gemini.

The universal path pattern is:

```

<plugin-name>/skills/<skill-name>/SKILL.md

```

## Three Methods to List Available Skills

Depending on your workflow, you can use one of three approaches to enumerate the available skills.

### Read the README for a Quick Overview

The [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) file at the repository root contains a human-readable catalogue organized by plugin. The "Available Plugins" section enumerates every skill per plugin, making it ideal for documentation or onboarding when you need a high-level summary without writing code.

### Run the Validation Script

The repository includes [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), which programmatically walks every `skills/*` folder, loads each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md), validates the front-matter, and reports skill counts. This method provides a trustworthy inventory while simultaneously verifying the integrity of the skill definitions.

### Write a Custom Python Script

For automation pipelines or custom filtering, you can write a small script using Python's `pathlib` module to discover skills and extract their display names from the YAML front-matter. This approach offers full customization, such as outputting JSON or filtering by specific plugins.

## Code Examples for Listing Skills

Below are practical implementations for each method.

### Python Script with Pathlib and YAML

This script walks the repository structure and prints each skill's relative path and display name extracted from the `name:` front-matter field:

```python
import pathlib
import re
import yaml

repo_root = pathlib.Path(__file__).parent  # adjust if run from elsewhere

skill_pattern = repo_root.glob('pm-*/skills/*/SKILL.md')

def read_skill_name(path: pathlib.Path) -> str:
    # The first YAML front-matter block is between --- lines

    text = path.read_text(encoding='utf-8')
    m = re.search(r'^---\n(.*?)\n---', text, re.DOTALL)
    if m:
        fm = yaml.safe_load(m.group(1))
        return fm.get('name', path.parent.name)
    return path.parent.name

for sk_path in skill_pattern:
    print(f'{sk_path.parent.relative_to(repo_root)} – {read_skill_name(sk_path)}')

```

Running this from the repository root outputs lines such as:

```

pm-product-discovery/skills/brainstorm-ideas-existing – brainstorm-ideas-existing
pm-product-strategy/skills/value-proposition – value-proposition
pm-marketing-growth/skills/north-star-metric – north-star-metric

```

### Bash One-Liner

For Unix-like environments, use this command to list all skill directory paths:

```bash
find . -path "*/skills/*/SKILL.md" -printf '%P\n' | sed 's|/SKILL.md||'

```

This returns relative paths like `pm-product-discovery/skills/brainstorm-ideas-existing`.

### Using the Built-In Validator

Execute the validation script to see a summary count and validation status:

```bash
python validate_plugins.py

```

The script prints the total number of skills per plugin after checking that each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) contains the required front-matter fields.

## Key Files in the Repository

Understanding these files helps when building custom listing tools:

- **[`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md)**: Contains the human-readable catalogue of plugins and skills.
- **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)**: Validates the repository structure and reports skill counts.
- **`pm-*/skills/*/SKILL.md`**: Individual skill definitions (e.g., [`pm-product-discovery/skills/brainstorm-ideas-existing/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/skills/brainstorm-ideas-existing/SKILL.md) or [`pm-toolkit/skills/grammar-check/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/grammar-check/SKILL.md)).

## Summary

- **The pm-skills repository uses a file-based plugin structure** where each skill lives at `<plugin>/skills/<skill-name>/SKILL.md`.
- **Three methods exist to list available skills**: reading the README for manual review, running [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) for validated inventory, or writing a custom script using `pathlib` and `yaml`.
- **The [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files contain YAML front-matter** with the display name, making it possible to extract human-readable titles programmatically.
- **All approaches rely on the same glob pattern**: `pm-*/skills/*/SKILL.md`.

## Frequently Asked Questions

### Where are skill definitions stored in the pm-skills repository?

Skill definitions are stored in individual [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files located within plugin subdirectories following the pattern `<plugin-name>/skills/<skill-name>/SKILL.md`. Each skill resides in its own folder within a plugin's `skills/` directory.

### What information does the validate_plugins.py script provide?

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script walks the repository structure, loads each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file, validates the YAML front-matter for required fields, and prints a summary count of skills per plugin. It serves as both a validator and an inventory tool.

### Can I filter skills by specific plugins when listing them?

Yes. When writing a custom script, you can modify the glob pattern or add conditional logic to filter by plugin name. For example, use `repo_root.glob('pm-product-discovery/skills/*/SKILL.md')` to list only skills from the product discovery plugin.

### What metadata is available in each SKILL.md file?

Each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file contains YAML front-matter with fields such as `name`, `description`, and other AI assistant configuration parameters. The `name` field provides the human-readable display title for the skill.