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

To update an existing skill in the pm-skills repository, edit the 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 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 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 within that folder.

For example, the privacy-policy skill resides at 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 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, 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 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 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:

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

Update the front-matter to refine the description:

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

Add new input arguments in the markdown body:

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

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.
• 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 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 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 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 if the skill is listed there.

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