max skills
General building skills for Claude Code — project-agnostic skills for turning ideas into verified code.
Inspired by Matt Pocock's skills, the Ouroboros specification-first workflow, and the Superpowers plugin.
What's inside
| Skill | What it does | |---|---| | grill-me | Interview the user relentlessly about a plan, spec, or ticket. Produces a per-dimension ambiguity report and gate. | | grill-with-docs | Domain-aware grilling — stress-tests a plan against the project's CONTEXT.md glossary and ADRs, sharpens terminology, cross-references the code, and updates those docs inline as decisions land. | | cookoff | Auto-grill a plan, spec, or ticket by running Claude and Codex as interrogator/answerer pairs — relay (iterative) or parallel (two swapped streams merged). User reviews the pre-chewed result instead of sitting through the interview. Requires the openai-codex plugin. | | write-prd | Turn a vague idea into a grounded PRD. Codebase exploration, Socratic interview, grill gate before exit. | | tdd | Test-driven development with red-green-refactor discipline and vertical-slice tracer bullets. Includes "when NOT to TDD" for UI code. | | tech-spec | Turn a PRD into a technical implementation spec. Module decomposition with deep-module emphasis, tracer-bullet sequencing, grill gate. | | verify-before-done | Three-level evidence rubric (Mechanical / Behavioral / Consensus) for proving work is done before claiming it is. Red flag dictionary for false success claims. | | improve-codebase | Architectural review that produces proposals, not commits. Deep-module detection + four-persona pass (Contrarian / Simplifier / Architect / Hacker). | | design-interface | Parallel exploration of UI/UX designs along explicit dimension axes. Spawns multiple distinct design corners to avoid anchoring. | | handoff | Compact the current conversation into a self-contained handoff document in the OS temp dir, so a fresh agent can resume the work — state, decisions, gotchas, next steps, and suggested skills. | | release-plugin | Ship a Claude Code plugin update — detect plugin, bump version, update CHANGELOG, stage surgically, commit, push, merge to default branch via worktree. Encodes the version-bump discipline that makes /plugin update actually land. |
Installation
Standalone (just these general skills)
/plugin marketplace add max4c/skills
/plugin install max@max4c-skillsAs a companion to the Bugbook plugin
/plugin marketplace add max4c/bugbook
/plugin install bugbook@max4c-bugbook
/plugin install max@max4c-bugbookThe max4c/bugbook marketplace bundles both plugins. Installing max alongside bugbook unlocks active spec grilling and ambiguity scoring inside Bugbook's /flow, /prep, and /ticket workflows.
> The install commands use plugin@marketplace-name format. The marketplace names (max4c-skills and max4c-bugbook) come from the name field in each repo's .claude-plugin/marketplace.json or plugin.json.
Composition
These skills compose with each other and with caller plugins:
caller → write-prd → grill-me → ambiguity report → return PRD
↓
(grill-me is reusable as a subroutine)Callers (including bugbook:flow) pre-load context into the conversation, invoke max:write-prd, and post-process the output for persistence. write-prd never reaches into external systems directly — it produces markdown; the caller decides where it goes.
Philosophy
- Composition over duplication. Skills invoke each other rather than reimplementing shared concepts.
- Grounded, not aspirational. Specs and plans are built on actual codebase reading, not memory.
- Evidence before assertions. Nothing is "done" until it's been verified.
- Qualitative scoring over accounting theater. The LLM judges clarity directly; don't launder judgment through arithmetic.
- Active interrogation over passive review. Grill-me pushes on vague claims until they become specific or the user explicitly overrides.
Contributing
This is a personal skill library. Issues and PRs welcome, but the bar for accepting changes is "does this match how I work" rather than "is this a general improvement". If you want a different style, fork it.
License
MIT. See LICENSE.
