Help us improve
Share bugs, ideas, or general feedback.
From pm-skills
Applies targeted improvements to an existing pm-skills skill based on feedback, validation reports, or convention changes. Reads current files, previews proposed changes, writes on confirmation, and suggests a version bump.
npx claudepluginhub product-on-purpose/pm-skills --plugin pm-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/pm-skills:utility-pm-skill-iterateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill improves an existing pm-skills skill by applying targeted changes
Evolves an existing skill by refining content in-place or creating an advanced variant, including assessment, version bumps, and cross-reference sync. Use for skill maintenance.
Updates existing jaan.to skills with spec compliance and documentation sync. Use when modifying or improving skills in the catalog.
Updates SKILL.md files to fix specific review findings without rewriting validated sections.
Share bugs, ideas, or general feedback.
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:
utility-pm-skill-validateutility-pm-skill-validate and getting a report with findingsutility-pm-skill-builderutility-pm-skill-validate firstutility-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.mddeliver-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 utility-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 utility-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.)--- at
byte 0 of the file (no preceding content). If the previous content
violated byte-0 placement (e.g., HTML attribution comment on line 1),
surface this defensively before applying other changes and offer to
fix the placement as part of the same write. Reference:
library/skill-output-samples/SAMPLE_CREATION.md Section 5.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 `utility-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.