12 Lines vs 689 Lines: Comparing the Design Paths of mattpocock/skills and Superpowers

Two AI‑agent skill repositories are compared: mattpocock/skills (12 lines of core skill code, 18 promoted skills) and superpowers (689 lines of skill code, 14 skills). Star counts are ≈160 k vs 250 k, but the analysis focuses on design differences.

Promoted skills and repository layout

Version 1.1.0 of mattpocock/skills defines 18 promoted skills (12 user‑invoked, 6 model‑invoked). Only skills under the engineering/ and productivity/ buckets appear in the top‑level README, .claude-plugin/plugin.json, and documentation. Other buckets ( misc/, personal/, in‑progress/, deprecated/) are not promoted.

Recent refactoring renamed to‑prd → to‑spec, merged to‑issues into to‑tickets, and moved legacy skills to deprecated/. The deprecated/ directory shows the evolution of skills such as design-an-interface → codebase-design → qa → triage → request‑refactor‑plan → improve‑codebase‑architecture → ubiquitous‑language → domain‑modeling.

disable‑model‑invocation constraint

Invocation rules are defined in .agents/invocation.md (18 lines). User‑invoked skills set disable‑model‑invocation: true, preventing automatic model triggering and disallowing calls from other skills. Model‑invoked skills are the default and remain visible to the model. Consequently, user‑invoked skills can only call model‑invoked skills; they cannot call each other, creating a one‑way dependency.

The router ask‑matt ( 76 lines) explains this design: exposing only a small set of skills to the model keeps the context clean and predictable. Users must remember the twelve slash commands (e.g., /grill-with-docs, /handoff, /prototype, …) to invoke user‑invoked skills.

Four foundational pillars

Grilling : Handles the failure mode “Agent didn’t do what I wanted” by asking the developer one question at a time. Inspired by The Pragmatic Programmer .

CONTEXT.md : Mitigates “Agent is too verbose” by building a project‑specific ubiquitous language (from Eric Evans’ DDD). Defines terms such as Issue tracker, Issue, and Triage role.

TDD + Feedback Loop : Addresses “Code doesn’t work” with vertical‑slice testing. Avoids anti‑patterns: implementation‑coupled mocks, tautological assertions, and horizontal slicing.

Deep Modules / Architecture : Solves “Code becomes a mudball” using concepts from Kent Beck and Paul Ousterhout, defining Module, Interface, Depth, Seam (Michael Feathers), Adapter, Leverage, and Locality.

Main workflow: from idea to ship

The authoritative router is the ask‑matt skill. The end‑to‑end flow consists of slash commands chained together, for example:

/grill-with-docs → /handoff → /prototype → /handoff → /to‑spec → /to‑tickets → /implement → /tdd → /code‑review

Key rules:

Only one session may handle a single ticket; user‑invoked skills require live human‑in‑the‑loop (HITL) execution.

The first three steps must stay within a single “smart zone” (~120 k tokens) to preserve context.

Ticket types (research, prototype, grilling, task) determine whether the agent or a human drives the work. code‑review runs two parallel sub‑agents (Standards and Spec) to avoid context pollution, using a Fowler‑style baseline of 12 common code smells.

Meta‑methodology for writing skills

The writing-great-skills skill (83 lines + GLOSSARY.md) defines a vocabulary aimed at predictability:

Leading words : Leverage model‑pretrained terms (e.g., “fog of war”, “tracer bullet”).

Progressive disclosure : Load details on demand rather than in the frontmatter.

Completion criterion : Explicitly state when a skill is finished to avoid premature completion.

Sediment , No‑op , Negation : Default hidden behaviors, intentional no‑ops, and prohibited negative phrasing.

These conventions explain why grilling works in 12 lines (it trusts leading words) while superpowers expands to 689 lines (it enumerates every fallback).

Engineering trade‑off in to‑tickets

For wide refactors, the repository abandons the tracer‑bullet pattern in favor of an “expand‑contract” strategy: create the new form alongside the old, migrate batch‑by‑batch (one ticket per CI run), then remove the legacy code. This avoids meaningless tests when no design decision is involved.

Route comparison

superpowers

assumes the model will be lazy, injecting hooks at every session start and forcing execution, which consumes many tokens. mattpocock/skills assumes the model usually makes correct choices; it provides minimal anchors and relies on the router to handle forgotten commands. The trade‑off is clear: superpowers offers a hands‑off experience at token cost, while mattpocock gives developers fine‑grained control at the expense of remembering twelve slash commands.

Both approaches can be run on the same project to benchmark delivery quality and token efficiency.

Analysis based on mattpocock/skills v1.1.0 source (GitHub: https://github.com/mattpocock/skills ). Star counts are snapshots and may change.