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

To debug phuryn/pm-skills, verify the plugin.json manifest glob patterns match your skill files, ensure each 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 manifest that tells Claude Code which files to expose. A minimal manifest located at pm-<area>/.claude-plugin/plugin.json looks like:

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

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 files on disk.

Validate Skill Markdown Structure

Skill files must follow a strict Markdown schema defined in the repository’s README.md. Each 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 includes all required headings to ensure reliable loading.

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

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:

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

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

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

If the command references a non-existent skill, correct the reference to match an existing 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:

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:

#!/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 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 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 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 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 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 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 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 file includes the ## Output Format heading and that the command file at pm-<plugin>/commands/<command>.md correctly references the skill name.

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