# 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.

```bash
npx skills@latest add mattpocock/skills/tdd
```

```text
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:

```text
> /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

| Requirement | Why it's needed |
|---|---|
| Claude Code | The host that loads `SKILL.md` files and runs the workflows. |
| Node.js + `npx` | The installer (`skills@latest`) is a small npm package that copies SKILL files into your project. |
| Git | Skills read `git remote`, `git log`, and run `git mv` for renames. |
| GitHub CLI (`gh`) | Required for `write-a-prd`, `prd-to-issues`, `request-refactor-plan`, `triage-issue`, `qa`, `github-triage`, and `improve-codebase-architecture`. |
| Bash + `jq` | Required for the `git-guardrails-claude-code` hook script. |

> [!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

```bash
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:

```bash
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/`:

```bash
ls .claude/skills/
```

```text
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:

```bash
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

| Skill | Theme | Triggers (Claude detects) | Needs `gh`? |
|---|---|---|---|
| `write-a-prd` | Planning | "write a PRD", "create a product requirements document", plan a new feature | Yes |
| `prd-to-plan` | Planning | "break down a PRD", "create an implementation plan", "tracer bullets" | No (writes local file) |
| `prd-to-issues` | Planning | "convert a PRD to issues", "create implementation tickets" | Yes |
| `grill-me` | Planning | "stress-test a plan", "get grilled on my design", "grill me" | No |
| `design-an-interface` | Planning | "design an API", "explore interface options", "design it twice" | No |
| `request-refactor-plan` | Planning | "plan a refactor", "create a refactoring RFC" | Yes |
| `tdd` | Development | "TDD this", "red-green-refactor", "test-first development" | No |
| `triage-issue` | Development | "triage this bug", "investigate and plan a fix" | Yes |
| `improve-codebase-architecture` | Development | "improve architecture", "find refactoring opportunities", "deepen modules" | Yes |
| `migrate-to-shoehorn` | Development | "migrate to shoehorn", "replace `as` in tests" | No |
| `scaffold-exercises` | Development | "scaffold exercises", "create exercise stubs" (ai-hero-cli context) | No |
| `setup-pre-commit` | Tooling | "set up Husky", "configure lint-staged", "add pre-commit hooks" | No |
| `git-guardrails-claude-code` | Tooling | "block dangerous git commands", "add git safety hooks" | No |
| `github-triage` | Tooling | "triage issues", "review incoming bugs", "manage issue workflow" | Yes |
| `qa` | Tooling | "QA session", "report bugs conversationally" | Yes |
| `write-a-skill` | Writing | "create a new skill", "write a skill" | No |
| `edit-article` | Writing | "edit an article", "improve a draft" | No |
| `ubiquitous-language` | Writing | "extract a glossary", "ubiquitous language", "DDD terms" | No |
| `obsidian-vault` | Writing | "find a note in Obsidian", "create an Obsidian note" | No |

> [!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.**

| Pattern | Replacement |
|---|---|
| `obj as Type` | `fromPartial(obj)` |
| `obj as unknown as Type` | `fromAny(obj)` |
| Force full object | `fromExact(obj)` |

**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.**

| Command pattern | Why blocked |
|---|---|
| `git push` (all variants, including `--force`) | Pushing remote state by mistake |
| `git reset --hard` | Discards uncommitted work |
| `git clean -f` / `git clean -fd` | Deletes untracked files |
| `git branch -D` | Force-deletes a branch |
| `git checkout .` / `git restore .` | Discards working-tree changes |

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:

| Current state | Can transition to | Trigger |
|---|---|---|
| unlabeled | needs-triage / ready-for-agent / ready-for-human / wontfix | Skill or maintainer |
| needs-triage | needs-info / ready-for-agent / ready-for-human / wontfix | Maintainer via skill |
| needs-info | needs-triage | Skill (detects reporter reply) |

**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.**

```text
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:

```bash
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

```text
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:

| Convention | Where it appears |
|---|---|
| Vertical slices (tracer bullets) | `tdd`, `prd-to-plan`, `prd-to-issues` |
| Deep modules (small interface, large implementation) | `tdd`, `write-a-prd`, `design-an-interface`, `improve-codebase-architecture` |
| `gh issue create` for durable records | `write-a-prd`, `prd-to-issues`, `request-refactor-plan`, `triage-issue`, `qa`, `github-triage`, `improve-codebase-architecture` |

> [!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.

---

_Generated April 2026 from mattpocock/skills at 651eab0. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._