Debugging PM Skills Execution and Command Routing: A Complete Guide

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 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 file that declares the plugin name, version, description, and author metadata. According to the source code in 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 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.
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), 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).

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

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

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

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:

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

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

python validate_plugins.py

Then install and invoke:

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

Claude-Code will load 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:

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 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 file or correct the skill name in the command file.

Can I run validation checks in a CI pipeline?

Yes. The 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.

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