# Debugging PM Skills Execution and Command Routing: A Complete Guide

> Debug PM Skills execution and command routing errors with `python validate_plugins.py`. Diagnose routing, missing files, and mismatches before running slash commands in Claude-Code.

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

---

**Run `python validate_plugins.py` to diagnose routing errors, missing skill files, and front-matter mismatches before executing slash commands in Claude-Code.**

The **PM Skills** repository by `phuryn` is a Claude-Code plugin marketplace containing **9 independent plugins** that encapsulate product management frameworks as executable skills. When **debugging PM Skills execution and command routing**, understanding how the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script inspects plugin manifests, skill markdown files, and command definitions is essential to resolve "command not found" and "skill not loaded" errors. This guide covers the architecture, common failure modes, and the validation workflow required to maintain healthy plugin operations.

## PM Skills Execution and Command Routing Architecture

The repository organizes functionality into self-contained plugins. Each plugin follows a strict directory structure that Claude-Code parses when resolving slash commands.

### Plugin Manifest and Metadata

Every plugin requires a [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) file that declares the plugin name, version, description, and author metadata. According to the source code in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), this manifest is validated against the parent directory name to prevent routing mismatches.

### Skills and Commands

**Skills** are defined in `*/skills/<skill-name>/SKILL.md` files. Each file contains a YAML front-matter block specifying `name` and `description`, followed by the prompt body that Claude uses to generate responses.

**Commands** are defined in `*/commands/<command-name>.md` files. These files also contain YAML front-matter (`description`, optional `argument-hint`) and a body that references skills using bold syntax (e.g., `**brainstorm-ideas** skill`) and defines execution steps.

### The Validation Engine

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script serves as the central authority for debugging. It traverses every plugin directory to validate manifests, skill front-matter, command front-matter, cross-references between commands and skills, and README sections.

## How Command Routing Works in PM Skills

Understanding the resolution path is critical for debugging execution failures.

1. **User invocation**: A slash command like `/pm-product-discovery:discover` triggers Claude-Code.
2. **File resolution**: Claude-Code maps the command to [`pm-product-discovery/commands/discover.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/commands/discover.md).
3. **Pre-execution validation**: Running `python validate_plugins.py` verifies that the command file's front-matter is correct and that referenced skills exist.
4. **Skill loading**: Claude-Code parses the command body, loads the listed skill markdowns (e.g., [`pm-product-discovery/skills/brainstorm-ideas/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/skills/brainstorm-ideas/SKILL.md)), and executes the prompts in sequence.

If any step fails—such as a missing skill file or invalid YAML front-matter—the execution halts and returns an error.

## Common Debugging Scenarios and Solutions

Most execution failures stem from five specific issues detectable by the validator.

### Command Not Found

**Symptom**: Claude-Code returns "Command not found" when invoking a slash command.

**Root cause**: The command markdown file is missing, misnamed, or lacks the `.md` extension. The slash command name must match the filename (e.g., `/discover` requires [`discover.md`](https://github.com/phuryn/pm-skills/blob/main/discover.md)).

**Diagnosis**: Run `python validate_plugins.py` and check for `ERROR: Missing README.md` or file not found errors in the command section output.

### Skill Not Loaded

**Symptom**: The command executes but returns "Skill not loaded" or fails to execute the expected prompt.

**Root cause**: The command markdown references a skill that does not exist in the plugin's `skills/` directory, or the skill filename is misspelled.

**Diagnosis**: The validator emits a specific warning: `WARN: Command discover.md references skill 'brainstorm-ideas' not found in this plugin`.

### Incomplete Prompt Execution

**Symptom**: Claude returns truncated or generic responses instead of the structured skill prompt.

**Root cause**: The skill file lacks required front-matter fields or the prompt body is empty. The `description` field is mandatory in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files.

**Diagnosis**: Look for `ERROR: Missing required frontmatter field: description` in the validator output for the specific skill path.

### Version Mismatch Warnings

**Symptom**: Warnings about plugin identity during installation or execution.

**Root cause**: The `name` field in [`.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) does not match the parent directory name.

**Diagnosis**: The validator reports `ERROR: Name mismatch: plugin.json says 'pm-product-strategy' but directory is 'pm-product-discovery'`.

### README Validation Failures

**Symptom**: Installation warnings or missing documentation errors.

**Root cause**: The plugin's [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) lacks required sections such as `overview` or `install`.

**Diagnosis**: The validator outputs notes like `NOTE: README may be missing 'install' section` during the `validate_readme` phase.

## Step-by-Step Debugging Guide

Follow this workflow to systematically eliminate execution errors.

1. Clone the repository and navigate to the root:

```bash
git clone https://github.com/phuryn/pm-skills.git
cd pm-skills

```

2. Run the validation script (requires Python ≥3.8):

```bash
python validate_plugins.py

```

3. Analyze the output. The script categorizes issues by severity:

- **✗ ERROR**: Hard failures that prevent execution (missing files, invalid JSON, broken cross-references).
- **⚠ WARN**: Issues that may cause unexpected behavior (short descriptions, missing optional fields).
- **ℹ NOTE**: Suggestions for improvement (missing README sections).

4. Fix all reported errors, then re-run the validator until zero errors remain. For example, if you see `ERROR: Missing SKILL.md` in `pm-ai-shipping/skills/quick-audit/`, create the missing file with proper YAML front-matter.

## Creating New Skills and Commands

Adding functionality requires strict adherence to the file structure to ensure proper routing. Below is a complete example adding a `quick-audit` skill to the `pm-ai-shipping` plugin.

### Create the Skill File

Create the directory `pm-ai-shipping/skills/quick-audit/` and add [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md):

```yaml
---
name: quick-audit
description: Run a fast static security audit on a codebase, returning high‑risk findings only.
---
You are a security auditor.  
Given a path to source code, list any hard‑coded secrets, insecure imports, and missing input validation.  
Return a concise table with **File**, **Issue**, **Severity**.

```

### Create the Command File

Create [`pm-ai-shipping/commands/quick-audit.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/quick-audit.md):

```yaml
---
description: Perform a quick static security audit using the quick-audit skill.
argument-hint: "<path-to-code>"
---
**quick-audit** skill

Run the skill on the supplied path and return the result.

```

### Validate and Execute

Run the validator to ensure zero errors:

```bash
python validate_plugins.py

```

Then install and invoke:

```bash
claude plugin install pm-ai-shipping@pm-skills
claude /pm-ai-shipping:quick-audit ./my-service/src

```

Claude-Code will load [`quick-audit.md`](https://github.com/phuryn/pm-skills/blob/main/quick-audit.md), resolve the `quick-audit` skill, execute the prompt, and return the audit table.

## Integrating Validation into CI/CD

For automated testing, import the validation logic directly from [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py):

```python
from validate_plugins import validate_plugin

# Validate a single plugin (e.g., pm-product-strategy)

result = validate_plugin('pm-product-strategy')

# Inspect specific sections

if not result['sections']['manifest'].ok:
    print("Manifest errors:", result['sections']['manifest'].errors)

```

This programmatic approach allows you to gate deployments on validation results, ensuring that only error-free plugins reach production.

## Summary

- **Execution flow** in PM Skills depends on command markdown files referencing skill markdown files via precise file paths and front-matter metadata.
- **Command routing** fails when file names mismatch directory names, when front-matter is malformed, or when skills are referenced but not present.
- **[`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** is the canonical debugging tool that checks manifests, cross-references, and README requirements.
- **Resolution** requires running the validator, fixing all ERROR and WARN messages, and re-validating until the output shows zero issues.
- **Integration** into CI pipelines is supported via the `validate_plugin` function import.

## Frequently Asked Questions

### Why is my slash command showing "Command not found"?

This error occurs when the command markdown file is missing or its name does not match the slash command invocation. Verify that the file exists at `*/commands/<command-name>.md` and that the filename matches the command you are typing. Run `python validate_plugins.py` to confirm the file is detected and properly formatted.

### How do I fix "Skill not loaded" errors during command execution?

Ensure the command markdown references a skill that actually exists in the plugin's `skills/` directory. The validator will flag `WARN: Command discover.md references skill 'brainstorm-ideas' not found in this plugin` if the reference is broken. Create the missing [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file or correct the skill name in the command file.

### Can I run validation checks in a CI pipeline?

Yes. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script can be imported as a module. Use `from validate_plugins import validate_plugin` to call `validate_plugin('plugin-name')` programmatically. This returns a structured result object containing error states for each validation section, allowing you to fail builds when validation does not pass.

### What Python version is required for the validator?

The validator requires **Python 3.8 or higher**. Running the script with older versions may result in syntax errors or missing standard library features used by the validation logic.