# mattpocock/skills — Administrator and Developer Guide > An architectural and contributor reference for `mattpocock/skills`. This collection is a Claude Code "skill pack" — eighteen self-contained Markdown specifications, two reference documents, and one helper shell script, distributed via `npx` and consumed by Claude Code. There is no compiled binary, no API server, no database. The system's value is the structure and discipline of the skill specifications themselves. **Repository:** `mattpocock/skills` **Source commit:** `651eab0` (2026-04-01) **License:** MIT (Copyright 2026 Matt Pocock) **Total source files:** 30 **Top-level skill directories:** 18 **Helper scripts:** 1 (`git-guardrails-claude-code/scripts/block-dangerous-git.sh`) --- ## 1. Architecture Overview ### 1.1. What this is `mattpocock/skills` is a **Markdown-only authoring repository** for Claude Code skills. Each skill is a directory whose primary artefact is a `SKILL.md` file consisting of a YAML frontmatter block and a Markdown body. Optional companion files (`REFERENCE.md`, additional topic-specific Markdown, or a `scripts/` subfolder) provide deeper material. The repository ships zero application code, zero tests, and zero build pipeline. Distribution is handled externally by the `skills` npm package (`npx skills@latest add //`), which copies the relevant directory into the consumer's `.claude/skills/` folder. > [!NOTE] > Because the deliverable is plain Markdown read by an LLM, the "architecture" of this project is the **structure of its specifications** and the **conventions that govern them**. There is no runtime to diagram. The diagrams below describe authoring and consumption, not execution. ### 1.2. Authoring and consumption flow ```text ┌──────────────────────────────────┐ │ mattpocock/skills (this repo) │ │ │ │ 18 SKILL.md files │ │ + 5 TDD reference files │ │ + 2 github-triage briefs │ │ + 1 improve-arch reference │ │ + 1 git-guardrails script │ │ + README.md, LICENSE │ └────────────────┬─────────────────┘ │ │ git push to main ▼ ┌──────────────────────────────────┐ │ GitHub: mattpocock/skills │ └────────────────┬─────────────────┘ │ │ fetched by `npx skills@latest` ▼ ┌──────────────────────────────────┐ │ Consumer project │ │ .claude/skills// │ │ .claude/hooks/ (guardrails) │ │ .claude/settings.json │ └────────────────┬─────────────────┘ │ │ loaded at conversation time ▼ ┌──────────────────────────────────┐ │ Claude Code session │ │ reads SKILL.md `description:` │ │ to decide which to load │ └──────────────────────────────────┘ ``` ### 1.3. Component inventory | Component | Path | Role | |---|---|---| | Index | `README.md` | Human-readable index grouping skills by theme with one-line descriptions and install commands. | | License | `LICENSE` | MIT, Copyright 2026 Matt Pocock. | | Planning skills | `write-a-prd/`, `prd-to-plan/`, `prd-to-issues/`, `grill-me/`, `design-an-interface/`, `request-refactor-plan/` | Six planning-and-design skills covering PRD authoring, slicing, interrogation, interface design. | | Development skills | `tdd/`, `triage-issue/`, `improve-codebase-architecture/`, `migrate-to-shoehorn/`, `scaffold-exercises/` | Five development skills covering TDD, bug triage, architectural deepening, type-assertion migration, exercise scaffolding. | | Tooling skills | `setup-pre-commit/`, `git-guardrails-claude-code/`, `github-triage/`, `qa/` | Four tooling skills covering pre-commit hooks, dangerous-git blocking, issue triage, conversational QA. | | Writing skills | `write-a-skill/`, `edit-article/`, `ubiquitous-language/`, `obsidian-vault/` | Four writing skills covering skill authoring, article editing, glossary extraction, and Obsidian vault management. | | TDD reference set | `tdd/{deep-modules,interface-design,mocking,refactoring,tests}.md` | Five companion documents bundled with the `tdd` skill explaining its underlying theory and patterns. | | GitHub triage reference set | `github-triage/{AGENT-BRIEF,OUT-OF-SCOPE}.md` | Two reference documents that the `github-triage` skill links to. | | Architecture reference | `improve-codebase-architecture/REFERENCE.md` | Companion document with dependency category definitions and the issue template. | | Helper script | `git-guardrails-claude-code/scripts/block-dangerous-git.sh` | The one shell script in the repo. Implements the PreToolUse hook. | ### 1.4. Repository statistics - **Total tracked files:** 30 (per the briefing manifest; 18 SKILL.md + 5 TDD reference + 2 github-triage + 1 architecture reference + 1 hook script + README + LICENSE + 1 internal triage doc). - **Total source characters:** 507 (briefing's `total_source_chars` — counts only what the AST extractor processed, which for a Markdown-only repo is effectively trivial). - **Complexity tier:** medium (briefing). - **Extracted feature density:** zero functions, classes, CLI commands, API endpoints, or config keys. The AST extractor does not parse Markdown. > [!NOTE] > The AST-extraction zero-counts are not a defect of this guide — they reflect that the artefact is prose, not code. Briefing confidence is 100 because every skill is fully readable from `SKILL.md`. The lone shell script is short and transparent (~25 lines). ### 1.5. Technology stack | Layer | Technology | Where it appears | |---|---|---| | Distribution | npm package `skills` (external) | `npx skills@latest add ...` install commands across all `SKILL.md` and `README.md`. | | Hosting | GitHub | Repo lives on GitHub; the `gh` CLI is the canonical way every issue-creating skill writes back to it. | | Format | YAML frontmatter + Markdown body | Every `SKILL.md`. | | Hook script | Bash + `jq` | `git-guardrails-claude-code/scripts/block-dangerous-git.sh`. | | Pre-commit (consumed by `setup-pre-commit`) | Husky 9+, lint-staged, Prettier | Configured in target consumer projects, not this repo. | | Test-data utility (consumed by `migrate-to-shoehorn`) | `@total-typescript/shoehorn` | `npm i @total-typescript/shoehorn` in target consumer projects. | | Linter (consumed by `scaffold-exercises`) | `pnpm ai-hero-cli internal lint` | Run in target consumer projects (Matt Pocock's AI Hero curriculum). | --- ## 2. The `SKILL.md` Specification The single most important contract in the project is what a `SKILL.md` looks like. The pack's own `write-a-skill` skill documents the canonical shape; every other skill in the repo conforms to it. This section is the authoritative reference. ### 2.1. File layout ```text / ├── SKILL.md # Main instructions (required) ├── REFERENCE.md # Detailed reference (optional) ├── EXAMPLES.md # Usage examples (optional) └── scripts/ # Utility scripts (optional) └── helper.sh ``` Names use kebab-case. The skill's directory name becomes its install path: `mattpocock/skills/`. ### 2.2. Frontmatter contract Every `SKILL.md` begins with a YAML frontmatter block delimited by `---`: ```yaml --- name: skill-name description: Brief description of capability. Use when [specific triggers]. --- ``` | Field | Required | Constraints | |---|---|---| | `name` | Yes | Kebab-case, must match the directory name. | | `description` | Yes | Max 1024 characters; written in third person; first sentence describes the capability; second sentence begins "Use when …" and lists explicit trigger keywords/contexts. | > [!IMPORTANT] > The `description` is the **only** thing the host agent sees when deciding which skill to load. It is surfaced in the system prompt alongside every other installed skill. Vague descriptions cause the agent to miss the right skill or load the wrong one. Every skill in this repo follows the "what + when" template. ### 2.3. Body conventions After the frontmatter, the body is plain Markdown. The repo's skills consistently use: - A top-level heading naming the skill (often duplicating the directory name). - A **Process** or **Workflow** section as the spine, numbered or sub-headed by step. - Optional sections: **Why**, **Anti-patterns**, **Templates**, **Notes**, **Reference docs**. - Inline templates inside `...` pseudo-tags or fenced code blocks. - Heavy use of checklists (`- [ ]`) for verification points. ### 2.4. Description heuristics in this repo | Skill | Description shape | |---|---| | `write-a-prd` | Capability + "Use when user wants to write a PRD, create a product requirements document, or plan a new feature." | | `tdd` | Capability + "Use when user wants to build features or fix bugs using TDD, mentions 'red-green-refactor', wants integration tests, or asks for test-first development." | | `grill-me` | Capability + "Use when user wants to stress-test a plan, get grilled on their design, or mentions 'grill me'." | | `git-guardrails-claude-code` | Capability + "Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code." | The pattern is consistent: a capability sentence followed by a "Use when …" clause that mixes intent verbs with literal trigger keywords (the user's exact phrases). ### 2.5. Length budget `write-a-skill/SKILL.md` recommends keeping `SKILL.md` under 100 lines. When a skill exceeds that, content is split into adjacent files. The exemplars in this repo: - `tdd/SKILL.md` (107 lines) splits theory across five companion files. - `github-triage/SKILL.md` (175 lines) keeps its long state machine in-line but pushes templates to `AGENT-BRIEF.md` and `OUT-OF-SCOPE.md`. - `improve-codebase-architecture/SKILL.md` (76 lines) pushes the issue template and dependency definitions to `REFERENCE.md`. Edge cases also exist: `edit-article/SKILL.md` is just 14 lines (one-section workflow) and `grill-me/SKILL.md` is 10 lines (a single instruction prompt). > [!TIP] > Don't pad a skill to hit a length target. The smallest skills (`grill-me`, `edit-article`) are valuable because they're tight directives, not because they're "complete" in a documentation sense. --- ## 3. Authoring a New Skill ### 3.1. Decide whether to add a new skill Before writing, ask: 1. Could an existing skill in the pack be edited to handle this case? Editing tends to be cheaper and reduces the agent's "which skill?" search space. 2. Is the trigger distinct? If the description would overlap heavily with an existing skill, the agent will be confused. 3. Does the new skill have stable, repeatable steps? Skills are workflows; one-off prompts don't belong here. The pack's own `write-a-skill` workflow encodes this: gather requirements, draft, then **review with the user** before merging. ### 3.2. Drafting Recommended sequence: 1. Write the frontmatter `name` and `description`. Force yourself to articulate the trigger in the description before the body. 2. Write the workflow as a numbered list (one heading per step is fine for longer skills). Use sub-headings sparingly. 3. Add templates inside `...` blocks if the skill files an artefact (issue, PRD, plan). 4. Add a checklist where verification steps exist (`- [ ]`). 5. Run a self-review using the checklist below. ### 3.3. Review checklist Adapted from `write-a-skill/SKILL.md`: - [ ] Description is third-person, includes "Use when …" clause, and is under 1024 characters. - [ ] `SKILL.md` is under 100 lines (or content is split into companion files for a justified reason). - [ ] No time-sensitive information (versions, dates, "as of 2026"). - [ ] Terminology is consistent — same word for same concept across the body. - [ ] At least one concrete example is included. - [ ] References go one level deep — `SKILL.md` may link to a companion `.md`, but that companion does not link further down a chain. - [ ] Workflow steps are numbered or clearly ordered. - [ ] Templates use fenced code blocks with a language tag. ### 3.4. Bundling scripts Add a `scripts/` subfolder when: - The operation is deterministic (validation, formatting, exact pattern matching). - The same code would be regenerated by Claude on every invocation, wasting tokens and risking subtle drift. - Errors need explicit handling (exit codes, stderr messages — see `block-dangerous-git.sh` for an example). If you ship a script: 1. Make it `#!/bin/bash` with `set -e` if not parsing JSON, or rely on `jq` if you are. 2. Document its expected stdin / stdout / exit codes inside the `SKILL.md`. 3. Keep it short — the scripts in this pack are self-evident on a single screen. ### 3.5. Bundling reference docs Use companion `.md` files when content has distinct subdomains or when advanced material is rarely needed. The TDD pack is the canonical example — `SKILL.md` is the workflow, while `deep-modules.md`, `interface-design.md`, `mocking.md`, `refactoring.md`, and `tests.md` provide topic-specific depth. Cross-link from `SKILL.md` to the reference using relative Markdown links: `[deep modules](deep-modules.md)`. The `npx skills@latest add ...` installer copies the entire skill directory, so relative links keep working in the consumer project. ### 3.6. Pull request flow The repo is on `main` only — there is no `develop` or release branch. Submit a pull request against `main`. The maintainer reviews via the same `github-triage` workflow he documents (in fact, he dogfooded it: the AGENT-BRIEF and OUT-OF-SCOPE structures were applied retroactively to make incoming issues a productive intake channel). > [!NOTE] > Issue #6 in the upstream repo (closed) was the request to add an MIT license. Issue #11 (closed) standardised the skill prefix. These two closures established that the pack accepts community contributions and that breaking renames will be considered. --- ## 4. Skill-by-Skill Module Reference This section enumerates every skill in the pack with its file footprint, exposed contract, and consumed dependencies. The **consumer interface** column lists what callers (Claude Code) see; the **environment** column lists external tools the workflow assumes. ### 4.1. Planning & Design #### `write-a-prd/` - **Files:** `SKILL.md` (74 lines). - **Purpose:** Interview-driven PRD authoring with module sketching. - **Consumer interface:** Slash invocation; ends in a filed GitHub issue containing Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes. - **Environment:** `gh` (issue create), repo with main branch + write access. - **Notable internals:** Explicitly looks for "deep module" extraction opportunities; uses checklists for testing-decision capture. #### `prd-to-plan/` - **Files:** `SKILL.md` (107 lines). - **Purpose:** Convert a PRD in conversation context into a phased plan saved locally. - **Consumer interface:** Writes `./plans/.md`. Plan format includes durable architectural decisions and per-phase Title / User stories / What to build / Acceptance criteria. - **Environment:** Filesystem write to current working directory. - **Notable internals:** Explicit "vertical-slice rules" embedded as `` block (also used in `prd-to-issues`). Forbids file/function names in plan body to keep it durable. #### `prd-to-issues/` - **Files:** `SKILL.md` (88 lines). - **Purpose:** Slice a PRD into independently-grabbable GitHub issues. - **Consumer interface:** N issues created with `gh issue create`, each in dependency order; HITL/AFK marked. - **Environment:** `gh`, parent PRD must already be a filed issue. - **Notable internals:** Iterative quizzing loop until granularity is approved. Issue template requires Parent PRD link, Acceptance Criteria checklist, Blocked-by, User stories. #### `grill-me/` - **Files:** `SKILL.md` (10 lines). - **Purpose:** Tightest skill in the pack — a single directive to interview relentlessly with codebase exploration as a substitute for asking obvious questions. - **Consumer interface:** Conversation only. No artefact. - **Environment:** None. #### `design-an-interface/` - **Files:** `SKILL.md` (94 lines). - **Purpose:** Spawn parallel sub-agents to produce 3+ radically different interface designs and compare. - **Consumer interface:** Conversation only — outputs sequential design presentations and a comparison. - **Environment:** Task tool / sub-agent spawning. - **Notable internals:** Anchored in Ousterhout's "Design It Twice"; assigns each agent a different design constraint (minimise methods / maximise flexibility / optimise common case / paradigm-driven). #### `request-refactor-plan/` - **Files:** `SKILL.md` (68 lines). - **Purpose:** Produce a tiny-commits refactor plan and file as a GitHub issue. - **Consumer interface:** GitHub issue with Problem Statement, Solution, Commits (long plain-English breakdown), Decision Document, Testing Decisions, Out of Scope, Further Notes. - **Environment:** `gh`, repo write access. - **Notable internals:** Cites Martin Fowler on tiny-commit refactoring. Forbids file paths and code snippets in Decision Document. ### 4.2. Development #### `tdd/` - **Files:** `SKILL.md` (107 lines), `deep-modules.md`, `interface-design.md`, `mocking.md`, `refactoring.md`, `tests.md`. - **Purpose:** Red-green-refactor TDD with vertical slicing (tracer bullets). - **Consumer interface:** Conversation only — drives test-first development one cycle at a time. - **Environment:** Test runner in the consumer project. - **Reference set:** - `deep-modules.md` — Ousterhout's deep vs shallow module visual; reduce methods, simplify params, hide complexity. - `interface-design.md` — Three rules: accept dependencies don't create them; return results don't side-effect; keep surface area small. - `mocking.md` — Mock at system boundaries only (external APIs, sometimes DBs/time/FS); design for mockability via dependency injection and SDK-style per-endpoint interfaces. - `refactoring.md` — Refactor candidate catalogue: duplication, long methods, shallow modules, feature envy, primitive obsession. - `tests.md` — Good (integration-style, observable behavior) vs bad (implementation-coupled, mocks internal collaborators) tests with side-by-side TypeScript examples. - **Notable internals:** Explicit "horizontal slicing is bad" anti-pattern. Per-cycle checklist enforces minimum implementation and behavior-only tests. #### `triage-issue/` - **Files:** `SKILL.md` (102 lines). - **Purpose:** Investigate a bug end-to-end and produce a TDD-based fix issue. - **Consumer interface:** GitHub issue with Problem, Root Cause Analysis, TDD Fix Plan (RED/GREEN cycles), Acceptance Criteria. - **Environment:** `gh`, `git log` reads, sub-agent (`subagent_type=Explore`). - **Notable internals:** Single clarifying question ceiling. Durability rule: suggestions describe behaviors and contracts, not internal structure. #### `improve-codebase-architecture/` - **Files:** `SKILL.md` (76 lines), `REFERENCE.md`. - **Purpose:** Architectural friction-finding via exploration; deepens shallow modules; files refactor RFCs. - **Consumer interface:** Numbered candidate list, framed problem space, parallel sub-agent design comparison, GitHub refactor RFC issue. - **Environment:** `gh`, sub-agent `Explore`, sub-agent design pool. - **Reference set:** - `REFERENCE.md` — Four dependency categories (in-process / local-substitutable / remote-but-owned via Ports & Adapters / true external via mock); testing-strategy principle "replace, don't layer"; full issue template. #### `migrate-to-shoehorn/` - **Files:** `SKILL.md` (118 lines). - **Purpose:** Replace `as` type assertions in test files with `@total-typescript/shoehorn`. - **Consumer interface:** Edited test files, `@total-typescript/shoehorn` added to dev dependencies, type-check confirmation. - **Environment:** TypeScript project with tests. - **Notable internals:** Patterns: `as Type` → `fromPartial()`; `as unknown as Type` → `fromAny()`; full-object force → `fromExact()`. Hard rule: test code only, never production. #### `scaffold-exercises/` - **Files:** `SKILL.md` (106 lines). - **Purpose:** Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`. - **Consumer interface:** New directory tree under `exercises/`, stub `readme.md` per variant, lint pass. - **Environment:** `pnpm`, `ai-hero-cli` (Matt Pocock's curriculum tool). - **Notable internals:** Section naming `XX-name`; exercise naming `XX.YY-name`; uses `git mv` (not `mv`) for renames to preserve history. ### 4.3. Tooling & Setup #### `setup-pre-commit/` - **Files:** `SKILL.md` (91 lines). - **Purpose:** Husky 9+ + lint-staged + Prettier with optional typecheck/test commands in the pre-commit hook. - **Consumer interface:** New `.husky/pre-commit`, `.lintstagedrc`, `.prettierrc` (if absent), updated `package.json`, signed commit running through the new hook as a smoke test. - **Environment:** Node + npm/pnpm/yarn/bun. - **Notable internals:** Auto-detects package manager via lockfile presence. Omits `typecheck`/`test` lines when those scripts are absent in `package.json` (and tells the user). Husky v9+ does not need shebangs in hooks. #### `git-guardrails-claude-code/` - **Files:** `SKILL.md` (95 lines), `scripts/block-dangerous-git.sh`. - **Purpose:** PreToolUse hook that intercepts and blocks dangerous git commands before Claude executes them. - **Consumer interface:** Modified `.claude/settings.json` (or `~/.claude/settings.json`), executable hook at `.claude/hooks/block-dangerous-git.sh`. - **Environment:** Bash, `jq`. - **Notable internals (script body):** ```bash #!/bin/bash INPUT=$(cat) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command') DANGEROUS_PATTERNS=( "git push" "git reset --hard" "git clean -fd" "git clean -f" "git branch -D" "git checkout \." "git restore \." "push --force" "reset --hard" ) for pattern in "${DANGEROUS_PATTERNS[@]}"; do if echo "$COMMAND" | grep -qE "$pattern"; then echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2 exit 2 fi done exit 0 ``` Exit code 2 is the convention Claude Code uses to signal "do not run this Bash command and surface the stderr." The skill explicitly merges into existing `hooks.PreToolUse` arrays rather than overwriting. #### `github-triage/` - **Files:** `SKILL.md` (175 lines), `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`. - **Purpose:** Label-based state machine for issue triage with mandatory grilling-then-preview before any label change. - **Consumer interface:** Modified GitHub labels, posted comments (agent briefs, triage notes, wontfix explanations), local `.out-of-scope/.md` files for rejected enhancements. - **Environment:** `gh`, repo with maintainer rights, `git remote` to infer the repo. - **State machine summary:** | From | To | Trigger | |---|---|---| | unlabeled | needs-triage / ready-for-agent / ready-for-human / wontfix | First look | | needs-triage | needs-info / ready-for-agent / ready-for-human / wontfix | After grilling or maintainer override | | needs-info | needs-triage | Skill detects reporter reply | - **Companion docs:** - `AGENT-BRIEF.md` — Principles (durability over precision, behavioral not procedural, complete acceptance criteria, explicit scope) and template (Category, Summary, Current/Desired behavior, Key interfaces, Acceptance criteria, Out of scope) with two good examples (bug, enhancement) and one annotated bad example. - `OUT-OF-SCOPE.md` — `.out-of-scope/.md` directory format (one file per concept, not per issue), file template (heading, "Why this is out of scope", code samples, "Prior requests" list), kebab-case naming, durability rules for the reasoning. #### `qa/` - **Files:** `SKILL.md` (130 lines). - **Purpose:** Conversational QA — files durable issues from chat-style descriptions. - **Consumer interface:** Filed GitHub issues using one of two templates (single-issue, breakdown). - **Environment:** `gh`, sub-agent `Explore` (background), optional `UBIQUITOUS_LANGUAGE.md` in the repo. - **Notable internals:** Caps clarifying questions at 2-3 before filing. Bans file paths and line numbers in issue bodies. Maximises parallelism via independent breakdown issues. ### 4.4. Writing & Knowledge #### `write-a-skill/` - **Files:** `SKILL.md` (117 lines). - **Purpose:** Bootstrap a new skill following the conventions of this repo. - **Consumer interface:** New `skill-name/SKILL.md` (and optional companions). - **Environment:** Filesystem write to working directory. - **Notable internals:** Encodes the description-format contract; gives "good" and "bad" description examples; lists when to add scripts and when to split files. #### `edit-article/` - **Files:** `SKILL.md` (14 lines). - **Purpose:** Edit articles section-by-section respecting information dependencies (DAG ordering). - **Consumer interface:** Edited article in place. - **Environment:** None. - **Notable internals:** Treats sections as nodes in a DAG; enforces 240-character paragraph maximum. #### `ubiquitous-language/` - **Files:** `SKILL.md` (92 lines). - **Purpose:** Extract a DDD glossary from the current conversation; write to `UBIQUITOUS_LANGUAGE.md`. - **Consumer interface:** New or updated `UBIQUITOUS_LANGUAGE.md`. - **Environment:** Filesystem write to working directory. - **Output structure:** Multiple grouped tables (Term, Definition, Aliases to avoid), Relationships section with cardinality, Example dialogue (3-5 dev/domain-expert exchanges), Flagged ambiguities. #### `obsidian-vault/` - **Files:** `SKILL.md` (59 lines). - **Purpose:** Search, create, manage notes in an Obsidian vault using wikilinks and index notes. - **Consumer interface:** Reads/writes inside the vault path. - **Environment:** Filesystem at `/mnt/d/Obsidian Vault/AI Research/` by default. - **Notable internals:** Hard-coded vault path. Title Case naming. No folder hierarchy — index notes and `[[wikilinks]]` only. --- ## 5. Helper Script: `block-dangerous-git.sh` This is the only executable artefact in the pack. Because it's tiny and security-critical, it deserves a section of its own. ### 5.1. Contract - **Stdin:** A JSON object from Claude Code's PreToolUse hook framework with `.tool_input.command` containing the candidate Bash command. - **Stdout:** Empty. - **Stderr:** A `BLOCKED` message naming the matched pattern, only when blocking. - **Exit code:** `0` when allowed, `2` when blocked. Exit code 2 is the documented Claude Code convention for "abort the tool call and surface stderr to the model." ### 5.2. Pattern set The patterns are matched with `grep -qE` (extended regex on the command string). Note that the `\.` patterns escape the dot — `git checkout .` matches a literal dot, not a wildcard. | Pattern | Matches | |---|---| | `git push` | Any `git push` invocation, including `--force`. | | `git reset --hard` | The explicit destructive reset. | | `git clean -fd` / `git clean -f` | Force-clean variants. | | `git branch -D` | Force-delete branches. | | `git checkout .` | Discard working-tree changes via checkout. | | `git restore .` | Discard working-tree changes via restore. | | `push --force` | Defensive double-coverage for `git push --force`. | | `reset --hard` | Defensive double-coverage for `git reset --hard`. | ### 5.3. Operational considerations > [!CAUTION] > The script depends on `jq`. If `jq` is missing, the `COMMAND=$(echo ... | jq ...)` line silently produces an empty string, no patterns match, and the hook exits 0 — which means **dangerous commands run unblocked**. Always verify `jq --version` is available on the host before installing this skill. > [!WARNING] > The pattern list is conservative — it does not cover all destructive operations (e.g., `git rebase --abort`, `git reflog expire`, `git stash drop`, `git tag -d`, `git remote remove`). If your threat model needs broader coverage, edit `DANGEROUS_PATTERNS` after install. The skill explicitly invites this customisation in its step 4. > [!NOTE] > Settings file merging is the maintainer's responsibility — the skill instructs the agent to merge into the existing `hooks.PreToolUse` array rather than overwriting. If you have other PreToolUse hooks, expect to see this script's matcher appended alongside them. --- ## 6. Configuration & Customisation The repo itself has no configuration. Configuration lives entirely on the consumer side — the artefacts the skills produce. ### 6.1. Settings.json shape (consumer side) The `git-guardrails-claude-code` skill is the only one that writes to `settings.json`. The expected shape: ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh" } ] } ] } } ``` Global variant uses `~/.claude/hooks/block-dangerous-git.sh` instead of the `$CLAUDE_PROJECT_DIR` form. ### 6.2. Pre-commit configuration (consumer side) `setup-pre-commit` writes three files: | File | Content | |---|---| | `.husky/pre-commit` | `npx lint-staged` + `npm run typecheck` + `npm run test` (substituting the detected package manager and omitting missing scripts). | | `.lintstagedrc` | `{"*": "prettier --ignore-unknown --write"}` — runs Prettier on every staged file, skipping those Prettier can't parse. | | `.prettierrc` (if missing) | `useTabs: false`, `tabWidth: 2`, `printWidth: 80`, `singleQuote: false`, `trailingComma: "es5"`, `semi: true`, `arrowParens: "always"`. | The skill also adds `prepare: "husky"` to `package.json`. ### 6.3. PRD/plan/issue templates (across skills) Several skills embed inline templates. These are not configuration in the traditional sense — they are the contract the skill writes back to GitHub or local files: - `write-a-prd` — Problem Statement, Solution, User Stories (numbered "As a … I want … so that …"), Implementation Decisions, Testing Decisions, Out of Scope, Further Notes. - `prd-to-issues` — Parent PRD, What to build, Acceptance criteria checklist, Blocked by (or "None — can start immediately"), User stories addressed. - `prd-to-plan` — Architectural decisions header (Routes, Schema, Key models), per-phase Title / User stories / What to build / Acceptance criteria. - `request-refactor-plan` — Problem Statement, Solution, Commits, Decision Document, Testing Decisions, Out of Scope, Further Notes. - `triage-issue` — Problem, Root Cause Analysis, TDD Fix Plan, Acceptance Criteria. - `qa` (single) — What happened, What I expected, Steps to reproduce, Additional context. - `qa` (breakdown) — Parent issue, What's wrong, What I expected, Steps to reproduce, Blocked by, Additional context. - `improve-codebase-architecture` — Problem, Proposed Interface, Dependency Strategy, Testing Strategy, Implementation Recommendations. - `github-triage` agent brief — Category, Summary, Current behavior, Desired behavior, Key interfaces, Acceptance criteria, Out of scope. - `github-triage` `.out-of-scope/.md` — H1 concept name, "Why this is out of scope" prose, optional code sample, "Prior requests" list of issue links. - `github-triage` triage notes (needs-info) — "Established so far" + "Need from you (@reporter)". - `ubiquitous-language` — Multiple grouped tables (Term, Definition, Aliases to avoid), Relationships, Example dialogue, Flagged ambiguities. > [!IMPORTANT] > If you fork a skill to change its template, keep the template in sync with the skill's body — the body references specific section names. Renaming a section in the template without updating the body will silently break the skill at runtime. --- ## 7. Testing The pack ships **no automated tests**. Validation is done by: 1. **Manual dogfooding** — the maintainer uses every skill in his own work, including filing issues against this very repo via `github-triage`. 2. **Smoke testing the hook script** — the documented one-liner `echo '{"tool_input":{"command":"git push origin main"}}' | ` verifies blocking. Run after install or any pattern edit. 3. **Issue-driven evolution** — skill bugs surface as community issues. Several closed issues (#11, #16, #17, #18, #19, #24) document the patch trail. ### 7.1. Suggested local validation when authoring a skill Even though the repo has no test runner, you can validate a skill before submitting: - [ ] Description loads cleanly into Claude Code's skill list (no parsing errors in frontmatter). - [ ] Skill can be invoked by its `description` triggers without ambiguity vs other installed skills. - [ ] Walk through the workflow on a small, contrived example. - [ ] Confirm any inline template still parses as valid Markdown when filed as an issue. - [ ] If the skill ships a script, confirm exit codes and stderr behavior with crafted inputs. ### 7.2. Suggested validation for `block-dangerous-git.sh` ```bash # Should be blocked (exit 2) echo '{"tool_input":{"command":"git push origin main"}}' | .claude/hooks/block-dangerous-git.sh; echo "exit=$?" echo '{"tool_input":{"command":"git reset --hard HEAD~5"}}' | .claude/hooks/block-dangerous-git.sh; echo "exit=$?" echo '{"tool_input":{"command":"git clean -fd"}}' | .claude/hooks/block-dangerous-git.sh; echo "exit=$?" # Should be allowed (exit 0) echo '{"tool_input":{"command":"git status"}}' | .claude/hooks/block-dangerous-git.sh; echo "exit=$?" echo '{"tool_input":{"command":"git log --oneline -10"}}' | .claude/hooks/block-dangerous-git.sh; echo "exit=$?" ``` ```text BLOCKED: 'git push origin main' matches dangerous pattern 'git push'. The user has prevented you from doing this. exit=2 BLOCKED: 'git reset --hard HEAD~5' matches dangerous pattern 'git reset --hard'. The user has prevented you from doing this. exit=2 BLOCKED: 'git clean -fd' matches dangerous pattern 'git clean -fd'. The user has prevented you from doing this. exit=2 exit=0 exit=0 ``` > [!NOTE] > The script does not currently match `git rebase --abort`, `git reflog expire`, `git stash drop`, or other destructive but less-common operations. If you extend the pattern list, add a corresponding allow/block test pair to your local validation script. --- ## 8. Maintenance & Operations ### 8.1. Release model The repo has no semver, no changelog, no tags. Skills ship from `main`. Consumers fetch the latest commit by default with `npx skills@latest add ...`. To pin a specific commit, replace the installer's URL behavior — typically by forking the repo at a known commit or vendoring the relevant skill directories into your own repo. > [!IMPORTANT] > Production-critical workflows (e.g., a CI bot that depends on a specific skill's behavior) should pin a commit, not rely on `latest`. Skills evolve in place — a workflow that depends on the v0 description of `qa` may break silently when the description is reworded. ### 8.2. Issue intake The maintainer triages incoming issues with the `github-triage` workflow. See section 4.3 for the state machine. The label set he uses on this repo: | Label | Meaning | |---|---| | `bug` | Something is broken. | | `enhancement` | New feature or improvement. | | `needs-triage` | Maintainer needs to evaluate. | | `needs-info` | Waiting on reporter for more information. | | `ready-for-agent` | Fully specified, agent-suitable. | | `ready-for-human` | Requires human implementation. | | `wontfix` | Will not be actioned. | Open issues at the time of source commit `651eab0`: | # | State | Topic | |---|---|---| | 21 | open | Add `marketplace.json` for plugin marketplace support. | | 38 | open | Q from the community (non-English title). | | 29 | open | Ubiquitous language usage. | | 23 | open | The flow. | | 14 | open | Potential typo in `setup-pre-commit/SKILL.md`. | Closed issues that informed the current design: | # | Resolution | Lesson | |---|---|---| | 6 | Closed (license added) | Repo is now MIT licensed. | | 11 | Closed | Skill prefix standardised. | | 3 | Closed | Native Claude Code marketplace path adopted instead of custom marketplace. | | 16 | Closed | `grill-me` should ask one question at a time, not 10+. | | 17 | Closed | `prd-to-issues` should not put "tests" as their own slice. | | 18 | Closed | `grill-me` should always summarise at the end. | | 19 | Closed | `grill-me` should always use the question tool. | | 24 | Closed | `tdd` should add STUB before RED for new features. | | 31 | Closed | Wrong installation folder bug. | | 33 | Closed | `pop_timeline_green` review item. | | 37 | Closed | Ubiquitous-language agent additions. | ### 8.3. Common operational tasks #### Add a new skill 1. Create `/` at repo root. 2. Author `SKILL.md` per section 2. 3. Add the skill to the appropriate group in `README.md` (Planning & Design, Development, Tooling & Setup, Writing & Knowledge). 4. Open a PR. #### Edit an existing skill 1. Modify `/SKILL.md` (and any companion files). 2. If the description changed, double-check that triggers don't overlap with another skill in the pack. 3. Open a PR. Note the behavioral change in the PR body so consumers who pin understand the impact. #### Add a reference companion to a skill 1. Add `.md` inside the skill's directory. 2. Link from `SKILL.md` using a relative Markdown link. 3. Confirm the install (`npx skills@latest add ...`) copies the file into `.claude/skills//`. #### Publish to consumers There is nothing to publish on the repo side. `npx skills@latest add ...` reads `main` directly. No package.json publish step in this repo. #### Add a new git-guardrails pattern Edit `DANGEROUS_PATTERNS` in `git-guardrails-claude-code/scripts/block-dangerous-git.sh`. Patterns are extended-regex and matched against the full command string. Test with the validation script in section 7.2. ### 8.4. Deprecation strategy The pack has not deprecated a skill at the source commit. If a skill is deprecated in the future, the maintainer's likely path (extrapolated from the issue handling style) is: 1. Mark the skill as deprecated in `README.md` and at the top of its `SKILL.md`. 2. Suggest a replacement skill. 3. Leave the deprecated skill in place for some grace period so existing consumers don't break. 4. Eventually remove — at which point pinned consumers continue to work, and `latest` consumers no longer install the skill. --- ## 9. Security Skills run with the privileges of the host Claude Code process, which inherits the user's privileges. There is no sandbox between a skill's instructions and the user's system. ### 9.1. Threat surface | Surface | Risk | Mitigation | |---|---|---| | `npx skills@latest add ...` | Pulls Markdown from a remote repo at install time. A malicious commit or compromised npm package could ship hostile instructions. | Pin to a reviewed commit in security-sensitive contexts; review installed `SKILL.md` files before invoking. | | `block-dangerous-git.sh` | Runs as the user before every Bash tool call. A compromised script could approve dangerous commands silently. | Read the 25-line script in full; verify with the test in section 7.2 immediately after install. | | `gh issue create` calls | Skills file issues using the user's authenticated `gh` token. A misbehaving skill could file noise or leak content into a public repo. | Only install issue-creating skills in repos where you have considered the consequences. Review the issue body templates in section 6.3. | | Hard-coded paths | `obsidian-vault` writes/reads `/mnt/d/Obsidian Vault/AI Research/`. | Edit the path before invoking; the skill will otherwise fail or, in unlikely edge cases, write to an unintended location if the path coincidentally exists. | > [!WARNING] > The pack does not implement secret redaction. Skills that file issues paste content from the conversation into GitHub. If conversation context contains secrets (API keys, tokens, internal identifiers), they will end up in the issue body. Strip secrets from context before invoking issue-filing skills. > [!CAUTION] > The `git-guardrails-claude-code` hook is a defence-in-depth measure, not a security boundary. It blocks dangerous git commands at Claude Code's PreToolUse stage but does NOT prevent the user from running the same commands directly in a shell. Treat it as a guardrail, not a gate. ### 9.2. Supply chain considerations - The repo is published on GitHub under `mattpocock/skills`. No CDN, no mirror. Tampering would require pushing to that repo. - The `skills` npm package (consumed by `npx`) is a separate supply-chain link — its source is independently maintained and is the primary install vector. Auditing that package is out of scope for this guide but is the more likely vector of compromise. - No third-party dependencies are vendored in this repo. The only external dependency is `jq` (system package) used by the hook script. ### 9.3. Recommended hardening For high-stakes consumer environments: 1. Vendor the relevant skill directories into your own monorepo. Stop relying on `npx skills@latest`. 2. Run `git-guardrails-claude-code` globally (`~/.claude/settings.json`) with an extended `DANGEROUS_PATTERNS` list. 3. Add a wrapper around `gh` that requires confirmation for `gh issue create` in production repos. 4. Periodically re-review installed `SKILL.md` files for drift if you do follow `latest`. --- ## 10. Code Quality and Conventions Although the artefacts are Markdown, the pack has its own style of "code quality." The conventions are observable across every `SKILL.md`. ### 10.1. Pattern: workflow as numbered process Every skill except `grill-me` and `edit-article` (the two shortest) presents its body as a numbered or sub-headed sequence of steps. This makes the workflow scannable and gives the agent a clear ordering to follow. ### 10.2. Pattern: inline template via tagged block Skills that file artefacts embed the template inline using pseudo-XML tags: ```text ## Problem ... ``` The agent recognises the block as a template and follows it verbatim. This keeps the template close to the explanation of when to use it. ### 10.3. Pattern: anti-pattern call-outs Several skills explicitly name the failure mode they exist to prevent: - `tdd` — "DO NOT write all tests first, then all implementation. This is horizontal slicing." - `design-an-interface` — "Don't let sub-agents produce similar designs - enforce radical difference." - `migrate-to-shoehorn` — "Test code only. Never use shoehorn in production code." - `triage-issue` — "Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout." - `qa` — "No file paths or line numbers — these go stale." ### 10.4. Pattern: durability rules A common discipline across the issue-filing skills (especially `triage-issue`, `qa`, `request-refactor-plan`, and `github-triage`'s AGENT-BRIEF): describe behaviors and contracts, not implementation. Forbid file paths and line numbers. The `OUT-OF-SCOPE.md` rule is even stricter — do not reference temporary circumstances ("we're too busy right now"); only durable reasons (project scope, technical constraints, strategic decisions). ### 10.5. Pattern: dogfooding The `github-triage`/`AGENT-BRIEF.md`/`OUT-OF-SCOPE.md` triplet is itself organised the way the AGENT-BRIEF prescribes — durable, behavioral, with explicit out-of-scope sections. The maintainer follows his own conventions on his own repo. ### 10.6. Naming conventions - Directory names: kebab-case, lowercase. - File names: kebab-case Markdown for SKILL companions; UPPERCASE-WITH-DASHES for the github-triage briefs (`AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`); `REFERENCE.md` and `EXAMPLES.md` are uppercase per the `write-a-skill` template. - Heading style: H1 once at the top of each `SKILL.md` (matching the skill's name); H2 for major sections; H3 for sub-steps; H4 rare. ### 10.7. Markdown discipline - Fenced code blocks always have a language tag in the in-body examples. - Tables include header + separator rows. - Inline code uses backticks for filenames, commands, types, and config keys. - Bold for key terms on first use and UI-style labels. --- ## 11. Potential Improvements Recorded community asks and observed gaps that would likely strengthen the pack: | Area | Observation | Source | |---|---|---| | Marketplace integration | Issue #21 (open) requests a `marketplace.json` for plugin marketplace support. Currently no marketplace file exists. | GitHub #21 | | `grill-me` cadence | Issue #16 (closed) reports the skill sometimes asks 10+ questions at once instead of one-by-one. The current 10-line `SKILL.md` is direct ("Ask the questions one at a time") but does not enforce it strongly. | GitHub #16 | | `grill-me` summarisation | Issue #18 (closed) requests an end-of-session summary. Current skill body has no summarisation step. | GitHub #18 | | `prd-to-issues` test slicing | Issue #17 (closed) flags that `prd-to-issues` should not produce "tests" as a standalone slice. Current rules forbid it implicitly via the vertical-slice rule, but the rule could be stated explicitly. | GitHub #17 | | `tdd` STUB step | Issue #24 (closed) requests adding STUB before RED for new features. The current TDD body does not include a STUB phase. | GitHub #24 | | `setup-pre-commit` typo | Issue #14 (open) flags a potential typo in `setup-pre-commit/SKILL.md`. Worth a re-read before next edit. | GitHub #14 | | Install-folder bug | Issue #31 (closed) reports wrong-folder installs. The fix is on the `skills` npm package side, but a defensive note in each skill's verification step would help. | GitHub #31 | | Vault path in `obsidian-vault` | Hard-coded WSL path is brittle for non-WSL users. Could be a frontmatter parameter or environment variable. | Source review | | `block-dangerous-git.sh` `jq` dependency | Hook silently fails open if `jq` is missing. A pre-flight check inside the script (`command -v jq` → fail closed) would harden it. | Source review | | `block-dangerous-git.sh` pattern coverage | Common destructive operations like `git rebase --abort`, `git stash drop`, `git tag -d`, `git remote remove` are not blocked. | Source review | | Skill versioning | Skills evolve in place with no version pin or changelog. Production consumers must vendor or fork. A simple `_version` field in frontmatter would let consumers detect drift. | Source review | | Test harness | A minimal smoke-test script that validates frontmatter and lints links across all SKILL.md files would catch typos and broken cross-references at PR time. | Source review | | Description-overlap detection | As the pack grows, two skills with similar descriptions confuse the agent. A linter that flags similarity above a threshold would help author hygiene. | Source review | --- ## 12. Quick Reference ### 12.1. Install commands (every skill) ```bash npx skills@latest add mattpocock/skills/write-a-prd npx skills@latest add mattpocock/skills/prd-to-plan npx skills@latest add mattpocock/skills/prd-to-issues npx skills@latest add mattpocock/skills/grill-me npx skills@latest add mattpocock/skills/design-an-interface npx skills@latest add mattpocock/skills/request-refactor-plan npx skills@latest add mattpocock/skills/tdd npx skills@latest add mattpocock/skills/triage-issue npx skills@latest add mattpocock/skills/improve-codebase-architecture npx skills@latest add mattpocock/skills/migrate-to-shoehorn npx skills@latest add mattpocock/skills/scaffold-exercises 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 npx skills@latest add mattpocock/skills/qa npx skills@latest add mattpocock/skills/write-a-skill npx skills@latest add mattpocock/skills/edit-article npx skills@latest add mattpocock/skills/ubiquitous-language npx skills@latest add mattpocock/skills/obsidian-vault ``` ### 12.2. Files written by skills (consumer side) | File | Written by | |---|---| | `.husky/pre-commit` | `setup-pre-commit` | | `.lintstagedrc` | `setup-pre-commit` | | `.prettierrc` (if missing) | `setup-pre-commit` | | `.claude/hooks/block-dangerous-git.sh` (or `~/.claude/hooks/...`) | `git-guardrails-claude-code` | | `.claude/settings.json` (or `~/.claude/settings.json`) — `hooks.PreToolUse` entry | `git-guardrails-claude-code` | | `./plans/.md` | `prd-to-plan` | | `./UBIQUITOUS_LANGUAGE.md` | `ubiquitous-language` | | `./.out-of-scope/.md` | `github-triage` (when closing enhancement as wontfix) | | `exercises/XX-section/XX.YY-exercise/{problem,solution,explainer}/readme.md` | `scaffold-exercises` | | Test files (edited in place) | `migrate-to-shoehorn` | | `package.json` (`prepare: "husky"` + dev deps) | `setup-pre-commit` | ### 12.3. GitHub interactions (consumer side) | Skill | Operation | |---|---| | `write-a-prd` | `gh issue create` (PRD) | | `prd-to-issues` | `gh issue create` × N (slices, dependency order) | | `request-refactor-plan` | `gh issue create` (refactor RFC) | | `triage-issue` | `gh issue create` (bug + TDD fix plan) | | `qa` | `gh issue create` × N (single or breakdown) | | `improve-codebase-architecture` | `gh issue create` (refactor RFC) | | `github-triage` | `gh` reads, label updates, comments, closes | | `prd-to-issues` | `gh issue view ` (PRD fetch) | ### 12.4. External tools required | Tool | Required by | |---|---| | `npx` (Node) | All install commands. | | `git` | All skills that read repo state. | | `gh` | All issue-creating skills. | | `jq` | `git-guardrails-claude-code` hook script. | | `pnpm`, `ai-hero-cli` | `scaffold-exercises`. | | `npm` / `pnpm` / `yarn` / `bun` | `setup-pre-commit` (auto-detected). | | `@total-typescript/shoehorn` | Installed by `migrate-to-shoehorn`. | ### 12.5. Per-skill file footprint | Skill | Lines (`SKILL.md`) | Companion files | |---|---:|---| | `design-an-interface` | 94 | — | | `edit-article` | 14 | — | | `git-guardrails-claude-code` | 95 | `scripts/block-dangerous-git.sh` | | `github-triage` | 175 | `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md` | | `grill-me` | 10 | — | | `improve-codebase-architecture` | 76 | `REFERENCE.md` | | `migrate-to-shoehorn` | 118 | — | | `obsidian-vault` | 59 | — | | `prd-to-issues` | 88 | — | | `prd-to-plan` | 107 | — | | `qa` | 130 | — | | `request-refactor-plan` | 68 | — | | `scaffold-exercises` | 106 | — | | `setup-pre-commit` | 91 | — | | `tdd` | 107 | `deep-modules.md`, `interface-design.md`, `mocking.md`, `refactoring.md`, `tests.md` | | `triage-issue` | 102 | — | | `ubiquitous-language` | 92 | — | | `write-a-prd` | 74 | — | | `write-a-skill` | 117 | — | --- _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._