# How to Debug a Skill in the pm‑skills Repository: A Complete Validation Guide

> Debug skills in the pm-skills repository efficiently. Use the validate_plugins.py script to catch frontmatter errors, naming mismatches, and cross-reference issues before running your skills.

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

---

**The best way to debug a skill in pm‑skills is to run the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) validator to catch frontmatter errors, naming mismatches, and cross‑reference issues before execution.**

A skill in the **pm‑skills** repository is a self‑contained markdown file that defines a prompt template, input arguments, and response structure for Claude’s plugin engine. Because these skills rely on strict YAML frontmatter and naming conventions, you should debug a skill using static analysis rather than trial‑and‑error execution. The repository provides a dedicated validator that checks every structural requirement against the agentskills.io specification.

## Understanding the Skill Structure

Each skill resides in its own directory (e.g., `pm‑toolkit/skills/review‑resume/`) and contains a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file with three critical components:

- **YAML Frontmatter**: Metadata between `---` markers including `name`, `version`, and `description`
- **Input Arguments**: Variables like `$RESUME` or `$JOB_POSTING` that the command must supply
- **Response Structure**: The expected output format that downstream commands consume

The validator treats this frontmatter as the single source of truth. Any typo or missing field in the YAML will cause the plugin engine to ignore the skill entirely, so you must verify this structure first.

## Step‑by‑Step Workflow to Debug a Skill

### 1. Run the Central Validator

Start every debugging session by executing [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) from the repository root. This script parses every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md), checks manifest integrity, and validates associated command files.

```bash

# Validate the entire collection

python validate_plugins.py .

# Validate a specific plugin directory

python validate_plugins.py pm-toolkit

```

According to the source code in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), the validator enforces the complete agentskills.io specification and exits with code **0** only when all critical checks pass (see lines 61‑63).

### 2. Fix YAML Frontmatter Errors

The validator’s `parse_yaml_frontmatter` routine (lines 62‑81) extracts key‑value pairs from the initial `---` delimiters. Common failures include:

- **Missing required fields**: `name`, `version`, or `description`
- **Malformed YAML**: Syntax errors that prevent parsing

If you see errors like “Missing required frontmatter field: name”, open the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) and verify that all required keys exist between the first set of `---` markers.

### 3. Verify Naming Consistency

The `validate_skill` function (lines 36‑40) checks that the `name` field in the frontmatter matches the directory name exactly. A mismatch triggers the error: “Name mismatch: frontmatter says … but directory is …”.

**Fix**: Rename the directory or update the `name:` value in the YAML so they align. The agentskills.io spec requires this match so that commands can reference the skill correctly.

### 4. Check Description Quality

Lines 111‑119 of the validator warn if the `description` is shorter than 30 characters or lacks trigger phrases like “trigger” or “use when”. While these appear as warnings (not errors), they indicate discovery issues that make the skill hard to invoke.

**Fix**: Expand the description to explain when a user should activate the skill, including specific trigger keywords.

### 5. Validate Cross‑References

Commands and skills must reference each other with exact names. The `validate_cross_references` function (lines 89‑109) scans command markdown files for the pattern `**skill-name** skill` and reports missing targets.

**Fix**: If the validator reports “Command references non‑existent skill”, open the command file (e.g., `pm‑toolkit/commands/review‑resume.md`) and verify the skill name matches the directory name exactly.

### 6. Confirm README Documentation

The `validate_readme` function (lines 43‑45) checks that [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) contains the required sections: **overview**, **install**, **skill**, and **command**. Missing sections indicate incomplete documentation that may hide usage problems.

**Fix**: Add the missing headers to your plugin’s README to ensure users can install and invoke the skill correctly.

### 7. Inspect the Skill File Manually

After clearing validator errors, open the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) (e.g., `pm‑toolkit/skills/review‑resume/SKILL.md`) and verify:

- **Input Arguments**: All variables listed in the “Input Arguments” section (e.g., `$RESUME`, `$JOB_POSTING`) must match what the command file provides
- **Response Structure**: The documented output must align with what the consuming command expects

Inconsistent argument names cause the plugin engine to pass `null` values, leading to silent runtime failures that the validator cannot catch.

### 8. Test via Command Execution

Run the associated command markdown (e.g., `pm‑toolkit/commands/review‑resume.md`) using the Claude CLI or UI. Observe the output:

- If the response is empty or malformed, re‑run the validator to check for new warnings
- If arguments are null, return to step 7 and verify variable name alignment between the command and skill files

## Interpreting Validator Output

The validator produces structured output showing errors, warnings, and informational notes. A clean skill shows:

```

┌─ pm-toolkit  [12 skills, 10 commands]  ✓ PASS

```

Typical errors appear as:

```

  Skills with issues:
    review-resume:
      ⚠ WARN: Description is very short (28 chars)
  Commands with issues:
    review-resume.md:
      ✗ ERROR: Missing required frontmatter field: description

```

Address all **ERROR** levels before testing execution. The script returns a non‑zero exit code if any errors remain, making it suitable for CI/CD pipelines.

## Summary

- **Run [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)** first to debug a skill; it catches structural issues before runtime.
- **Frontmatter is authoritative**: The `name` field must match the directory name, and all required YAML keys must be present.
- **Check `parse_yaml_frontmatter`** (lines 62‑81) when resolving malformed YAML errors.
- **Validate cross‑references** to ensure commands point to existing skills using the `**skill-name** skill` pattern.
- **Confirm README sections** (overview, install, skill, command) to prevent documentation gaps.
- **Verify input variable names** manually between command and skill files to avoid `null` value injection.

## Frequently Asked Questions

### What is the fastest way to debug a skill in pm-skills?

Execute `python validate_plugins.py <plugin-dir>` from the repository root. This static analysis runs in seconds and reports frontmatter errors, naming mismatches, and missing cross‑references before you ever load the skill in Claude. Fix all **ERROR** level messages before proceeding to manual testing.

### Why does my skill return null values when executed?

Null values occur when the command file passes variables that do not match the skill’s “Input Arguments” section. Open the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) (e.g., [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md)) and verify that the variable names (like `$RESUME`) exactly match those referenced in the command markdown. The validator checks file structure but cannot validate runtime argument alignment.

### How do I fix "Name mismatch" errors in the validator?

The `validate_skill` logic (lines 36‑40) compares the directory name against the `name` field in the YAML frontmatter. To resolve the error, rename the directory to match the frontmatter value, or edit the `name:` field in the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file to match the directory. The agentskills.io specification requires exact alignment for the plugin engine to locate the skill.

### What README sections are required for a valid pm-skills plugin?

The `validate_readme` function (lines 43‑45) requires four specific sections in [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md): **overview**, **install**, **skill**, and **command**. Missing any of these will trigger a validation warning. These sections ensure users understand how to install the plugin and invoke its capabilities.