Improves existing PM skills by applying targeted changes from feedback, validation reports, or conventions. Previews file diffs, writes on confirmation, suggests version bumps.
From pm-skillsnpx claudepluginhub product-on-purpose/pm-skillsThis skill uses the workspace's default tool permissions.
references/EXAMPLE.mdreferences/TEMPLATE.mdDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
This skill improves an existing pm-skills skill by applying targeted changes based on input you provide. It reads the current skill files, proposes changes as before/after previews grouped by file, and writes them on your confirmation. After applying changes, it suggests a version bump class and offers to update HISTORY.md.
The iterator accepts any of these as input:
/pm-skill-validate/pm-skill-validate and getting a report with findings/pm-skill-builder/pm-skill-validate first/pm-skill-validate --all first to triage, then iterate one skill at a timeWhen asked to iterate on a skill, follow these steps:
Accept the skill name in any form:
deliver-prdskills/deliver-prd/SKILL.md/prdResolve to the canonical directory path: skills/{name}/.
If the skill directory does not exist, stop and report: "Skill directory
skills/{name}/ does not exist. Use /pm-skill-builder to create it."
Read all files in the skill directory:
| File | Required | Purpose |
|---|---|---|
SKILL.md | yes | Frontmatter + instructions (the primary edit target) |
references/TEMPLATE.md | yes | Output template |
references/EXAMPLE.md | yes | Worked example |
HISTORY.md | no | Version history (needed for Step 7) |
Record the exact content of each file at this point. You will compare against this content before writing in Step 5 (stale-preview guard).
If reading files is not possible (MCP/embedded environment), ask the user to paste the relevant file contents before proceeding (see Degraded Mode).
Regardless of input type, extract a structured list of intended changes before generating any edits. This normalization step is what makes the unified flow work consistently across all input types.
If the input is a validation report (from /pm-skill-validate):
Report schema: v1 in the header. If absent or a different
schema version, warn: "This report uses an unrecognized schema. I'll
do my best but may miss structured fields."## Recommendations section.| to extract:
Target:: file pathAction: (next line): what to changeIf the input is free text (feedback, convention change, improvement request):
Present the normalized list for user confirmation:
Intended changes:
1. Target: skills/{name}/SKILL.md -> {section}
Change: {what will change}
Source: {validation report check ID | user feedback | convention change}
2. Target: skills/{name}/references/EXAMPLE.md -> {section}
Change: {what will change}
Source: {source}
If the user wants to modify the list (add, remove, or change items), adjust and re-present before proceeding.
For each intended change, generate the proposed edit and present it as a before/after block grouped by file:
### skills/{name}/SKILL.md
**{Section name} -- before:**
> {exact current content of the section being changed}
**{Section name} -- after:**
> {proposed new content for this section}
### skills/{name}/references/EXAMPLE.md
**{Section name} -- before:**
> {exact current content}
**{Section name} -- after:**
> {proposed new content}
Preview rules:
Ask: "Apply these changes? [yes / no]"
If the user says no, ask what to adjust and return to Step 3 or Step 4.
Before writing any file, re-read each target file and compare its content to what you recorded in Step 2.
If any target file has changed since Step 2:
{path} has changed since the preview was generated.
Regenerating preview with current content."If all target files match:
updated field in SKILL.md frontmatter to today's date.
(The updated field tracks when the file was last modified, regardless
of whether a version bump is accepted.)After changes are applied, classify the overall change and suggest a version bump class. Do NOT auto-write the version number.
Classification rules (from docs/internal/skill-versioning.md):
| Change type | Bump class | Examples |
|---|---|---|
| Wording clarified, examples improved, typos fixed | patch | Reworded checklist item, better example scenario, description expanded |
| New optional capability or section added | minor | New optional output section, handles more scenarios, new quality check |
| Required contract changed, interaction pattern breaks | major | Command renamed, required section removed, "done" definition narrowed |
Tie-breaker: If a user must do something new to stay compliant with the skill's required contract, classify as major. If the new behavior is additive or optional, classify as minor. If the required behavior is unchanged and only clarified, classify as patch.
Present the suggestion:
Suggested bump: {class} ({reason}).
Current version: {current}.
Bump to {suggested}? [yes / override / skip]
After the version decision, produce a change summary and handle HISTORY.md based on the current state:
If HISTORY.md exists and version was bumped:
| Version | Date | Release | ... header## X.Y.Z section below## X.Y.Z section with the change summary.If HISTORY.md does not exist and this is the skill's second version:
Offer to create it. "This is the second version of this skill. Would you
like me to create HISTORY.md with entries for both versions? [yes / no]"
On yes: create HISTORY.md with the format from docs/internal/skill-versioning.md,
including entries for both the original version (from release history or
effort brief) and the new version.
If HISTORY.md does not exist and version was not bumped: No offer. HISTORY.md is premature until the skill has shipped a second version.
If HISTORY.md exists but version was not bumped (skip): No offer. The change summary is available in the conversation for the user to use at their discretion.
Present a final summary:
## Iteration Complete: {skill-name}
**Files changed:**
- skills/{name}/SKILL.md -- {summary}
- skills/{name}/references/EXAMPLE.md -- {summary}
**Version:** {current} -> {new} ({class}) | or: unchanged (skipped)
**HISTORY.md:** updated | created | skipped | not applicable
**Next steps:**
- Run `/pm-skill-validate {name}` to verify the changes pass
- Run local CI: `bash scripts/lint-skills-frontmatter.sh`
- If satisfied, commit the changes
If you cannot read skill files directly (e.g., running via MCP or in an embedded environment without file system access):
The iterator MUST:
updated frontmatter field on every applyThe iterator MUST NOT:
Before completing the iteration, verify:
updated date was set to today in SKILL.md frontmatterSee references/EXAMPLE.md for a completed iteration demonstrating
a validation-report-driven improvement to a real shipped skill.