marcin-urbanski/claude-skills

The skills, subagents and hooks I use every day with Claude Code. This repo is also where they live: the folders in ~/.claude/skills on my Mac are symlinks to it, so every change is tracked in git.
They encode my way of working, and some are strict on purpose: tdd writes a failing test even when asked to skip it. Take what fits your workflow and turn off the rest.
## Skills
| Skill | What it's for |
| handoff | Writes one handoff per thread of work to .md in the repo's handoffs folder, ~/.claude/handoffs/ / (the main checkout's path with every character other than a letter or digit replaced by -, for example -Users-me-Developer-app; $CLAUDECONFIGDIR replaces ~/.claude when set), when a session gets long or a task is finished, then gives you a prompt to paste into the next session. The folder is outside the repo, so the file survives the worktree being deleted and can be written from worktrees the Claude desktop app creates, which may not write into the main checkout. A session that coordinates parallel worktree sessions writes overview.md there instead. Works with the two hooks below. |
| spec-first | Plans a change before any code is written, scaled to its size: a small fix goes straight to tests, a feature gets a short spec, an epic gets a spec and a plan committed on its feature branch, an adversarial review of the plan before it is built, a review per task, and an adversarial review of the whole branch with a judge before the PR. Feature and epic specs also say how success will be checked after release, and propose deeper work the user can pick. An epic in a project without CODINGSTANDARDS.md starts one from a template with Core candidates for Swift/SwiftUI, Laravel, WordPress and Next.js. |
| design-check | Turns a design into work: a Claude Design handoff export, a Design artifact (pulled into docs/design with the Artifact tool), a Figma link (read through the Figma plugin) or PNG/JPG mockups (values estimated). Writes a spec for a new project, reports what changed when the design changes, and checks the UI against it before a pull request. |
| tdd | Red, green, refactor for every change to production code. |
| systematic-debugging | Find the root cause before fixing anything. |
| verification-before-completion | Run the tests, linters and build before saying something works. |
| ux-principles | My UI/UX rulebook: avoiding generic AI-looking design, conversion psychology within honest limits, visual craft, interaction and app patterns, e-commerce product pages and checkout, and native iPhone, iPad and Mac apps. |
| pr | The format for a pull request body that a human can review fast: a small visual of the change (pseudocode, call tree, Mermaid, a diff of the shape), before-and-after evidence, and a merge danger call (one-way or two-way door, blast radius). spec-first uses it when it opens a PR. |
| retro | /retro after a hard session or a PR review: reads a digest of the session transcript (digest.py) and the PR's review comments, then proposes, most severe first, the automated check, coding standard, reviewer rule, skill fix or CLAUDE.md pointer that stops the same mistake from happening again. It keeps CODINGSTANDARDS.md within its template's limit by sharpening, merging or replacing rules. Only you can invoke it, and it changes nothing until you pick. |