mattpocock/skills — User Guide

A curated collection of agent skills authored by Matt Pocock that extend Claude Code across planning, development, tooling, and writing. Each skill is a self-contained Markdown specification (SKILL.md) installed into your project's .claude/skills/ directory and invoked by name during a Claude Code session.

Repository: mattpocock/skills License: MIT (Copyright 2026 Matt Pocock) Installer: npx skills@latest Skill count: 18 skills, 2 reference docs, 1 helper script

1. Quick Start

The fastest path from zero to a working skill is a single npx call. Pick the skill you want, run the installer, then invoke it inside Claude Code.

npx skills@latest add mattpocock/skills/tdd

Installed mattpocock/skills/tdd into .claude/skills/tdd/

Once installed, ask Claude Code to use it. The skill's SKILL.md description tells Claude when to load the workflow:

> /tdd
> Let's TDD a new shopping cart total calculator.

Claude reads .claude/skills/tdd/SKILL.md, loads the red-green-refactor instructions, and walks you through the cycle one test at a time.

Tip

You can install multiple skills back-to-back. They are independent — each lives in its own folder and only loads when its description matches the current request.

What you get

• 18 production-tested skills covering planning, implementation, refactoring, code quality, GitHub workflow, and writing.
• Bundled reference material (e.g., the TDD pack ships five companion files on deep modules, mocking, refactoring, tests, and interface design).
• A drop-in helper script (block-dangerous-git.sh) for the git-guardrails skill.
• An MIT license that allows commercial and community reuse.

What you need

• Claude Code installed and signed in.
• Node.js with npx (the installer is published to npm as skills).
• Git (most skills explore repos via git log / git diff).
• The GitHub CLI (gh) for any skill that creates issues — see the matrix in section 3.

2. Installation

2.1. Prerequisites

Important

Authenticate the GitHub CLI before you install any issue-creating skill. Run gh auth login once per machine — every issue-creating skill calls gh issue create and will fail with a permissions error if gh is unauthenticated.

2.2. Install a single skill

npx skills@latest add mattpocock/skills/<skill-name>

Replace <skill-name> with any of the 18 skill names (see section 3). The installer creates .claude/skills/<skill-name>/ in the current working directory and copies SKILL.md plus any bundled reference files (e.g., tdd/ ships with deep-modules.md, mocking.md, refactoring.md, tests.md, and interface-design.md).

2.3. Install several skills

Run the installer once per skill — there is no batch syntax:

npx skills@latest add mattpocock/skills/tdd
npx skills@latest add mattpocock/skills/write-a-prd
npx skills@latest add mattpocock/skills/grill-me

Note

The skills do not depend on each other. You can mix and match freely; install only the ones you intend to use to keep Claude's skill list short.

2.4. Verify

After installation, list the contents of .claude/skills/:

ls .claude/skills/

tdd  write-a-prd  grill-me

Each subdirectory contains a SKILL.md (and possibly companion .md files or a scripts/ folder). Claude Code auto-discovers any SKILL.md under .claude/skills/.

2.5. Uninstall

Delete the skill directory:

rm -rf .claude/skills/<skill-name>

2.6. Project vs. global install

Most skills install into the current project (./.claude/skills/). The git-guardrails-claude-code skill is the one explicit exception — it asks during invocation whether to install the hook for this project only (.claude/settings.json) or all projects (~/.claude/settings.json).

3. Available Skills

The pack contains 18 skills grouped into four themes. The table below is the at-a-glance index; each skill is detailed in section 4.

3.1. Skill matrix

Note

The obsidian-vault skill hard-codes the vault path /mnt/d/Obsidian Vault/AI Research/. If your vault lives elsewhere, edit obsidian-vault/SKILL.md after install and replace the path.

3.2. By theme

Planning & Design (6): write-a-prd, prd-to-plan, prd-to-issues, grill-me, design-an-interface, request-refactor-plan.

Development (5): tdd, triage-issue, improve-codebase-architecture, migrate-to-shoehorn, scaffold-exercises.

Tooling & Setup (4): setup-pre-commit, git-guardrails-claude-code, github-triage, qa.

Writing & Knowledge (4): write-a-skill, edit-article, ubiquitous-language, obsidian-vault.

4. Skill Reference

Each entry summarises the skill's purpose, its trigger phrases, what it produces, and the workflow it follows. All summaries are drawn directly from each SKILL.md's description: field and body — there is no fabricated functionality.

4.1. write-a-prd

Purpose. Turn a problem statement into a Product Requirements Document, then file it as a GitHub issue.

Trigger. "write a PRD", "create a product requirements document", "plan a new feature".

Workflow.

1. Asks for a long, detailed description of the problem and any candidate solutions.
2. Explores the repo to verify your assertions and understand the current codebase.
3. Interviews you relentlessly, walking down each branch of the design tree, resolving dependencies one decision at a time.
4. Sketches the major modules to build/modify, actively looking to extract deep modules with simple, testable interfaces.
5. Confirms which modules need tests written for them.
6. Writes a PRD using a template with sections: Problem Statement, Solution, User Stories (numbered, "As an X I want Y so that Z" format), Implementation Decisions, Testing Decisions, Out of Scope, Further Notes.
7. Submits the PRD as a GitHub issue.

Output. A new GitHub issue containing the full PRD body.

Tip

The skill will skip steps it considers unnecessary. Push back if it skips an interview step you wanted — be explicit: "Don't skip the interview, I want to grill the design first."

4.2. prd-to-plan

Purpose. Convert an in-context PRD into a phased implementation plan saved locally.

Trigger. "break down a PRD", "create an implementation plan", "plan phases from a PRD", "tracer bullets".

Workflow.

1. Confirms the PRD is in conversation context (or asks for it).
2. Explores the codebase to understand current architecture and integration layers.
3. Identifies durable architectural decisions (route shapes, schema shape, key data models, auth approach, third-party boundaries).
4. Drafts vertical slices (tracer bullets) — each slice cuts through every layer end-to-end.
5. Quizzes you on granularity and dependencies; iterates until approved.
6. Writes ./plans/<feature-name>.md with sections for architectural decisions and per-phase blocks (Title, User stories, What to build, Acceptance criteria).

Output. A Markdown plan file under ./plans/. Creates the directory if missing.

Important

Phases must NOT include specific file names, function names, or implementation details that are likely to change. They DO include durable decisions like route paths, schema shapes, and data model names. The plan is meant to outlive the first refactor.

4.3. prd-to-issues

Purpose. Break a PRD into independently-grabbable GitHub issues.

Trigger. "convert a PRD to issues", "create implementation tickets", "break a PRD into work items".

Workflow.

1. Asks for the PRD GitHub issue number; fetches it with gh issue view <number> if not in context.
2. Explores the codebase if not already explored.
3. Drafts vertical-slice issues. Each is tagged HITL (human-in-the-loop, requires judgment) or AFK (away-from-keyboard, can be done autonomously). Prefers AFK.
4. Presents the breakdown: Title, Type (HITL/AFK), Blocked by, User stories covered. Asks about granularity, dependencies, splits/merges, and HITL/AFK classification.
5. Iterates until you approve.
6. Creates each issue with gh issue create in dependency order so "Blocked by" can reference real numbers. Does NOT close or modify the parent PRD.

Issue body template. Parent PRD link, "What to build", "Acceptance criteria" checklist, "Blocked by" (or "None — can start immediately"), "User stories addressed".

4.4. grill-me

Purpose. Force a thorough Q&A pass over a plan or design.

Trigger. "stress-test a plan", "get grilled on my design", "grill me".

Workflow. Interviews you relentlessly, walking each branch of the decision tree and resolving dependencies one at a time. Asks one question at a time. Provides its recommended answer with each question. If a question can be answered by exploring the codebase, it explores instead of asking.

Output. A shared mental model captured in conversation — no file is written.

Tip

Issue #16 in the upstream repo notes that the skill sometimes asks 10+ questions at once instead of one-by-one. If that happens, push back: "One at a time, please."

4.5. design-an-interface

Purpose. Generate radically different interface designs for a module using parallel sub-agents, then compare them.

Trigger. "design an API", "explore interface options", "compare module shapes", "design it twice".

Workflow.

1. Gathers requirements: what problem the module solves, who the callers are, key operations, constraints, what should be hidden vs exposed.
2. Spawns 3+ sub-agents in parallel using the Task tool. Each gets a different design constraint:
   • Agent 1: minimise method count (1-3 methods max).
   • Agent 2: maximise flexibility.
   • Agent 3: optimise for the most common case.
   • Agent 4: take inspiration from a specific paradigm or library.
3. Each agent outputs an interface signature, a usage example, what it hides internally, and trade-offs.
4. Presents designs sequentially.
5. Compares them on interface simplicity, generality, implementation efficiency, depth (small interface hiding significant complexity = good), and ease of correct vs incorrect use. Discusses in prose, not tables.
6. Synthesises — often the best design combines insights from multiple options.

Theory. Anchored in John Ousterhout's "A Philosophy of Software Design" — chapter "Design It Twice".

4.6. request-refactor-plan

Purpose. Draft a tiny-commits refactor plan and file it as a GitHub issue.

Trigger. "plan a refactor", "create a refactoring RFC", "break a refactor into safe incremental steps".

Workflow.

1. Asks for a long, detailed problem description and any candidate ideas.
2. Explores the repo to verify assertions.
3. Asks if you've considered alternatives; presents alternatives.
4. Interviews about implementation in extreme detail.
5. Hammers out exact scope — what's in, what's out.
6. Checks test coverage; asks about your test plan if coverage is thin.
7. Breaks the work into tiny commits ("each step as small as possible, so that you can always see the program working" — Martin Fowler).
8. Creates a GitHub issue using a template with: Problem Statement, Solution, Commits (long detailed plain-English plan), Decision Document (modules, interfaces, technical clarifications, schema/API contracts, interactions — no file paths or code snippets), Testing Decisions, Out of Scope, Further Notes.

4.7. tdd

Purpose. Test-driven development with a red-green-refactor loop, one vertical slice at a time.

Trigger. "TDD this", "red-green-refactor", "build a feature with tests first", "fix this bug with TDD".

Anti-pattern flagged. Horizontal slicing — writing all tests first then all implementation produces tests of imagined behavior coupled to data shape. The skill enforces vertical slicing: one test → one implementation → repeat.

Workflow.

1. Plan. Confirm interface changes, prioritise behaviors to test, identify deep-module opportunities, design for testability, get user approval.
2. Tracer bullet. Write ONE test for ONE behavior. RED → fails. GREEN → minimal code to pass.
3. Incremental loop. For each remaining behavior: RED → next test fails. GREEN → minimal code passes.
4. Refactor. Only after all tests pass. Extract duplication, deepen modules, apply SOLID where natural. Run tests after each step.

Per-cycle checklist. Test describes behavior not implementation; uses public interface only; would survive internal refactor; code is minimal for this test; no speculative features added.

Bundled references. deep-modules.md, interface-design.md, mocking.md, refactoring.md, tests.md — see the Admin Guide for what each covers.

Warning

Never refactor while RED. Get to GREEN first. The skill explicitly enforces this.

4.8. triage-issue

Purpose. Investigate a bug, find its root cause, and create a GitHub issue with a TDD fix plan.

Trigger. "triage this bug", "investigate and plan a fix", "file an issue".

Workflow.

1. Captures the problem with at most ONE clarifying question. Then starts investigating.
2. Uses the Agent tool with subagent_type=Explore to find: where the bug manifests, what code path is involved, why it fails (root cause not symptom), what related code exists.
3. Identifies the minimal fix and which behaviors need test coverage.
4. Designs a TDD fix plan as ordered RED-GREEN cycles.
5. Creates the issue with gh issue create (no review prompt) using a template: Problem, Root Cause Analysis, TDD Fix Plan, Acceptance Criteria.

Durability rule. Suggestions must survive radical codebase changes — describe behaviors and contracts, not internal structure.

4.9. improve-codebase-architecture

Purpose. Find architectural improvement opportunities (especially shallow modules) and propose deepening refactors as GitHub issues.

Trigger. "improve architecture", "find refactoring opportunities", "consolidate tightly-coupled modules", "make a codebase more AI-navigable".

Workflow.

1. Explores the codebase using subagent_type=Explore. Looks for friction signals: bouncing between many small files to understand one concept, modules where the interface is nearly as complex as the implementation, pure functions extracted just for testability while real bugs hide in calls, tightly-coupled modules with integration risk in seams.
2. Presents a numbered list of candidates with: cluster, why they're coupled, dependency category, test impact.
3. After you pick a candidate, frames the problem space — constraints, dependencies, an illustrative code sketch (NOT a proposal).
4. Spawns 3+ parallel sub-agents to design radically different interfaces.
5. Compares designs in prose and gives an opinionated recommendation.
6. Creates a GitHub refactor RFC issue with: Problem, Proposed Interface, Dependency Strategy, Testing Strategy, Implementation Recommendations.

Dependency categories. In-process / Local-substitutable / Remote-but-owned (Ports & Adapters) / True external (Mock).

4.10. migrate-to-shoehorn

Purpose. Replace as type assertions in test files with @total-typescript/shoehorn.

Trigger. "migrate to shoehorn", "replace as in tests", "need partial test data".

Migration table.

Workflow.

1. Asks which test files have as assertions, whether large objects with few-needed-properties are involved, and whether intentionally-wrong data is needed.
2. Installs @total-typescript/shoehorn as a dev dependency.
3. Finds candidates with grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts".
4. Replaces as Type with fromPartial() and as unknown as Type with fromAny().
5. Adds imports and runs the type checker.

Warning

Test code only. The skill explicitly forbids using shoehorn in production code.

4.11. scaffold-exercises

Purpose. Create the directory structure for tutorial exercises that pass pnpm ai-hero-cli internal lint.

Trigger. "scaffold exercises", "create exercise stubs", "set up a new course section".

Conventions.

• Sections: XX-section-name/ inside exercises/.
• Exercises: XX.YY-exercise-name/ inside a section.
• Names dash-cased (lowercase, hyphens).
• Each exercise needs at least one of problem/, solution/, explainer/. Default when stubbing: explainer/.
• Each subfolder needs a readme.md that is non-empty and has no broken links.
• A subfolder with code also needs a main.ts (>1 line). Readme-only is fine for stubs.

Workflow. Parse the plan → create directories with mkdir -p → write minimal stub READMEs (a title + description) → run pnpm ai-hero-cli internal lint → fix errors and iterate.

Renames. Use git mv (not mv) to preserve history.

4.12. setup-pre-commit

Purpose. Set up Husky + lint-staged + Prettier with type-check and test scripts in the pre-commit hook.

Trigger. "set up Husky", "configure lint-staged", "add pre-commit hooks".

Workflow.

1. Detects package manager (package-lock.json → npm, pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb → bun; defaults to npm).
2. Installs husky, lint-staged, prettier as devDependencies.
3. Initialises Husky (npx husky init).
4. Writes .husky/pre-commit containing: npx lint-staged, npm run typecheck, npm run test (substituting the detected package manager and omitting the lines for missing scripts).
5. Writes .lintstagedrc with {"*": "prettier --ignore-unknown --write"}.
6. Writes .prettierrc if missing (defaults: useTabs: false, tabWidth: 2, printWidth: 80, singleQuote: false, trailingComma: "es5", semi: true, arrowParens: "always").
7. Verifies via a checklist and commits with the message Add pre-commit hooks (husky + lint-staged + prettier) — a smoke test of the new hook.

Note

Husky v9+ does not need shebangs in hook files. The skill writes hooks without them.

4.13. git-guardrails-claude-code

Purpose. Block dangerous git commands inside Claude Code via a PreToolUse hook before they execute.

Trigger. "block dangerous git commands", "add git safety hooks", "block git push/reset".

Blocks.

When blocked, Claude sees a stderr message stating it does not have authority for these commands and exits with code 2.

Workflow.

1. Asks scope — project (.claude/settings.json) or global (~/.claude/settings.json).
2. Copies scripts/block-dangerous-git.sh into .claude/hooks/ (or ~/.claude/hooks/) and makes it executable.
3. Adds a PreToolUse matcher to the chosen settings file. If the file already exists, merges into the existing hooks.PreToolUse array — never overwrites.
4. Asks if you want to add or remove patterns; edits the script accordingly.
5. Verifies with: echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script> — should exit 2 and print a BLOCKED message.

Caution

The hook runs for every Bash tool call. If jq is missing on your system, the script will fail and the hook will not block anything. Install jq first.

4.14. github-triage

Purpose. Triage GitHub issues through a label-based state machine with grilling sessions.

Trigger. "triage issues", "review incoming bugs or feature requests", "prepare issues for an AFK agent", "manage issue workflow".

Labels. Two axes — Category (bug, enhancement) and State (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). Every issue should have exactly one of each. Conflicts are flagged before any action.

State transitions. Documented as a transition table:

Workflows. "Show what needs attention" (groups unlabeled, needs-triage, and needs-info-with-new-activity, oldest first), "Triage a specific issue" (gather context, recommend, reproduce bugs, grill if needed, apply outcome with preview), "Quick state override" (trust the maintainer, but still preview).

Outputs.

• ready-for-agent → posts an agent brief comment (template in AGENT-BRIEF.md).
• ready-for-human → posts a brief explaining why a human is needed.
• needs-info → posts triage notes (Established / Need from you).
• wontfix (bug) → polite comment + close.
• wontfix (enhancement) → write to .out-of-scope/<concept>.md (template in OUT-OF-SCOPE.md), comment, close.

Important

Before posting any comment or applying any label, the skill ALWAYS shows a preview of exactly what will be posted and which labels will change, then waits for confirmation.

4.15. qa

Purpose. Conversational QA — you describe bugs, the skill files them as durable GitHub issues.

Trigger. "report bugs", "do QA", "file issues conversationally", "QA session".

Workflow.

1. Listens to your description. Asks at most 2-3 short clarifying questions (expected vs actual, repro steps, consistent vs intermittent).
2. Kicks off a background Agent (subagent_type=Explore) to learn the domain language and behavior boundary — but does NOT cite specific files, line numbers, or internal modules in the issue.
3. Decides single issue vs. breakdown:
   • Break down when the fix spans multiple independent areas, has separable concerns, or has multiple distinct failure modes.
   • Single when one behavior is wrong in one place.
4. Files with gh issue create (no review prompt). Uses two body templates — single-issue and breakdown — both with What happened / What I expected / Steps to reproduce / (Blocked by, for breakdowns) / Additional context.
5. Continues until you say you're done.

Issue rules. No file paths or line numbers (they go stale). Use the project's domain language (check UBIQUITOUS_LANGUAGE.md if present). Describe behaviors, not code. Reproduction steps are mandatory. Concise — readable in 30 seconds.

4.16. write-a-skill

Purpose. Bootstrap a new skill with proper structure, progressive disclosure, and bundled resources.

Trigger. "create a new skill", "write a skill", "build a skill".

Workflow.

1. Gathers requirements: task/domain, specific use cases, whether scripts are needed, reference materials.
2. Drafts SKILL.md (concise instructions) plus optional REFERENCE.md / EXAMPLES.md / scripts/ if needed.
3. Reviews with you: coverage, clarity, depth.

Recommended structure.

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

Description requirements. Max 1024 characters. Third person. First sentence: what it does. Second: "Use when [specific triggers]." The description is the ONLY thing the agent sees when deciding which skill to load.

When to add scripts. Operation is deterministic, the same code would be generated repeatedly, errors need explicit handling.

When to split files. SKILL.md exceeds 100 lines, content has distinct domains, advanced features are rarely needed.

4.17. edit-article

Purpose. Improve article drafts by restructuring sections, sharpening clarity, and tightening prose.

Trigger. "edit this article", "revise my draft", "improve clarity".

Workflow.

1. Divides the article into sections by heading. Treats information as a directed acyclic graph — sections must respect their dependencies. Confirms sections with you.
2. For each section, rewrites for clarity, coherence, and flow with a maximum of 240 characters per paragraph.

Note

The 240-char-per-paragraph cap forces short, scannable paragraphs. Longer technical paragraphs may need to be split or argued for explicitly.

4.18. ubiquitous-language

Purpose. Extract a Domain-Driven-Design ubiquitous-language glossary from the current conversation.

Trigger. "define domain terms", "build a glossary", "harden terminology", "ubiquitous language", "domain model", "DDD".

Workflow.

1. Scans the conversation for domain-relevant nouns, verbs, and concepts.
2. Identifies problems: same word for different concepts (ambiguity), different words for the same concept (synonyms), vague or overloaded terms.
3. Proposes a canonical glossary with opinionated term choices.
4. Writes UBIQUITOUS_LANGUAGE.md with grouped tables (Term / Definition / Aliases to avoid), relationships (cardinality), example dialogue (3-5 dev/domain-expert exchanges), and flagged ambiguities.
5. On re-run in the same conversation, reads the existing file, incorporates new terms, updates definitions, and rewrites the example dialogue.

4.19. obsidian-vault

Purpose. Search, create, and manage notes in an Obsidian vault using wikilinks and index notes.

Trigger. "find a note", "create a note", "organise notes in Obsidian".

Default vault path. /mnt/d/Obsidian Vault/AI Research/ — edit obsidian-vault/SKILL.md if your vault is elsewhere.

Conventions.

• Mostly flat at the root level.
• Index notes aggregate related topics (e.g., Skills Index.md, RAG Index.md).
• Title Case for all note names.
• No folders for organisation — links and index notes only.
• [[wikilinks]] syntax. Notes link to dependencies/related notes at the bottom.

Workflows. Search by filename (find ... -name "*.md" | grep -i "keyword"), search by content (grep -rl "keyword" ... --include="*.md"), create a new note (Title Case, write as a unit of learning, add wikilinks at the bottom), find backlinks (grep -rl "\\[\\[Note Title\\]\\]"), find index notes (find ... -name "*Index*").

5. Using a Skill — End-to-End Walkthroughs

The following recipes show real, common flows.

5.1. Recipe: Plan → Implement → Ship

Goal: take a fresh idea from a one-liner to merged code with tests.

1. Brainstorm with grill-me — install and invoke. Answer questions one at a time until the design tree is fully resolved.
2. Capture the plan with write-a-prd — install if you haven't. Walks you from problem statement through user stories and modules; files the PRD as a GitHub issue.
3. Slice with prd-to-issues — install. Reference the PRD issue. Approve the breakdown. Issues are filed in dependency order with Blocked by references.
4. Implement with tdd — install. Pick the first issue. Walk the red-green-refactor loop one vertical slice at a time.

Tip

If at any point the design starts to drift, drop back to grill-me for a focused interrogation of the open question.

5.2. Recipe: Triage a bug end-to-end

Goal: turn a vague bug report into a fix plan.

1. triage-issue — install. Describe the bug in one sentence. The skill explores the codebase, finds the root cause, and files an issue with a TDD fix plan.
2. Implement with tdd — pick up the issue from step 1.

5.3. Recipe: Refactor a tightly-coupled subsystem

1. improve-codebase-architecture — install. Skill explores the codebase and proposes deepening candidates.
2. Pick a candidate. Skill spawns parallel sub-agents to design 3+ radically different interfaces.
3. Skill files a refactor RFC issue with the chosen interface, dependency strategy, and testing strategy.
4. request-refactor-plan (optional) — for very large refactors, you can layer this on top to break the chosen design into tiny commits.
5. tdd — implement.

5.4. Recipe: Wrap a project in safety rails

Run all three setup skills early in a new project:

npx skills@latest add mattpocock/skills/setup-pre-commit
npx skills@latest add mattpocock/skills/git-guardrails-claude-code
npx skills@latest add mattpocock/skills/github-triage

In one Claude Code session: invoke setup-pre-commit (Husky + lint-staged + Prettier + typecheck + tests), then git-guardrails-claude-code (PreToolUse hook against destructive git), then start using github-triage for any incoming issues.

5.5. Recipe: Document the domain alongside the code

Goal: keep a living glossary as the system grows.

1. ubiquitous-language — install. Run it after major design discussions. Each run reads UBIQUITOUS_LANGUAGE.md, merges new terms, and rewrites the example dialogue.
2. qa — install. References the glossary when filing issues so domain language stays consistent.
3. obsidian-vault — if you keep parallel notes, link the same terms in your vault for cross-referencing.

6. Combining Skills

The skills compose deliberately. Understanding the handoff points helps you avoid redundant work.

6.1. Planning chain

grill-me → write-a-prd → prd-to-plan OR prd-to-issues → tdd
                                                   ↑
                                        improve-codebase-architecture
                                        request-refactor-plan

• grill-me clarifies intent before any artefact is written.
• write-a-prd files the PRD as an issue (durable record).
• prd-to-plan writes a local plan file when you're not yet ready to file issues.
• prd-to-issues files issues when you're ready to dispatch work.
• request-refactor-plan and improve-codebase-architecture produce refactor RFCs that feed the same tdd loop.

6.2. Quality chain

• qa files conversational bug reports.
• triage-issue investigates a single bug deeply and produces a TDD fix plan.
• github-triage runs the full state-machine workflow over many issues, batching grilling sessions and producing agent briefs.

6.3. Cross-skill conventions

The pack uses three shared conventions that show up in multiple skills:

Note

When two skills both want to file an issue (e.g., triage-issue and qa), use the one that matches the depth of investigation. triage-issue does a full root-cause exploration; qa does light clarification and bulk filing.

7. Customisation

Each skill is just a Markdown file. After installing, you can edit .claude/skills/<skill-name>/SKILL.md directly.

Common edits:

• Vault path — obsidian-vault/SKILL.md hard-codes /mnt/d/Obsidian Vault/AI Research/. Replace with your path.
• Blocked git patterns — edit git-guardrails-claude-code/scripts/block-dangerous-git.sh to add or remove entries from the DANGEROUS_PATTERNS array.
• Pre-commit script list — setup-pre-commit/SKILL.md writes npx lint-staged, npm run typecheck, npm run test. If your repo has different scripts (e.g., lint, e2e), swap them in.
• Issue templates — every skill that files issues has its template inline. Reword to match your repo's conventions if needed.
• Prettier defaults — setup-pre-commit/SKILL.md ships opinionated defaults; edit them in-place.

Tip

If you change a skill, keep a note of what you changed and why. Re-running npx skills@latest add <skill> will overwrite your edits — the installer copies fresh.

8. Troubleshooting

Error: gh: command not found

Cause. A skill that files issues has tried to call gh issue create but the GitHub CLI is not installed.

Solution.

1. Install the GitHub CLI from https://cli.github.com/.
2. Authenticate: gh auth login.
3. Re-run the skill.

Prevention. Install and authenticate gh before installing write-a-prd, prd-to-issues, request-refactor-plan, triage-issue, qa, github-triage, or improve-codebase-architecture.

Error: hook not blocking dangerous git commands

Cause. The git-guardrails-claude-code hook script is missing jq, is not executable, or is not registered in settings.json.

Solution.

1. Verify jq is installed: jq --version.
2. Verify the script is executable: ls -l .claude/hooks/block-dangerous-git.sh should show x permissions.
3. Verify it is registered: cat .claude/settings.json | jq '.hooks.PreToolUse'.
4. Test manually: echo '{"tool_input":{"command":"git push origin main"}}' | .claude/hooks/block-dangerous-git.sh — should exit 2 with a BLOCKED message.

Prevention. Run the verification command in step 4 immediately after installing the skill.

Error: grill-me asks ten questions at once instead of one

Cause. Known behavior — see issue #16 in the upstream repo.

Solution. Push back explicitly: "One at a time, please. Recommend an answer with each."

Prevention. None at the moment — re-prompt as needed.

Error: setup-pre-commit writes npm run typecheck but my repo has no typecheck script

Cause. The skill checks for missing typecheck and test scripts in package.json and is supposed to omit those lines while telling you. If the omission did not happen, the script reading hit a permissions or parsing issue.

Solution.

1. Open .husky/pre-commit.
2. Delete the npm run typecheck line (or replace with your actual script — e.g., npm run lint).
3. Commit again.

Prevention. Add the expected scripts to package.json before running the skill, or accept that you'll edit .husky/pre-commit once.

Error: npx skills@latest add ... puts the skill in the wrong folder

Cause. Issue #31 in the upstream repo notes occasional wrong-folder installs.

Solution.

1. Locate the misplaced directory.
2. mv it to .claude/skills/<skill-name>/.
3. Verify Claude Code picks it up (it watches .claude/skills/).

Prevention. Run npx skills@latest add ... from the repo root only.

Error: skill description appears to truncate mid-word

Cause. Skill descriptions are capped at 1024 characters. Some are very close to the limit. The agent brief example in github-triage/AGENT-BRIEF.md documents this exact bug template.

Solution. Shorten the description manually inside the installed SKILL.md and reload Claude Code.

Error: obsidian-vault skill does nothing useful

Cause. The vault path /mnt/d/Obsidian Vault/AI Research/ is hard-coded for Matt Pocock's WSL setup.

Solution. Edit .claude/skills/obsidian-vault/SKILL.md and replace every occurrence of the path with your vault location.

Error: migrate-to-shoehorn finds no candidates

Cause. The grep pattern " as [A-Z]" only matches assertions where as is followed by a capitalised type name. Lowercase types or assertions across line breaks are not detected.

Solution. Run grep -rn " as " --include="*.test.ts" --include="*.spec.ts" manually to confirm; copy the candidates back to the agent.

Error: improve-codebase-architecture finds nothing interesting

Cause. The skill works by sensing friction during exploration. In a small or already-deep codebase, friction signals are absent.

Solution. Re-run with a specific module under investigation: "Look specifically at the auth/ subsystem — I think the session module is shallow."

9. FAQ

Q: Do I need every skill?

No. Install only the ones you'll use. Each is independent and lives in its own directory under .claude/skills/.

Q: How does Claude Code decide which skill to load?

It reads the description: field in each SKILL.md and picks the one whose description matches the current conversation. The write-a-skill skill explains this in detail — descriptions are surfaced in the system prompt.

Q: Can I use these skills on non-TypeScript projects?

Most of them, yes. Some are TypeScript-specific by name or example: migrate-to-shoehorn (TypeScript-only), setup-pre-commit (Node-only because of Husky), tdd examples are TypeScript but the methodology is language-agnostic. The PRD/refactor/issue/QA/architecture/triage skills are project-agnostic.

Q: Do the skills modify files outside .claude/skills/?

Some do — by design.

• setup-pre-commit writes .husky/pre-commit, .lintstagedrc, .prettierrc, and updates package.json.
• git-guardrails-claude-code writes .claude/hooks/block-dangerous-git.sh and updates .claude/settings.json (or ~/.claude/settings.json if global).
• prd-to-plan writes ./plans/<name>.md.
• ubiquitous-language writes ./UBIQUITOUS_LANGUAGE.md.
• scaffold-exercises creates exercises/... directory trees.
• github-triage writes .out-of-scope/<concept>.md for rejected enhancement requests.
• All issue-creating skills call gh issue create (no local file writes for those).

Q: Can two skills be invoked in the same conversation?

Yes. Claude Code can load several skills concurrently. The skills are designed to compose — see section 6 for chains.

Q: How are the skills versioned?

The repo is plain Markdown on main. npx skills@latest add ... fetches the latest commit's content. No semantic version is published. Pin a commit by editing the installer URL if you need stability — see the Admin Guide.

Q: Does the pack support a marketplace?

Issue #21 in the upstream repo proposes adding marketplace.json for plugin marketplace support; issue #3 closed in favour of native Claude Code marketplace integration. As of source commit 651eab0, no marketplace file exists in the repo.

Q: Is the pack open-source?

MIT licensed (see LICENSE). Issue #6 (closed) was the request that added the license.

Q: Where does the design philosophy come from?

Two recurring sources are cited inline:

• John Ousterhout's A Philosophy of Software Design — deep modules, "Design It Twice".
• Martin Fowler — "make each refactoring step as small as possible, so that you can always see the program working."

Domain-Driven Design (Eric Evans) underlies the ubiquitous-language skill.

Q: Where do I report bugs or request skills?

Open an issue at the upstream repository on GitHub. The maintainer triages with the github-triage workflow described in section 4.14.