# How to Update or Modify an Existing Skill in the pm-skills Repository

> Learn to update or modify an existing skill in the phuryn/pm-skills repository. Edit SKILL.md and run validate_plugins.py to ensure compliance before committing changes.

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

---

**To update an existing skill in the pm-skills repository, edit the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file in the skill's directory while ensuring the folder name matches the `name` field in the front-matter, then run the [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) script to verify compliance before committing.**

The pm-skills repository organizes AI capabilities as self-contained markdown documents within plugin directories. When you need to update or modify an existing skill, you must edit the specific [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file while adhering to validation rules enforced by the repository's built-in validator.

## Where Skills Are Defined

Each skill in the pm-skills repository follows a strict directory structure that separates plugins from their capabilities.

- Every plugin (e.g., **pm-toolkit**, **pm-product-strategy**) contains a `skills/` subdirectory.
- Inside `skills/`, each skill has its own folder named identically to the skill's `name` field in front-matter.
- The canonical definition lives in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) within that folder.

For example, the *privacy-policy* skill resides at [`pm-toolkit/skills/privacy-policy/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-toolkit/skills/privacy-policy/SKILL.md). This path is the single source of truth for that skill's behavior.

## Validation Rules Enforced by validate_plugins.py

The repository includes [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) to maintain structural integrity. Any modification must satisfy these constraints:

### Directory and Front-Matter Naming

The `validate_skill` function checks that the front-matter `name` field matches the directory name exactly. According to lines 206-208 in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py), the validator asserts `fm["name"] == skill_dir`. A mismatch causes an immediate validation error.

### Required Fields and Sections

The validator expects specific front-matter keys defined in `EXPECTED_README_SECTIONS` (lines 36-44). Every [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) must include:

- `name`: The skill identifier (must match folder name)
- `description`: Human-readable purpose

Additionally, the file must contain standard markdown sections such as **Purpose**, **Input Arguments**, **Process**, and **Output Format**.

### File Presence and Cross-References

The validator aborts with an error if [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) is missing (lines 188-192). It also scans command files for cross-references using the pattern `**skill-name** skill` (lines 304-307), flagging any broken links between commands and skills.

## Step-by-Step Update Process

Follow these steps to safely modify an existing skill:

1. **Locate the skill file** at `*/skills/<skill-name>/SKILL.md`.

2. **Open the file** in your preferred editor to modify descriptions, arguments, or templates.

3. **Synchronize front-matter** by ensuring the `name:` field matches the folder name (e.g., `name: privacy-policy` for the `privacy-policy/` folder).

4. **Update content**:
   - Revise the `description:` field if the purpose changes.
   - Modify **Input Arguments** to add or remove variables like `$PRODUCT_NAME` or `$DATA_RETENTION`.
   - Adjust the **Process** section to change how the AI constructs output.

5. **Preserve required sections** to ensure the validator recognizes the file structure.

6. **Run local validation** by executing `python validate_plugins.py` from the repository root.

7. **Commit and submit** a pull request after confirming "✅ All good" output.

## Practical Code Examples

### Editing a Skill Definition

Navigate to the skill directory and edit the file:

```bash
cd pm-toolkit/skills/privacy-policy
vim SKILL.md

```

Update the front-matter to refine the description:

```yaml
---
name: privacy-policy
description: "Generate a privacy policy covering GDPR, CCPA, and jurisdiction-specific clauses."
---

```

Add new input arguments in the markdown body:

```markdown

## Input Arguments

- `$PRODUCT_NAME`: Name of the product or service
- `$COMPANY_NAME`: Legal name of your company
- `$DATA_RETENTION`: Retention period (new)

```

### Running the Validator

Execute the validation script from the repository root:

```bash
python validate_plugins.py

```

If the folder name and front-matter disagree, you will see:

```

Error: Name mismatch: frontmatter says 'privacy-policy' but directory is 'privacy'

```

Successful validation outputs "✅ All good", confirming your changes are safe to commit.

## Summary

- Skills are defined in `*/skills/<skill-name>/SKILL.md` files within plugin directories.
- The `name` field in front-matter must exactly match the parent folder name to pass validation in [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py).
- Required sections include `name`, `description`, Purpose, Input Arguments, Process, and Output Format.
- Always run `python validate_plugins.py` before committing to catch naming mismatches or missing files.
- Cross-references in command files must be updated manually if you change a skill's name.

## Frequently Asked Questions

### What happens if the front-matter name doesn't match the folder name?

The validator will report an error and fail. According to [`validate_plugins.py`](https://github.com/phuryn/pm-skills/blob/main/validate_plugins.py) lines 206-208, the `validate_skill` function explicitly checks `fm["name"] == skill_dir`, and any mismatch prevents the validation from passing.

### Can I add new variables to an existing skill's input arguments?

Yes. Simply edit the **Input Arguments** section in the [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) file to add new placeholders like `$NEW_VARIABLE`. The skill template will automatically incorporate these variables into the AI prompt generation.

### How do I verify my changes won't break the repository?

Run `python validate_plugins.py` from the repository root. This script checks for missing [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) files, front-matter inconsistencies, and broken cross-references between commands and skills, ensuring the repository remains in a healthy state.

### Do I need to update any other files when modifying a skill?

You only need to update other files if you change the skill's name. If you rename a skill, you must update the corresponding folder name, any command files in `*/commands/` that reference the skill using the `**skill-name** skill` pattern, and potentially the root [`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md) if the skill is listed there.