[DOCS] `/run-skill-generator` per-project verify skills are silently rewritten on every session; v2.1.205 fix to only rewrite on bundled-command changes is undocumented

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

The "Run and verify your app" subsection of skills.md (the table of /run, /verify, and /run-skill-generator, plus the closing paragraph that describes the per-project skill at .claude/skills/run-<name>/). The "Bundled skills" section directly above it, the /run / /verify / /run-skill-generator rows in the commands reference, and the Agent SDK slash-commands reference line that names code-review and verify as bundled skills should be cross-checked in the same pass.

Current Documentation

From skills.md lines 27-41, the "Run and verify your app" subsection introduces the three bundled skills and then says:

Three bundled skills work together to launch your app and confirm changes against the running app instead of just tests: | Skill | Purpose | | :--------------------- | :---------------------------------------------------------------------------------------------------------------- | | /run | Launch and drive your app to see a change working | | /verify | Build and run your app to confirm a code change does what it should, without falling back to tests or type checks | | /run-skill-generator | Teach /run and /verify how to build and launch your project | {/ min-version: 2.1.145 /}All three skills require Claude Code v2.1.145 or later. /run and /verify work without setup. They infer the launch from your project type (CLI, server, TUI, browser-driven) and from what's in your README, package.json, or Makefile. That inference gets unreliable for projects that need anything beyond a standard launch: a database, an env file, a graphical session, a multi-step build. /run-skill-generator records the recipe instead. It gets your app running from a clean environment, captures what worked (the install commands, the env vars, the launch script), and commits it as a per-project skill at .claude/skills/run-<name>/. After that, /run, /verify, and any other agent in the repo follow the recorded recipe instead of rediscovering it. Run /run-skill-generator once per project, and again if the build or launch process changes.

The matching /run and /run-skill-generator rows in the commands reference (commands.md lines 118-119) and the /verify row at line 144 do not mention any per-session rewriting behavior either:

| /run | Skill. Launch and drive your project's app to see a change working, not only passing tests. See Run and verify your app. {/ min-version: 2.1.145 /}Requires Claude Code v2.1.145 or later | | /run-skill-generator | Skill. Teach /run and /verify how to build, launch, and drive your project's app from a clean environment by writing a per-project skill. {/ min-version: 2.1.145 /}Requires Claude Code v2.1.145 or later | | /verify | Skill. Confirm a code change does what it should by building your project's app, running it, and observing the result, rather than relying on tests or type checks. See Run and verify your app. {/ min-version: 2.1.145 /}Requires Claude Code v2.1.145 or later |

The page never explains that the per-project skill files at .claude/skills/run-<name>/ may be rewritten by Claude Code itself, and it never says when those rewrites happen. The closing guidance — "Run /run-skill-generator once per project, and again if the build or launch process changes" — addresses only user-driven regeneration; it leaves Claude Code's own rewriting rule entirely implicit.

What's Wrong or Missing?

The v2.1.205 changelog records:

Fixed project verify skills being rewritten on every session instead of only when a documented command changed

That change is a meaningful behavior update for the per-project skills at .claude/skills/run-<name>/, but the skills page does not describe the behavior in either its pre-fix or post-fix form. Three consequences follow.

A. The docs never state that Claude Code itself can rewrite the per-project skill

Before v2.1.205, Claude Code rewrote the per-project verify skill on every session. After v2.1.205, it only rewrites them when a documented command (one of the bundled /run-skill-generator, /run, or /verify skills) has actually changed. Neither rule is named in the docs. A user who hand-edits the per-project skill to add a step, swap an env var, or pin a specific dependency has no way to know:

• whether their edit will be preserved on the next session;
• whether Claude Code itself will overwrite the file based on its own trigger rule;
• which "documented command" the v2.1.205 fix refers to.

The current "Run /run-skill-generator once per project, and again if the build or launch process changes" sentence frames the per-project skill as something the user owns. That is true for content, but the rewrite trigger lives inside Claude Code, and the docs do not say so.

B. The v2.1.205 fix is not recorded anywhere on the page

This is the kind of behavior change that the existing version-history pattern on other pages (e.g., the "Version history" tables in agent-view.md and the {/* min-version: ... */} markers in permission-modes.md) is designed to record. skills.md has neither — the closest version marker anywhere near the "Run and verify your app" section is the existing {/* min-version: 2.1.145 */} row that introduces the three skills, and the page has no v2.1.205 entry.

A reader who upgrades to v2.1.205 will see the changelog note, then look at the docs page for guidance, and find no signal that the per-project skill behavior changed in this version. They will not know whether the new behavior is already in effect on their machine, what the rewrite trigger is, or whether the files they hand-edited before the upgrade are still canonical.

C. The "documented command" in the changelog is ambiguous without a docs pointer

The changelog phrase "only when a documented command changed" refers, by context, to the bundled /run-skill-generator, /run, and /verify skills, but the user-facing surface for those is the table on this very page. Without a docs entry that names those three skills as the trigger set, the phrase reads as "only when something on this page changes", which is too broad — the rewrite trigger is a content match against the bundled skill payloads, not a docs version. A reader who edits .claude/skills/run-<name>/ after a Claude Code upgrade and sees their file rewritten on the next session will not be able to tell which change in Claude Code is the documented-command change the fix is gating on.

Suggested Improvement

Replace the closing sentence of the "Run and verify your app" section in skills.md (currently "Run /run-skill-generator once per project, and again if the build or launch process changes.") with prose that names the v2.1.205 rewrite rule and the per-project skill location together. For example:

{/ min-version: 2.1.205 /}/run-skill-generator records the recipe as a per-project skill at .claude/skills/run-<name>/. Claude Code may rewrite the files in that directory so the recipe tracks the bundled /run, /verify, and /run-skill-generator skills. As of v2.1.205 the rewrite fires only when one of those bundled commands has actually changed; earlier versions rewrote the files on every session. Edit the files by hand only when you intend to override the bundled recipe, and re-run /run-skill-generator to restore the canonical version after a Claude Code upgrade that changes a documented command.

In the same pass:

• Extend the min-version: 2.1.145 row in the "Run and verify your app" table to mention the v2.1.205 rewrite-rule change, in the same shape as the per-release bullets on other pages. A short footnote immediately under the table is the lowest-friction option:

> {/ min-version: 2.1.205 /}As of v2.1.205, Claude Code rewrites the per-project recipe only when the bundled /run, /verify, or /run-skill-generator command has changed. Earlier versions rewrote the recipe on every session.

• Add a one-line note to the /run, /verify, and /run-skill-generator rows in commands.md (lines 118-119, 144) pointing back at the rewrite rule. The note can mirror the new skills.md wording, for example: {/* min-version: 2.1.205 */}Claude Code may rewrite per-project skills generated by this command. See [Run and verify your app](https://code.claude.com/docs/en/skills#run-and-verify-your-app).

• In the Agent SDK slash-commands reference line 483, where code-review and verify are named as bundled skills, add a sibling sentence noting that the SDK honors the same per-project-skill rewrite rule so SDK consumers see the same behavior on query() sessions as on the CLI.

Keep the wording tied to the public changelog phrase "only when a documented command changed" so the docs describe the user-visible contract without exposing implementation-specific trigger details.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | Primary documentation: "Run and verify your app" section, "Bundled skills" section above it, and the closing sentence that talks about running /run-skill-generator once per project |
| https://code.claude.com/docs/en/commands | Secondary documentation: /run, /verify, and /run-skill-generator rows in the commands table should note the v2.1.205 rewrite rule and link back to the skills page |
| https://code.claude.com/docs/en/agent-sdk/slash-commands | Agent SDK cross-reference: line 483 names code-review and verify as bundled skills and should record the same per-project-skill behavior for SDK consumers |

Total scope: 3 pages affected.

Other locations to cross-check in the same pass (not new docs sites, just consistency):

• The claude directory page at https://code.claude.com/docs/en/claude-directory, which describes .claude/skills/ as the home for project skills (around line 1468 in the table that maps skills/<name>/SKILL.md to project or global scope); a one-line note that per-project skills generated by /run-skill-generator are subject to Claude Code's rewrite rule would close the loop for readers who land on that page first.
• The "Bundled skills" section in skills.md line 23, which lists /code-review, /batch, /debug, /loop, and /claude-api. /run, /verify, and /run-skill-generator are mentioned only in the "Run and verify your app" subsection directly below, so a reader scanning the bundled-skills list at the top of the page has no signal that those three are the same kind of object and are subject to the same per-project-skill rewrite rule.

Version marker: This changelog entry ships in v2.1.205 (July 8, 2026). The new prose should use {/* min-version: 2.1.205 */} so older clients reading the docs do not see the rewrite rule in the rendered "Run and verify your app" section.