# How Skill Dependencies Are Managed in PM Skills

> Discover how skill dependencies are managed in phuryn/pm-skills. Dependencies are declared in markdown and validated by a Python script, simplifying project management.

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

---

**Skill dependencies in the phuryn/pm-skills repository are declared directly within command markdown files using the `**skill-name** skill` pattern and enforced programmatically by the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) validation script, eliminating the need for external package managers or centralized manifest files.**

The PM Skills project organizes reusable knowledge into self-contained markdown skills that are consumed by user-facing slash-commands. Rather than using traditional dependency management tools, the project implements a lightweight, file-based dependency system where commands explicitly declare their required skills and automated validation ensures reference integrity at the plugin level.

## The Skill-Command Architecture

In this architecture, **skills** and **commands** serve distinct purposes but remain tightly coupled within plugin boundaries.

### Self-Contained Skills

Each skill resides in its own directory as a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file (for example, [`pm-toolkit/skills/review-resume/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/review-resume/SKILL.md)). These files contain the skill's front-matter and knowledge content, but crucially, they do not declare their own dependencies or depend on other skills. According to the README "How it Works" section, skills are loaded automatically when needed by commands.

### Command-Driven Dependencies

Commands are the only entities that "require" skills. A command file (located in directories like `pm-product-discovery/commands/`) declares which skills it needs by embedding specific markdown patterns. This design keeps the dependency graph simple: skills are passive knowledge blocks, while commands actively chain them together to form workflows.

## Declaring Dependencies in Command Files

Dependencies are declared using a strict markdown pattern that the validator recognizes.

### The Reference Pattern

To declare that a command depends on a specific skill, add a line following this exact format:

```markdown
**skill-name** skill

```

For example, in [`pm-product-discovery/commands/discover.md`](https://github.com/phuryn/pm-skills/blob/main/pm-product-discovery/commands/discover.md), the command declares multiple dependencies:

```markdown

# /discover – Full discovery workflow

**brainstorm-ideas-new** skill
**identify-assumptions-new** skill
**prioritize-assumptions** skill
**brainstorm-experiments-new** skill

```

Each line beginning with `**` and ending with `skill` tells the system that the `/discover` command requires those four specific skills to function.

## Automated Validation in validate_plugins.py

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script serves as the dependency enforcement layer, parsing every command file to verify that referenced skills exist within the same plugin.

### Regex Extraction Logic

At lines 289-307 of [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), the script uses regular expressions to extract skill references from command content:

```python

# validate_plugins.py – snippet handling cross‑references

refs = re.findall(r'\*\*(\w[\w-]+)\*\*\s+skill', content)
for ref in refs:
    if ref not in skill_names:
        result.warn(f"Command {cmd_file} references skill '{ref}' not found in this plugin")

```

The regex pattern `\*\*(\w[\w-]+)\*\*\s+skill` captures the skill name between the double asterisks, ignoring the literal `**` markers and trailing `skill` keyword.

### Plugin Isolation Enforcement

The validator maintains strict **plugin isolation**: it only checks for skills within the same plugin directory. If a command in `pm-toolkit/commands/` references a skill, the script verifies that the skill exists in `pm-toolkit/skills/`. This modular approach ensures that plugins remain self-contained and installable as complete units, preventing external dependencies from leaking across plugin boundaries.

## Adding New Skill Dependencies

When extending the marketplace with new capabilities, follow this workflow to ensure proper dependency linking:

1. **Create the skill**: Add a new directory under your plugin's `skills/` folder (e.g., `pm-toolkit/skills/my-new-skill/`) containing a [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file.

2. **Reference in command**: Open an existing command file or create a new one in `commands/`, then add the declaration line `**my-new-skill** skill` where the skill is needed.

3. **Validate**: Run the test suite (`make test` or execute [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py)). The script will confirm that the reference resolves correctly or raise a warning if the skill directory is missing.

## Summary

- **Skill dependencies** in PM Skills are managed through markdown declarations in command files, not package managers.
- The `**skill-name** skill` pattern in command files explicitly declares which skills a command requires.
- The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script automatically validates these references at lines 289-307 using regex extraction and warns on missing skills.
- **Plugin isolation** ensures dependencies are confined within plugin boundaries, keeping the marketplace modular.
- No external manifest files are required; the dependency graph is derived directly from the command markdown content.

## Frequently Asked Questions

### How do I declare a skill dependency in PM Skills?

Declare the dependency by adding a line in the format `**skill-name** skill` to any command markdown file. For example, `**review-resume** skill` tells the system that the command requires the `review-resume` skill. The validator will automatically check that this skill exists in your plugin's `skills/` directory.

### What happens if a command references a missing skill?

The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script will detect the missing reference during validation and call `result.warn()` with a message indicating which command file references the non-existent skill. This warning appears in CI output and prevents the build from passing until the skill is created or the reference is removed.

### Can skills depend on other skills?

No, the current architecture does not support skill-to-skill dependencies. Skills are designed as atomic, self-contained knowledge blocks stored in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files. Only commands can declare dependencies on skills, ensuring a flat dependency hierarchy that simplifies validation and maintenance.

### Is there a centralized dependency manifest file?

No centralized manifest exists. Dependencies are distributed across individual command markdown files. The [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script acts as the source of truth by scanning all command files to build the dependency graph dynamically, eliminating the need to maintain a separate configuration file and reducing the risk of drift between declared and actual dependencies.