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-skills

As a companion to the Bugbook plugin

/plugin marketplace add max4c/bugbook
/plugin install bugbook@max4c-bugbook
/plugin install max@max4c-bugbook

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