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 <owner>/<repo>/<skill>), 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

                     ┌──────────────────────────────────┐
                     │   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/<skill>/        │
                     │   .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

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

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

<skill-name>/
├── 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/<skill-name>.

2.2. Frontmatter contract

Every SKILL.md begins with a YAML frontmatter block delimited by ---:

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

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 <template-name>...</template-name> pseudo-tags or fenced code blocks.
• Heavy use of checklists (- [ ]) for verification points.

2.4. Description heuristics in this repo

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 <template-name>...</template-name> 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/<feature-name>.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 <vertical-slice-rules> 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):

  #!/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/<concept>.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/<concept>.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.

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:

{
  "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:

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/<concept>.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"}}' | <path-to-script> 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

# 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=$?"

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:

Open issues at the time of source commit 651eab0:

Closed issues that informed the current design:

8.3. Common operational tasks

Add a new skill

1. Create <skill-name>/ 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-name>/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 <topic>.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/<skill-name>/.

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

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:

<issue-template>
## Problem
...
</issue-template>

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:

12. Quick Reference

12.1. Install commands (every skill)

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)

12.3. GitHub interactions (consumer side)

12.4. External tools required

12.5. Per-skill file footprint