Per-Project Run Skills: /run and /run-skill-generator

Source: raw/reddit-1u9d58g.md (r/ClaudeCode, u/lolas_tounge, 2026-06-18, score 84) — /run is a documented Claude Code skill (“Launch and drive this project’s app”); the /run-skill-generator companion and the token-saving framing are the author’s report.

A pattern for stopping Claude Code from re-deriving how to build and launch your app on every session. The idea: do the build/launch discovery once, write it into a per-project skill, then invoke /run to read that skill instead of paying tokens to rediscover the same mechanics each time. It is a concrete application of the “keep the always-loaded CLAUDE.md lean; lazy-load mechanics into a skill” discipline.

Key Takeaways

• The problem it solves. Without a saved skill, the agent works out how to build, launch, and drive the app from the repo on every session — slow, inconsistent, and a recurring token cost.
• /run-skill-generator does discovery once. It probes how to build, how to launch, and how to drive the app, then writes all of it into a per-project skill. /run afterward just reads the skill and executes. ^[inferred — mechanism as described by the source author; /run is confirmed as a built-in Claude Code skill, /run-skill-generator is the author’s named companion]
• It captures the non-obvious, app-specific gotchas the agent would otherwise rediscover or get wrong each run. The author’s Spring Boot example: self-signed cert on :9000 (every curl needs -sk), a form-login CSRF token that must ride the same session cookie, a silent bind failure when the port is taken, and a Gradle warning that looks like a failure but isn’t.
• Three stated payoffs: (1) tokens — /run reading one focused skill kills the per-session rediscovery spend; (2) lean CLAUDE.md — run mechanics load only when /run needs them, not every turn; (3) testing — once the agent can reliably launch and drive the app, it can actually exercise it (functionality, deps, even security testing against the live target).
• Output is a reusable smoke script. In the example: build with the Gradle wrapper, kill whatever holds the port, launch the jar, wait for startup, hit seven endpoints, clean exit — with an optional --keep-running so /run can leave the app up and keep working.

Related

• Agent Skills Overview — the SKILL.md format and lazy-loading model this pattern relies on.
• Skills vs Projects — when to reach for a repeatable skill vs a Project.
• Seven Claude Skills Run My Business — other per-workflow skill patterns.
• goal Command Walkthrough — adjacent custom-command pattern for repeatable Claude Code workflows.
• Verifier-First Loops — “the agent can now launch and drive the app” is the precondition for live verification loops.

Try It

1. In a project where Claude Code keeps re-figuring out how to run the app, invoke /run-skill-generator (or ask Claude to author a per-project “run” skill) and let it probe build + launch + drive steps once.
2. Have it record the app-specific gotchas (ports, certs, auth/CSRF, false-positive warnings) into the skill, plus a smoke script that builds, launches, waits for startup, and hits key endpoints.
3. Keep run mechanics out of CLAUDE.md — the skill loads only when /run is invoked.
4. From then on, use /run to launch/drive the app before any live functional or security testing.