How to List Available Skills in the pm-skills Repository

You can list available skills in the pm-skills repository by reading the README file, executing the 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 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 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, which programmatically walks every skills/* folder, loads each 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:

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:

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:

python validate_plugins.py

The script prints the total number of skills per plugin after checking that each SKILL.md contains the required front-matter fields.

Key Files in the Repository

Understanding these files helps when building custom listing tools:

• README.md: Contains the human-readable catalogue of plugins and skills.
• 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 or 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 for validated inventory, or writing a custom script using pathlib and yaml.
• The 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 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 script walks the repository structure, loads each 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 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.

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