# How to Debug phuryn/pm-skills: A Complete Troubleshooting Guide

> Debug phuryn/pm-skills by checking plugin.json glob patterns, SKILL.md headings, and using CLAUDE_LOG=debug. Your complete troubleshooting guide for PM Skills.

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

---

**To debug phuryn/pm-skills, verify the [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest glob patterns match your skill files, ensure each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) contains required headings including `## Output Format`, and run commands with `CLAUDE_LOG=debug` to inspect which skills load and how inputs are processed.**

The phuryn/pm-skills repository is a Claude-compatible marketplace that bundles 9 plugins, each containing Markdown-defined skills and slash commands. When skills fail to load or commands return unexpected results, systematic debugging of the plugin manifests, skill schemas, and command references is required to identify the root cause according to the phuryn/pm-skills source code.

## Inspect Plugin Manifests

Each plugin in phuryn/pm-skills ships a [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) manifest that tells Claude Code which files to expose. A minimal manifest located at `pm-<area>/.claude-plugin/plugin.json` looks like:

```json
{
  "name": "pm-toolkit",
  "description": "Resume review, NDA drafting, privacy policy, grammar checking",
  "skills": ["skills/**/*.md"],
  "commands": ["commands/**/*.md"]
}

```

If a skill is not loading, first confirm the glob patterns actually match the existing file paths. A typo in the `skills` or `commands` array will prevent Claude from discovering the files, causing it to fall back to generic knowledge.

Run these CLI commands to verify installation:

```bash
claude plugin list
claude plugin inspect pm-toolkit

```

The inspect command prints the parsed manifest, allowing you to confirm that patterns like `skills/**/*.md` resolve to the correct [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files on disk.

## Validate Skill Markdown Structure

Skill files must follow a strict Markdown schema defined in the repository’s [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md). Each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file must contain these essential sections:

- `# <Skill name>` – The title line.

- `## Purpose` – Short description of the skill.

- `## Input Arguments` – JSON-style schema for expected inputs.

- `## Process` – Ordered execution steps.

- `## Output Format` – Specification for how the response should be structured.

For example, the resume-review skill at [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) includes all required headings to ensure reliable loading.

To quickly verify that all skills contain the required output section, run:

```bash
grep -R "## Output Format" pm-toolkit/skills/*/*.md

```

If this command returns no match for a specific skill, Claude may load the file but will not surface it reliably. Add the missing `## Output Format` heading to resolve the issue.

## Debug Command Execution with Verbose Logging

When a command runs but produces unexpected results, enable verbose logging to see the raw JSON payloads. Set the environment variable `CLAUDE_LOG=debug` before invoking the command:

```bash
export CLAUDE_LOG=debug
claude chat "/pm-toolkit:review-resume"

```

The debug output prints lines such as:

```

[debug] Loading skill: pm-toolkit/skills/review-resume/SKILL.md
[debug] Invoking skill with args: {"resume":"<base64>","job_description":"..."}
[debug] Skill response: {"introduction":"...","feedback":"..."}

```

If the log shows "Loading skill …" but the response is empty, inspect the `## Input Arguments` JSON schema in the skill file. A malformed schema can cause the skill to reject the payload silently.

## Verify Command File References

Commands are thin Markdown wrappers stored in `pm-<plugin>/commands/` that reference one or more skills. A typical command file at [`pm-toolkit/commands/review-resume.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/commands/review-resume.md) contains:

```markdown

# Review Resume

## Description

Runs the `review-resume` skill and formats the output.

## Steps

1. Load skill `review-resume`.
2. Pass user-provided resume and job description.
3. Return skill output.

```

Because commands reference skill names as strings, a typo will cause silent failures. Verify that the skill name used in the command matches the filename or identifier defined in the manifest:

```bash
grep -R "review-resume" pm-toolkit/commands

```

If the command references a non-existent skill, correct the reference to match an existing [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file.

## Automate End-to-End Testing

To verify the entire workflow without manual UI interaction, script the test using the Claude CLI. Below is a Python snippet that invokes the resume-review command and asserts the JSON response contains a `feedback` field:

```python
import os, json, subprocess, textwrap

# Ensure the plugin is installed

subprocess.run(["claude", "plugin", "install", "pm-toolkit@pm-skills"], check=True)

# Run the command and capture JSON output

cmd = [
    "claude", "chat",
    "/pm-toolkit:review-resume",
    "--json",
    "--input", json.dumps({
        "resume": "Base64-encoded-PDF",
        "job_description": "Product manager at XYZ"
    })
]
result = subprocess.run(cmd, capture_output=True, text=True)
payload = json.loads(result.stdout)

assert "feedback" in payload, "Missing feedback field – skill likely failed"
print("✅ Resume review skill returns expected structure")

```

For a lightweight bash alternative:

```bash
#!/usr/bin/env bash
set -e
claude plugin install pm-data-analytics@pm-skills
out=$(claude chat "/pm-data-analytics:write-query" --json --input '{"question":"Show top 10 users"}')
if [[ "$out" != *"SELECT"* ]]; then
  echo "❌ query generation failed"
  exit 1
fi
echo "✅ query generated"

```

## Common Debug Scenarios and Fixes

| Symptom | Likely Cause | Quick Fix |
|---------|--------------|-----------|
| Command returns "Skill not found" | The [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) glob pattern does not match the skill file path. | Verify `skills/**/*.md` patterns and ensure files live under the advertised paths like `pm-toolkit/skills/`. |
| Skill runs but output is empty | Missing or malformed `## Output Format` heading. | Add the missing heading to the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file and ensure it ends with a JSON block. |

| Errors about invalid JSON input | The `## Input Arguments` JSON schema contains syntax errors. | Run `jsonlint` on the schema to fix trailing commas or unquoted keys. |

| No debug logs appear | `CLAUDE_LOG` environment variable not exported. | Re-export `CLAUDE_LOG=debug` and restart the CLI session. |
| Skill loads slowly (>5s) | Large skill file size or heavy Markdown parsing. | Break the skill into multiple smaller files; keep each [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) under 200 KB. |

## Summary

- Verify that `pm-<plugin>/.claude-plugin/plugin.json` contains correct glob patterns matching your skill and command files.
- Ensure every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) includes mandatory headings: `## Purpose`, `## Input Arguments`, and `## Output Format`.

- Use `CLAUDE_LOG=debug` to trace skill loading and inspect raw JSON payloads during command execution.
- Check that command files reference existing skill names to avoid silent failures.
- Automate testing with Python or bash scripts to catch runtime errors without manual UI interaction.

## Frequently Asked Questions

### Why is my skill not loading in phuryn/pm-skills?

The most common cause is a mismatch between the glob patterns in [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json) and the actual file paths. Verify that the `skills` array in `pm-<area>/.claude-plugin/plugin.json` uses patterns like `skills/**/*.md` that actually match your [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) locations. Run `claude plugin inspect <plugin-name>` to confirm which files Claude detects.

### How do I enable debug logging for Claude Code plugins?

Set the environment variable `CLAUDE_LOG=debug` before starting the CLI or running a command. This outputs detailed logs showing which skills are loaded, the exact JSON payloads sent to skills, and the raw responses returned, allowing you to trace execution through [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md) or any other skill file.

### What is the required structure for a SKILL.md file?

According to the phuryn/pm-skills source code, each skill must contain: a title heading `# <Skill name>`, `## Purpose`, `## Input Arguments` with a JSON schema, `## Process` with ordered steps, and `## Output Format` defining the response structure. Missing any of these headings causes unreliable behavior in Claude Code.

### Why does my command return empty output?

Empty output typically indicates the skill executed but the `## Output Format` section is missing or malformed, causing Claude to return no content. Verify that your [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file includes the `## Output Format` heading and that the command file at `pm-<plugin>/commands/<command>.md` correctly references the skill name.