@d0cbr0wn/claude-skills

Personal Claude Code skills — install once, available everywhere.

Install

npm install -g @d0cbr0wn/claude-skills

The postinstall script symlinks all skills into ~/.claude/skills/. Restart Claude Code after installing — skills are loaded at startup and there is no hot-reload.

Update

npm update -g @d0cbr0wn/claude-skills

Stale symlinks (renamed or removed skills) are cleaned up automatically on update. Restart Claude Code to pick up the changes.

Skills

| Skill | Purpose | |---|---| | go-dev | End-to-end development from brief/issue to merged-ready PR | | brief-to-issues | Transform a product brief into a plan file and GitHub issues | | pr-prereview | Validate a branch (security + review + tests) then open a PR | | pr-review | Maintainer merge decision — APPROVE or REQUEST_CHANGES | | review | Two-axis diff review: Standards and Spec, in parallel sub-agents | | diagnose | Disciplined bug diagnosis loop across 6 structured phases | | grill-me | Relentless one-question-at-a-time design interview | | grill-my-brief | Holistic pre-implementation analysis of a feature brief — outputs a criticality-ordered question list (supports --full for exhaustive output) | | write-a-skill | Scaffold a new Claude Code skill with proper structure |

go-dev

Invoke: /go-dev, /go-dev #42, /go-dev 12 14 17, or /go-dev <plain text brief>

Full development pipeline from input to merged-ready PR. Handles a brief, one or more GitHub issues, or an epic — one backlog item per full cycle, never batching.

What it accepts

| Input | Behaviour | |---|---| | No arguments | Looks for a plan in .claude/plans/. Asks if none or multiple found. | | #N or N | Fetches the issue. Stops if closed. Expands if labelled epic. | | #N #M … or N,M,… | Queues multiple issues in that order. All must be open. | | Plain text | Brief mode — decomposes, confirms, then implements without creating issues. |

Epic expansion: reads the task-list in the epic body (- [ ] #12 …), skips closed issues, and queues the rest in listed order. Non-recursive.

What it does — full pipeline

Before the first cycle:

0. Configure base branch — asks which branch to work from and target for PRs. Defaults to dev (verified to exist). Accepts a custom name (validated); if the branch doesn't exist, offers dev as fallback; stops if you refuse. The resolved branch is shown alongside the queue so you can correct it before any code is written.

   | Your input | dev exists | Result | |---|---|---| | Enter / dev | yes | Use dev | | Enter / dev | no | Stop — specify a valid branch on re-invoke | | <name> | — | Validate; if found use it, if not offer dev fallback | | Refuse fallback | — | Stop |

1. Build & confirm queue — resolves input, structures the backlog if needed (plan files, briefs), shows the full ordered queue with the base branch header, and waits for your confirmation before writing any code. Each item is independently deliverable and sized at ~1–3 h.

Then, one cycle per item:

1. Analyse — understands the business need, impacted files, and risks. Stops to ask on any blocking ambiguity.
2. Branch — checks the tree is clean, pulls the base branch, creates feat/, fix/, docs/, refactor/, or chore/ branch.
3. Implement — touches only files relevant to the item. No side-refactors. Writes tests as part of the definition of done.
4. Validate — runs tests, lint, typecheck, and build sequentially. Every error must be fixed.
5. Quality loop — invokes /pr-prereview and applies this severity framework:
   • CRITICAL / HIGH → fix immediately, re-validate, re-run prereview. Loop until zero.
   • MEDIUM → explicit decision: FIX now or ACCEPT with written justification. Any MEDIUM findings marked FIX are applied and pushed as an additional commit before the PR is opened.
   • LOW → never blocking.
   • When /pr-prereview exits with no blockers, it creates the PR.
6. Implementation summary — appended to the PR description: objective, changes, validation results, pre-review findings.
7. Final review — invokes /pr-review independently (pre-review findings are not passed, so the verdict is uncontaminated).
8. Advance queue — marks item done, announces progress, moves to the next item without asking again. Stops when the queue is empty.

Implications

• Asks for the base branch at the very start — every feature branch is created from it and every PR targets it. The resolved branch is echoed before you confirm the queue, so you always know where things will land.
• Creates one branch and one PR per backlog item — never opens a PR that covers multiple items.
• Asks for queue confirmation once at the start; does not interrupt between items.
• In brief mode, no GitHub issues are created unless you explicitly ask.
• Both /pr-prereview and /pr-review are invoked automatically as part of the cycle.

brief-to-issues

Invoke: /brief-to-issues, or say "brief to issues", "transform this brief", "create issues from…"

Turns a product brief into a persistent plan file and a set of GitHub issues ready to develop.

What it does

1. Analyze — extracts business objective, affected users, constraints, ambiguities, risks, and dependencies. Asks blocking clarification questions if the brief is insufficient.
2. Create plan artifact — saves .claude/plans/<title>-plan.md before anything else. This is the single source of truth for all subsequent steps.
3. Stress-test — invokes the grill-me skill on the plan. Uses the output to tighten scope and resolve open questions before proceeding.
4. Build backlog — decomposes into tasks of 1–3 h each, with title, description, acceptance criteria, dependencies, and estimate.
5. Epic (conditional) — creates an Epic issue if the backlog has ≥ 6 tasks, spans multiple features, or involves multiple technical domains.
6. Create issues — runs gh issue create for each task. Language follows the brief. Each issue references the Epic if one was created.
7. Consistency check — verifies full coverage, no task over 3 h, no orphan tasks, coherent dependencies.

Implications

• The plan file is always written before any GitHub issue is created.
• grill-me is mandatory — it runs automatically as step 3, not optionally.
• Your answers to clarification questions are binding hard constraints through the entire workflow. If a later step conflicts with one of your answers, the skill stops and asks rather than silently overriding.
• Issues are created via gh CLI — you must be authenticated and in a GitHub repo.

pr-prereview

Invoke: /pr-prereview, or say "ready to PR", "pre-PR checks", "check before push", "push and PR"

Validates the current branch across three dimensions in parallel, then opens a well-structured PR if everything is green.

What it does

Runs in parallel:

• Security audit (sub-agent) — reads the diff directly, looking for injection vulnerabilities, hardcoded secrets, broken access control, sensitive data exposure, and deprecated patterns. Each finding gets a severity: LOW / MEDIUM / HIGH / CRITICAL.
• Code review (sub-agent) — invokes /code-review high on the diff: correctness bugs, simplifications, efficiency issues.

Runs sequentially in the main thread:

• Typecheck — detects and runs tsc --noEmit or the project's typecheck script.
• Lint — detects and runs ESLint, Biome, or the project's lint script.
• Tests — detects and runs the project's test suite (Jest, pytest, cargo test, go test, etc.).

Blocking conditions (PR not created)

• Security audit finds HIGH or CRITICAL issues
• Any test fails
• Code review finds correctness bugs (not style-only warnings)

Style warnings and missing tests are reported but do not block.

On success

Creates the PR targeting the detected base branch (dev by default, falling back to main) with a Conventional Commits title and a structured body (Summary, Changes, Test plan).

Final report

Always outputs a report with per-dimension status and a verdict, whether the PR was created or blocked.

Implications

• This skill is invoked automatically by go-dev as part of its quality loop — you rarely need to call it manually unless you're running a standalone branch.
• Security and code review run simultaneously with tests, so total time is roughly max(security+review, tests), not their sum.

pr-review

Invoke: /pr-review, /pr-review #42, or say "review this PR", "should I merge this"

Acts as the repository maintainer. Renders a single merge decision: APPROVE or REQUEST_CHANGES. Posts the full review as a GitHub PR comment.

What it does

1. Fetches the PR diff, description, and linked issue via gh.
2. Establishes the Definition of Done from the first available source: linked issue → plan file → PR description → project conventions.
3. Evaluates the diff against the DoD and checks for bugs, regressions, missing tests, and security risks.
4. Renders a decision with:
   • Blocking issues — each with a required corrective action. If none: "No blocking issues detected."
   • Non-blocking suggestions — optional, kept short.
5. Posts the review as a PR comment prefixed with 🤖 Claude Code — PR Review.

The only reasons to REQUEST_CHANGES

• Feature incomplete relative to the DoD
• Likely or certain bug
• Likely or certain regression
• Significant security risk
• Required technical contract violated
• Tests absent when project conventions require them
• Significant production risk

Never blocks for: naming, refactoring opportunities, alternative architectures, style preferences, minor tech debt.

Implications

• This skill is invoked automatically by go-dev as the final step of each cycle. The review runs after the PR is created, not before — and it does not receive the pre-review findings, so its verdict is independent.
• The review is posted as a comment, not via gh pr review --approve/--request-changes — this keeps it visible and attributable without triggering GitHub's merge-blocking review system.

review

Invoke: /review, /review main, /review HEAD~5

Two-axis diff review between HEAD and a fixed point you supply. Runs both axes as independent parallel sub-agents so neither contaminates the other's context.

The two axes

• Standards — does the diff conform to this repo's documented coding conventions? (CLAUDE.md, CONTRIBUTING.md, ADRs, style guides, tsconfig, linter config.)
• Spec — does the diff faithfully implement what the originating issue or PRD asked for? Are any requirements missing, partial, or wrong? Is there scope creep?

What it does

1. Pin the fixed point — uses whatever you supply (branch, commit SHA, tag, HEAD~N). Asks if you didn't specify.
2. Find the spec — looks for issue references in commits, then plan/spec files, then asks you.
3. Find the standards sources — CLAUDE.md, CONTRIBUTING.md, ADRs, config files.
4. Spawn two sub-agents in parallel — Standards agent and Spec agent each read the diff independently with their respective context.
5. Aggregate — reports findings under ## Standards and ## Spec headings, verbatim. Ends with a one-line summary and the worst single issue.

Why two axes

A change can pass one and fail the other:

• Follows every convention but implements the wrong thing → Standards pass, Spec fail.
• Does exactly what the issue asked but breaks project conventions → Spec pass, Standards fail.

Reporting separately prevents one axis from masking the other.

Implications

• Requires a fixed point — it will always ask if you don't provide one.
• If no spec is found and you confirm there isn't one, the Spec axis is skipped and noted.
• The parallel sub-agents add latency compared to a single pass, but produce cleaner, uncorrupted findings.
• The Spec axis's issue-fetching workflow relies on docs/agents/issue-tracker.md — a file from the upstream mattpocock/skills suite that is not bundled here. If your repo doesn't have it, the skill will ask you where the spec is instead of fetching it automatically. The Standards axis is unaffected.

diagnose

Invoke: /diagnose, or say "diagnose this", "debug this", "something is broken"

Structured 6-phase bug diagnosis. Skips no phase without explicit justification.

The 6 phases

1. Build a feedback loop — the most important phase. Constructs a fast, deterministic, agent-runnable pass/fail signal for the bug: failing test, curl script, CLI invocation, headless browser, replay harness, fuzz loop, bisection, or differential. Does not proceed to Phase 2 without a loop it believes in.
2. Reproduce — runs the loop. Confirms the failure matches what you described (not a nearby different failure). Records the exact symptom.
3. Hypothesise — generates 3–5 ranked, falsifiable hypotheses before testing any of them. Shows the ranked list and waits briefly for your input (domain knowledge often re-ranks instantly).
4. Instrument — maps each probe to a specific hypothesis prediction. Changes one variable at a time. Tags debug logs with unique prefixes for easy cleanup.
5. Fix + regression test — writes the regression test before the fix (if a correct seam exists). Watches it fail, applies the fix, watches it pass.
6. Cleanup + post-mortem — removes all debug instrumentation, verifies the original repro no longer reproduces, states which hypothesis was correct in the commit message, and asks what would have prevented the bug.

Implications

• If a feedback loop cannot be built, the skill stops and tells you exactly what it tried. It will ask for access to the reproducing environment, a captured artifact, or permission to add temporary production instrumentation. It does not proceed by staring at code.
• For non-deterministic bugs, the goal is raising the reproduction rate to a debuggable level (50%+), not necessarily a clean repro.
• The phase structure is intentional — single-hypothesis generation is a known failure mode, which is why Phase 3 requires 3–5 before testing any.

grill-me

Invoke: /grill-me, or say "grill me", "stress-test this plan"

Relentless design interview. Asks one question at a time, walks every branch of the decision tree, and doesn't stop until shared understanding is reached. For each question it also provides its own recommended answer.

What it does

• Identifies every decision point, dependency, and assumption in your plan or design.
• Asks questions one at a time — not a list dump.
• If a question can be answered by exploring the codebase, it explores first instead of asking.
• Resolves each branch before moving to the next.

Implications

• This skill is invoked automatically by brief-to-issues as a mandatory stress-test step on the plan before issue creation.
• Expect it to be uncomfortable — that's the point. Gaps it surfaces are gaps you'd otherwise hit during implementation.
• It does not produce an artifact; the value is the shared understanding reached during the session.

grill-my-brief

Invoke: /grill-my-brief, or say "grill my brief", "analyse ce brief", "analyze this brief"

Options: --full — lift the default 10-question cap and surface all critical and important questions (ceiling ~23).

Holistic pre-implementation risk analysis on a feature brief. Surfaces critical questions across architecture, backend, frontend, performance, scalability, security, UX, observability, ops, and compliance — then delivers them as a criticality-ordered list ready to submit to the stakeholder.

What it does

1. Completeness check — if the brief is too vague (no scope, no business goal, no context), stops and asks 2–3 targeted clarifying questions before analyzing. Does not analyze a blank canvas.
2. Domain analysis — selects only the domains where a real risk or ambiguity exists from: Architecture, Backend, Frontend, Performance, Scalability, Security, UX / Interface, Observability, Operational, Compliance / Data.
3. Question list — classifies each question as CRITICAL, IMPORTANT, or REFINEMENT, then orders them: CRITICAL first, then IMPORTANT, then REFINEMENT. Within each class, highest-impact first (the question whose answer most changes the architecture or unblocks the most work).
4. Output cap — two modes:
   • Standard (default): if more than 10 questions are identified, outputs only the 10 most critical and adds a refinement notice listing the overflow domains.
   • Full (--full): outputs all CRITICAL questions (no cap) + up to 15 IMPORTANT questions, with an overall ceiling of 23. No refinement notice. REFINEMENT questions are excluded.

Output format

## Questions — [Brief title]

1. [Question]? — *[Risk/impact]*
2. ...

---
> [Standard mode only, if capped: refinement notice + axes to explore]

No preamble, no summary after the list. Questions only. Output is saved to .claude/grills/<slug>.md.

Implications

• Language of output matches the language of the brief by default. Override by telling the skill which language to use.
• The standard 10-question cap is intentional — a brief that generates more than 10 blocking questions is not ready to implement. Use --full when you want to surface every risk before a major review or architecture decision.
• The skill selects domains dynamically — a pure backend microservice won't generate UX questions; a consumer-facing feature won't trigger Operational questions unless relevant.

write-a-skill

Invoke: /write-a-skill, or say "create a new skill", "build a skill", "scaffold a skill"

Guides you through creating a new Claude Code skill with proper structure, progressive disclosure, and bundled resources.

What it does

1. Gather requirements — asks about the domain, specific use cases, whether scripts are needed, and any reference materials.
2. Draft the skill — creates SKILL.md with concise instructions. Splits into REFERENCE.md and EXAMPLES.md if content exceeds 100 lines. Adds scripts/ if deterministic operations are needed.
3. Review with you — presents the draft and iterates until it covers your use cases.

Key constraints it enforces

• description must be under 1024 characters and include explicit trigger phrases — it's the only thing Claude reads when choosing a skill.
• SKILL.md stays under 100 lines; overflow goes into supplemental files.
• Scripts are added only for deterministic, repeatable operations — not for logic that varies per project.

Implications

• The description field is the most critical part of a skill. A vague description means the skill is never invoked. A good description includes what it does (first sentence) and "Use when [specific triggers]" (second sentence).
• After creating the skill, register it in this repo by creating skills/<name>/SKILL.md and running node scripts/install.js to symlink it locally.

How it works

scripts/install.js walks skills/*/, finds each SKILL.md, and symlinks the directory into ~/.claude/skills/<name>. Because they're symlinks into the package, skills stay up to date when you run npm update.

Adding a skill

skills/<name>/
├── SKILL.md       # required — YAML frontmatter + prompt body
└── scripts/       # optional utility scripts

---
name: skill-name
description: What it does. Use when [specific triggers].
---

Skill body here.

The description is all Claude sees when choosing a skill — max 1024 chars, make the triggers explicit.