From 62f43a18177be6ec82da242e59ffbc490a4c22ea Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 28 Apr 2026 09:42:34 +0100 Subject: [PATCH] Add new skills for TDD, issue management, PRD creation, and productivity tools - Introduced TDD skills including deep modules, interface design, mocking, refactoring, and testing guidelines. - Added skills for breaking plans into GitHub issues and creating PRDs from conversation context. - Implemented productivity skills for scaffolding exercises, setting up pre-commit hooks, and managing notes in Obsidian. - Created a caveman communication mode for concise technical responses and a grilling technique for thorough plan discussions. - Developed a skill for writing new agent skills with structured templates and guidelines. - Included git guardrails to prevent dangerous git commands and a migration guide for using @total-typescript/shoehorn in tests. --- .claude-plugin/plugin.json | 16 ++- CLAUDE.md | 9 ++ README.md | 122 +++++++++--------- skills/deprecated/README.md | 3 + skills/{ => deprecated}/qa/SKILL.md | 0 .../request-refactor-plan/SKILL.md | 0 skills/{ => deprecated}/triage-issue/SKILL.md | 0 .../ubiquitous-language/SKILL.md | 0 skills/engineering/README.md | 3 + skills/{ => engineering}/diagnose/SKILL.md | 0 .../diagnose/scripts/hitl-loop.template.sh | 0 .../domain-model/ADR-FORMAT.md | 0 .../domain-model/CONTEXT-FORMAT.md | 0 .../{ => engineering}/domain-model/SKILL.md | 0 .../github-triage/AGENT-BRIEF.md | 0 .../github-triage/OUT-OF-SCOPE.md | 0 .../{ => engineering}/github-triage/SKILL.md | 0 .../DEEPENING.md | 0 .../INTERFACE-DESIGN.md | 0 .../improve-codebase-architecture/LANGUAGE.md | 0 .../improve-codebase-architecture/SKILL.md | 0 skills/{ => engineering}/tdd/SKILL.md | 0 skills/{ => engineering}/tdd/deep-modules.md | 0 .../{ => engineering}/tdd/interface-design.md | 0 skills/{ => engineering}/tdd/mocking.md | 0 skills/{ => engineering}/tdd/refactoring.md | 0 skills/{ => engineering}/tdd/tests.md | 0 skills/{ => engineering}/to-issues/SKILL.md | 0 skills/{ => engineering}/to-prd/SKILL.md | 0 skills/{ => engineering}/zoom-out/SKILL.md | 0 skills/misc/README.md | 3 + .../git-guardrails-claude-code/SKILL.md | 0 .../scripts/block-dangerous-git.sh | 0 .../{ => misc}/migrate-to-shoehorn/SKILL.md | 0 skills/{ => misc}/scaffold-exercises/SKILL.md | 0 skills/{ => misc}/setup-pre-commit/SKILL.md | 0 skills/personal/README.md | 3 + skills/{ => personal}/edit-article/SKILL.md | 0 skills/{ => personal}/obsidian-vault/SKILL.md | 0 skills/productivity/README.md | 3 + skills/{ => productivity}/caveman/SKILL.md | 0 skills/{ => productivity}/grill-me/SKILL.md | 0 .../{ => productivity}/write-a-skill/SKILL.md | 0 43 files changed, 97 insertions(+), 65 deletions(-) create mode 100644 CLAUDE.md create mode 100644 skills/deprecated/README.md rename skills/{ => deprecated}/qa/SKILL.md (100%) rename skills/{ => deprecated}/request-refactor-plan/SKILL.md (100%) rename skills/{ => deprecated}/triage-issue/SKILL.md (100%) rename skills/{ => deprecated}/ubiquitous-language/SKILL.md (100%) create mode 100644 skills/engineering/README.md rename skills/{ => engineering}/diagnose/SKILL.md (100%) rename skills/{ => engineering}/diagnose/scripts/hitl-loop.template.sh (100%) rename skills/{ => engineering}/domain-model/ADR-FORMAT.md (100%) rename skills/{ => engineering}/domain-model/CONTEXT-FORMAT.md (100%) rename skills/{ => engineering}/domain-model/SKILL.md (100%) rename skills/{ => engineering}/github-triage/AGENT-BRIEF.md (100%) rename skills/{ => engineering}/github-triage/OUT-OF-SCOPE.md (100%) rename skills/{ => engineering}/github-triage/SKILL.md (100%) rename skills/{ => engineering}/improve-codebase-architecture/DEEPENING.md (100%) rename skills/{ => engineering}/improve-codebase-architecture/INTERFACE-DESIGN.md (100%) rename skills/{ => engineering}/improve-codebase-architecture/LANGUAGE.md (100%) rename skills/{ => engineering}/improve-codebase-architecture/SKILL.md (100%) rename skills/{ => engineering}/tdd/SKILL.md (100%) rename skills/{ => engineering}/tdd/deep-modules.md (100%) rename skills/{ => engineering}/tdd/interface-design.md (100%) rename skills/{ => engineering}/tdd/mocking.md (100%) rename skills/{ => engineering}/tdd/refactoring.md (100%) rename skills/{ => engineering}/tdd/tests.md (100%) rename skills/{ => engineering}/to-issues/SKILL.md (100%) rename skills/{ => engineering}/to-prd/SKILL.md (100%) rename skills/{ => engineering}/zoom-out/SKILL.md (100%) create mode 100644 skills/misc/README.md rename skills/{ => misc}/git-guardrails-claude-code/SKILL.md (100%) rename skills/{ => misc}/git-guardrails-claude-code/scripts/block-dangerous-git.sh (100%) rename skills/{ => misc}/migrate-to-shoehorn/SKILL.md (100%) rename skills/{ => misc}/scaffold-exercises/SKILL.md (100%) rename skills/{ => misc}/setup-pre-commit/SKILL.md (100%) create mode 100644 skills/personal/README.md rename skills/{ => personal}/edit-article/SKILL.md (100%) rename skills/{ => personal}/obsidian-vault/SKILL.md (100%) create mode 100644 skills/productivity/README.md rename skills/{ => productivity}/caveman/SKILL.md (100%) rename skills/{ => productivity}/grill-me/SKILL.md (100%) rename skills/{ => productivity}/write-a-skill/SKILL.md (100%) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2d19812..87ea6f6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,20 @@ { "name": "mattpocock-skills", "skills": [ - "./skills/deprecated/design-an-interface" + "./skills/engineering/diagnose", + "./skills/engineering/domain-model", + "./skills/engineering/github-triage", + "./skills/engineering/improve-codebase-architecture", + "./skills/engineering/tdd", + "./skills/engineering/to-issues", + "./skills/engineering/to-prd", + "./skills/engineering/zoom-out", + "./skills/productivity/caveman", + "./skills/productivity/grill-me", + "./skills/productivity/write-a-skill", + "./skills/misc/git-guardrails-claude-code", + "./skills/misc/migrate-to-shoehorn", + "./skills/misc/scaffold-exercises", + "./skills/misc/setup-pre-commit" ] } diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..24a0ca6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,9 @@ +Skills are organized into bucket folders under `skills/`: + +- `engineering/` — daily code work +- `productivity/` — daily non-code workflow tools +- `misc/` — kept around but rarely used +- `personal/` — tied to my own setup, not promoted +- `deprecated/` — no longer used + +Every skill in `engineering/`, `productivity/`, or `misc/` must have a reference in `README.md` and an entry in `.claude-plugin/plugin.json`. Skills in `personal/` and `deprecated/` must not appear in either. diff --git a/README.md b/README.md index 3a3b747..6daba43 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,38 @@ If you want to keep up with changes to these skills, and any new ones I create, [Sign Up To The Newsletter](https://www.aihero.dev/s/skills-newsletter) -## Planning & Design +## Engineering -These skills help you think through problems before writing code. +Skills I use daily for code work. -- **to-prd** — Turn the current conversation context into a PRD and submit it as a GitHub issue. No interview — just synthesizes what you've already discussed. +- **diagnose** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. ``` - npx skills@latest add mattpocock/skills/to-prd + npx skills@latest add mattpocock/skills/diagnose + ``` + +- **domain-model** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. + + ``` + npx skills@latest add mattpocock/skills/domain-model + ``` + +- **github-triage** — Triage GitHub issues through a label-based state machine. + + ``` + npx skills@latest add mattpocock/skills/github-triage + ``` + +- **improve-codebase-architecture** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`. + + ``` + npx skills@latest add mattpocock/skills/improve-codebase-architecture + ``` + +- **tdd** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. + + ``` + npx skills@latest add mattpocock/skills/tdd ``` - **to-issues** — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices. @@ -22,44 +46,48 @@ These skills help you think through problems before writing code. npx skills@latest add mattpocock/skills/to-issues ``` +- **to-prd** — Turn the current conversation context into a PRD and submit it as a GitHub issue. No interview — just synthesizes what you've already discussed. + + ``` + npx skills@latest add mattpocock/skills/to-prd + ``` + +- **zoom-out** — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code. + + ``` + npx skills@latest add mattpocock/skills/zoom-out + ``` + +## Productivity + +General workflow tools, not code-specific. + +- **caveman** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. + + ``` + npx skills@latest add mattpocock/skills/caveman + ``` + - **grill-me** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. ``` npx skills@latest add mattpocock/skills/grill-me ``` -- **design-an-interface** — Generate multiple radically different interface designs for a module using parallel sub-agents. +- **write-a-skill** — Create new skills with proper structure, progressive disclosure, and bundled resources. ``` - npx skills@latest add mattpocock/skills/design-an-interface + npx skills@latest add mattpocock/skills/write-a-skill ``` -- **request-refactor-plan** — Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. +## Misc + +Tools I keep around but rarely use. + +- **git-guardrails-claude-code** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute. ``` - npx skills@latest add mattpocock/skills/request-refactor-plan - ``` - -## Development - -These skills help you write, refactor, and fix code. - -- **tdd** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - - ``` - npx skills@latest add mattpocock/skills/tdd - ``` - -- **triage-issue** — Investigate a bug by exploring the codebase, identify the root cause, and file a GitHub issue with a TDD-based fix plan. - - ``` - npx skills@latest add mattpocock/skills/triage-issue - ``` - -- **improve-codebase-architecture** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`. - - ``` - npx skills@latest add mattpocock/skills/improve-codebase-architecture + npx skills@latest add mattpocock/skills/git-guardrails-claude-code ``` - **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. @@ -74,42 +102,8 @@ These skills help you write, refactor, and fix code. npx skills@latest add mattpocock/skills/scaffold-exercises ``` -## Tooling & Setup - - **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged, Prettier, type checking, and tests. ``` npx skills@latest add mattpocock/skills/setup-pre-commit ``` - -- **git-guardrails-claude-code** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute. - - ``` - npx skills@latest add mattpocock/skills/git-guardrails-claude-code - ``` - -## Writing & Knowledge - -- **write-a-skill** — Create new skills with proper structure, progressive disclosure, and bundled resources. - - ``` - npx skills@latest add mattpocock/skills/write-a-skill - ``` - -- **edit-article** — Edit and improve articles by restructuring sections, improving clarity, and tightening prose. - - ``` - npx skills@latest add mattpocock/skills/edit-article - ``` - -- **ubiquitous-language** — Extract a DDD-style ubiquitous language glossary from the current conversation. - - ``` - npx skills@latest add mattpocock/skills/ubiquitous-language - ``` - -- **obsidian-vault** — Search, create, and manage notes in an Obsidian vault with wikilinks and index notes. - - ``` - npx skills@latest add mattpocock/skills/obsidian-vault - ``` diff --git a/skills/deprecated/README.md b/skills/deprecated/README.md new file mode 100644 index 0000000..206f2bc --- /dev/null +++ b/skills/deprecated/README.md @@ -0,0 +1,3 @@ +# Deprecated + +Skills I no longer use. diff --git a/skills/qa/SKILL.md b/skills/deprecated/qa/SKILL.md similarity index 100% rename from skills/qa/SKILL.md rename to skills/deprecated/qa/SKILL.md diff --git a/skills/request-refactor-plan/SKILL.md b/skills/deprecated/request-refactor-plan/SKILL.md similarity index 100% rename from skills/request-refactor-plan/SKILL.md rename to skills/deprecated/request-refactor-plan/SKILL.md diff --git a/skills/triage-issue/SKILL.md b/skills/deprecated/triage-issue/SKILL.md similarity index 100% rename from skills/triage-issue/SKILL.md rename to skills/deprecated/triage-issue/SKILL.md diff --git a/skills/ubiquitous-language/SKILL.md b/skills/deprecated/ubiquitous-language/SKILL.md similarity index 100% rename from skills/ubiquitous-language/SKILL.md rename to skills/deprecated/ubiquitous-language/SKILL.md diff --git a/skills/engineering/README.md b/skills/engineering/README.md new file mode 100644 index 0000000..af9c04d --- /dev/null +++ b/skills/engineering/README.md @@ -0,0 +1,3 @@ +# Engineering + +Skills I use daily for code work. diff --git a/skills/diagnose/SKILL.md b/skills/engineering/diagnose/SKILL.md similarity index 100% rename from skills/diagnose/SKILL.md rename to skills/engineering/diagnose/SKILL.md diff --git a/skills/diagnose/scripts/hitl-loop.template.sh b/skills/engineering/diagnose/scripts/hitl-loop.template.sh similarity index 100% rename from skills/diagnose/scripts/hitl-loop.template.sh rename to skills/engineering/diagnose/scripts/hitl-loop.template.sh diff --git a/skills/domain-model/ADR-FORMAT.md b/skills/engineering/domain-model/ADR-FORMAT.md similarity index 100% rename from skills/domain-model/ADR-FORMAT.md rename to skills/engineering/domain-model/ADR-FORMAT.md diff --git a/skills/domain-model/CONTEXT-FORMAT.md b/skills/engineering/domain-model/CONTEXT-FORMAT.md similarity index 100% rename from skills/domain-model/CONTEXT-FORMAT.md rename to skills/engineering/domain-model/CONTEXT-FORMAT.md diff --git a/skills/domain-model/SKILL.md b/skills/engineering/domain-model/SKILL.md similarity index 100% rename from skills/domain-model/SKILL.md rename to skills/engineering/domain-model/SKILL.md diff --git a/skills/github-triage/AGENT-BRIEF.md b/skills/engineering/github-triage/AGENT-BRIEF.md similarity index 100% rename from skills/github-triage/AGENT-BRIEF.md rename to skills/engineering/github-triage/AGENT-BRIEF.md diff --git a/skills/github-triage/OUT-OF-SCOPE.md b/skills/engineering/github-triage/OUT-OF-SCOPE.md similarity index 100% rename from skills/github-triage/OUT-OF-SCOPE.md rename to skills/engineering/github-triage/OUT-OF-SCOPE.md diff --git a/skills/github-triage/SKILL.md b/skills/engineering/github-triage/SKILL.md similarity index 100% rename from skills/github-triage/SKILL.md rename to skills/engineering/github-triage/SKILL.md diff --git a/skills/improve-codebase-architecture/DEEPENING.md b/skills/engineering/improve-codebase-architecture/DEEPENING.md similarity index 100% rename from skills/improve-codebase-architecture/DEEPENING.md rename to skills/engineering/improve-codebase-architecture/DEEPENING.md diff --git a/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md similarity index 100% rename from skills/improve-codebase-architecture/INTERFACE-DESIGN.md rename to skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md diff --git a/skills/improve-codebase-architecture/LANGUAGE.md b/skills/engineering/improve-codebase-architecture/LANGUAGE.md similarity index 100% rename from skills/improve-codebase-architecture/LANGUAGE.md rename to skills/engineering/improve-codebase-architecture/LANGUAGE.md diff --git a/skills/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md similarity index 100% rename from skills/improve-codebase-architecture/SKILL.md rename to skills/engineering/improve-codebase-architecture/SKILL.md diff --git a/skills/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md similarity index 100% rename from skills/tdd/SKILL.md rename to skills/engineering/tdd/SKILL.md diff --git a/skills/tdd/deep-modules.md b/skills/engineering/tdd/deep-modules.md similarity index 100% rename from skills/tdd/deep-modules.md rename to skills/engineering/tdd/deep-modules.md diff --git a/skills/tdd/interface-design.md b/skills/engineering/tdd/interface-design.md similarity index 100% rename from skills/tdd/interface-design.md rename to skills/engineering/tdd/interface-design.md diff --git a/skills/tdd/mocking.md b/skills/engineering/tdd/mocking.md similarity index 100% rename from skills/tdd/mocking.md rename to skills/engineering/tdd/mocking.md diff --git a/skills/tdd/refactoring.md b/skills/engineering/tdd/refactoring.md similarity index 100% rename from skills/tdd/refactoring.md rename to skills/engineering/tdd/refactoring.md diff --git a/skills/tdd/tests.md b/skills/engineering/tdd/tests.md similarity index 100% rename from skills/tdd/tests.md rename to skills/engineering/tdd/tests.md diff --git a/skills/to-issues/SKILL.md b/skills/engineering/to-issues/SKILL.md similarity index 100% rename from skills/to-issues/SKILL.md rename to skills/engineering/to-issues/SKILL.md diff --git a/skills/to-prd/SKILL.md b/skills/engineering/to-prd/SKILL.md similarity index 100% rename from skills/to-prd/SKILL.md rename to skills/engineering/to-prd/SKILL.md diff --git a/skills/zoom-out/SKILL.md b/skills/engineering/zoom-out/SKILL.md similarity index 100% rename from skills/zoom-out/SKILL.md rename to skills/engineering/zoom-out/SKILL.md diff --git a/skills/misc/README.md b/skills/misc/README.md new file mode 100644 index 0000000..a01f397 --- /dev/null +++ b/skills/misc/README.md @@ -0,0 +1,3 @@ +# Misc + +Tools I keep around but rarely use. diff --git a/skills/git-guardrails-claude-code/SKILL.md b/skills/misc/git-guardrails-claude-code/SKILL.md similarity index 100% rename from skills/git-guardrails-claude-code/SKILL.md rename to skills/misc/git-guardrails-claude-code/SKILL.md diff --git a/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh b/skills/misc/git-guardrails-claude-code/scripts/block-dangerous-git.sh similarity index 100% rename from skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh rename to skills/misc/git-guardrails-claude-code/scripts/block-dangerous-git.sh diff --git a/skills/migrate-to-shoehorn/SKILL.md b/skills/misc/migrate-to-shoehorn/SKILL.md similarity index 100% rename from skills/migrate-to-shoehorn/SKILL.md rename to skills/misc/migrate-to-shoehorn/SKILL.md diff --git a/skills/scaffold-exercises/SKILL.md b/skills/misc/scaffold-exercises/SKILL.md similarity index 100% rename from skills/scaffold-exercises/SKILL.md rename to skills/misc/scaffold-exercises/SKILL.md diff --git a/skills/setup-pre-commit/SKILL.md b/skills/misc/setup-pre-commit/SKILL.md similarity index 100% rename from skills/setup-pre-commit/SKILL.md rename to skills/misc/setup-pre-commit/SKILL.md diff --git a/skills/personal/README.md b/skills/personal/README.md new file mode 100644 index 0000000..0ce876b --- /dev/null +++ b/skills/personal/README.md @@ -0,0 +1,3 @@ +# Personal + +Skills tied to my own setup, not promoted in the plugin. diff --git a/skills/edit-article/SKILL.md b/skills/personal/edit-article/SKILL.md similarity index 100% rename from skills/edit-article/SKILL.md rename to skills/personal/edit-article/SKILL.md diff --git a/skills/obsidian-vault/SKILL.md b/skills/personal/obsidian-vault/SKILL.md similarity index 100% rename from skills/obsidian-vault/SKILL.md rename to skills/personal/obsidian-vault/SKILL.md diff --git a/skills/productivity/README.md b/skills/productivity/README.md new file mode 100644 index 0000000..83b735f --- /dev/null +++ b/skills/productivity/README.md @@ -0,0 +1,3 @@ +# Productivity + +General workflow tools, not code-specific. diff --git a/skills/caveman/SKILL.md b/skills/productivity/caveman/SKILL.md similarity index 100% rename from skills/caveman/SKILL.md rename to skills/productivity/caveman/SKILL.md diff --git a/skills/grill-me/SKILL.md b/skills/productivity/grill-me/SKILL.md similarity index 100% rename from skills/grill-me/SKILL.md rename to skills/productivity/grill-me/SKILL.md diff --git a/skills/write-a-skill/SKILL.md b/skills/productivity/write-a-skill/SKILL.md similarity index 100% rename from skills/write-a-skill/SKILL.md rename to skills/productivity/write-a-skill/SKILL.md