controller-cleanup — Claude Code skill: refactor Symfony controllers
The controller-cleanup skill extracts business logic from fat Symfony controllers into services, handlers and commands. Leaves actions lean, delegating and responding only.
MIT ★ 234 updated 2026-10-05
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-codeWhat controller-cleanup does
The skill reads a controller, lists what it does — validation, authorization, logic, persistence — and moves each concern to its layer. Before refactoring, it writes a functional test to lock down HTTP behavior: same status codes, same payloads. Input is mapped to DTOs via #[MapRequestPayload] or #[MapQueryString], authorization moves to a voter, side effects to events or messages.
Services are injected as constructor or method arguments; pulling them from the container is forbidden. Logic does not move to a "manager" that is the old controller under a new name. Console commands are written as invokable #[AsCommand] classes (Symfony 7.3+) that delegate to the same services.
Output: an action in five to ten lines, extracted DTOs, services, voters or handlers with one responsibility each, tests confirming HTTP behavior stayed the same.
What it helps with
- extract business logic from a controller into services and handlers
- cover an action with a functional test before refactoring
- map input to a DTO using
#[MapRequestPayload] - move authorization to a voter, side effects to events
- write a console command as an invokable
#[AsCommand]class
Example prompts for the agent
- Break down
UserController::registerinto services for validation, user creation and email sending - Cover
POST /orderswith a functional test, then extract logic toCreateOrderHandler - Rewrite
app:import-productsas an invokable command that delegates toProductImporter
How to install controller-cleanup
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-code2Manually: put the files in place
~/.claude/skills/controller-cleanup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/controller-cleanup/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a codex2Manually: put the files in place
.agents/skills/controller-cleanup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a cursor2Manually: put the files in place
.cursor/skills/controller-cleanup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dev-toolings/superpowers-symfony content/skills/controller-cleanup2Manually: put the files in place
.github/skills/controller-cleanup/SKILL.md1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a gemini-cli2Platform CLI
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/controller-cleanupManually: put the files in place
.devin/skills/controller-cleanup/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about controller-cleanup
How do I install controller-cleanup in Claude Code?
Run npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-code, the skill path is ~/.claude/skills/controller-cleanup/SKILL.md.
What does the controller-cleanup skill do?
It moves business logic, validation and authorization from Symfony controllers into services, DTOs, voters and handlers. The action stays short — delegation and response only.
How does controller-cleanup preserve HTTP behavior?
Before refactoring, the skill writes a functional test to lock down response codes and bodies. After moving logic, the test confirms nothing broke.
Source text
SKILL.md · MIT
--- name: controller-cleanup description: Refactor fat controllers into lean ones by extracting business logic to services, handlers, and invokable commands capabilities: [read, search] tags: [architecture] # projected by `bun run build` — do not edit by hand allowed-tools: - Read - Glob - Grep --- # Controller Cleanup (Symfony) ## Use when - A controller action holds business logic, queries, or more than a handful of lines. - Input parsing, validation, authorization and persistence are mixed in one action. - A console command does the real work itself instead of delegating it. ## Default workflow 1. List what the action does: input, validation, authorization, business logic, persistence, side effects. 2. Cover the current HTTP behavior with a functional test before moving anything. 3. Map input to a DTO with `#[MapRequestPayload]` or `#[MapQueryString]` and let the validator reject it. 4. Move business logic into a service or a command handler, authorization into a voter, side effects into events or messages. 5. Leave the action to resolve, authorize, delegate and respond, in five to ten lines. ## Guardrails - Type-hint services as arguments or constructor parameters; never pull them from the container. - Keep the HTTP behavior identical: same status codes, same payloads. - Do not move the logic into a "manager" that is the old controller under a new name. - Write console entry points as invokable `#[AsCommand]` classes (Symfony 7.3+) that delegate to the same services. ## Progressive disclosure - Use this file for execution posture and risk controls. - Open references when deep implementation details are needed. ## Output contract - Lean actions that delegate. - The extracted DTOs, services, voters or handlers, one responsibility each. - Functional tests showing the HTTP behavior is unchanged. ## References - `reference.md`
© dev-toolings · MIT · dev-toolings/superpowers-symfony