The argument in one line.
Markdown-based agent skills beat large orchestrated frameworks because they eliminate abstraction layers, reduce token overhead, and distribute as standalone files rather than locked-in systems.
Read if. Skip if.
- You use Claude, Cursor, or Codex daily and notice yourself rewriting the same prompts or instructions across projects.
- An engineer or technical founder running solo or in a small team who wants to reduce AI-assisted coding loops without adopting a heavyweight framework.
- You've tried agent frameworks like SpecKit or BMAD and found them too rigid, and you want a fork-and-modify approach instead.
- You work in a large organization with established CI/CD, QA gates, and formal code review processes that don't map to single-file skills.
- You primarily code in languages or domains where Claude and similar models have weak performance—this breakdown assumes LLM-assisted development is viable for your stack.
The full version, fast.
Matt Pocock open-sourced his ~/.claude/skills/ folder and earned 68,000 GitHub stars in 90 days by proving that plain markdown files outperform sprawling agent frameworks like BMAD, SpecKit, and GSD. The method is a curated catalog of single-file skills the agent reads on demand: /grill-me interviews you before any code is written to force alignment, a shared context.md compresses repeated language so the same task costs half the tokens, /tdd enforces vertical slices with one test and one implementation at a time, and /diagnose ranks ten feedback loops from failing test down to manual repro. The lesson for you is to stop renting opaque frameworks, curate forkable single-file skills, and ship an installer because distribution is the real unlock.
Chat with this breakdown — free.
Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.
Create a free account →Where the time goes.
01 · Hook + social proof
Cold open with star count, comparison to Next.js, sets up the core question: why are real engineers abandoning BMAD and SpecKit to copy a folder of text files?
02 · Inside the repo
Walks the folder structure: engineering/, productivity/, personal/, misc/ — each leaf contains a single SKILL.md file. No runtime, no orchestrator.
03 · The vibe coding problem
Names the failure mode: vague request to agent guesses to ships wrong thing to prompt fixing loop. Introduces the repo as a kill-switch for this pattern.
04 · Skill 1: /grill-me
Agent interviews you relentlessly before writing any code. One question at a time. The fix for misalignment is friction applied to the developer, not the agent.
05 · Skill 2: context.md verbosity fix
Shared language file compresses repeated domain context from 28 words to 8. Same bug, same agent, half the tokens. Pocock calls it the single coolest technique in the repo.
06 · Skill 3: /tdd
Bans horizontal slicing (write all tests first). Enforces red-green-refactor one slice at a time. Tests verify actual behavior, not imagined behavior.
07 · Skill 4: /diagnose
Six phases: Reproduce, Minimize, Hypothesize, Instrument, Fix, Regression-Test. Real trick: rank and pick the right feedback loop first. Failing automated test is best.
08 · Framework showdown
Bar chart: SpecKit 93K, GSD 61K, BMAD 46.7K, mattpocock/skills 68.8K. Just markdown beats two of three.
09 · The thesis: skills vs frameworks
Big frameworks own the process. When something breaks you do not know which layer to fix. Skills are single files: read it, fork it, delete it. No lock-in. No magic. The catalog is the artifact.
10 · Distribution move + verdict
Pocock shipped an installer: npx skills@latest add. Distribution as a feature. Skills are the new package.json. Steal his version.
Lines worth screenshotting.
- Matt Pocock's ~/.claude/skills/ folder hit 68,000 GitHub stars in 90 days — more than Next.js accumulated in its first three years — with nothing but markdown files.
- The grill-me skill stops the agent from guessing by forcing it to interview the developer relentlessly until a shared understanding is reached before any code is written.
- A shared language file called context.md can cut token usage in half by replacing verbose descriptions with agreed-upon terms — the same bug described in half the words.
- Vertical slicing — one test, one implementation, one green bar, then repeat — is the correct TDD approach; horizontal slicing writes tests in bulk that verify imagined behavior.
- The diagnose skill's six phases — reproduce, minimize, hypothesize, instrument, fix, regression test — front-load the most important work: building the right feedback loop.
- A failing test is ranked number one on Pocock's ten-way feedback loop list because it catches regressions automatically without requiring a human to reproduce the scenario.
- Individual skills are single files you can read, fork, or delete with no lock-in — large frameworks make it impossible to identify which layer broke when something goes wrong.
- Distribution as a feature: Pocock shipped an installer that picks your skills and wires them into any agent — Claude Code, Codex, or Cursor — which is why the repo spread so fast.
- Skills are the new package.json — the catalog of skills you have curated is itself a portable artifact that defines how you work and can be versioned, shared, and forked.
- The BMAD framework has 12 specialized agents doing product, architecture, UX, dev, QA, and scrum master roles — more complexity than most solo builders will ever need.
- The fix for agent misalignment is applying friction to the developer, not to the agent — grill-me's relentless questioning forces clarity from the human before the agent touches a file.
- Big frameworks own the process; skills own a single decision — and when something breaks, knowing which file to open is the entire difference in debugging speed.
This is the modular skills playbook you are already running.
Pocock proved that a curated folder of markdown skill files, no framework, no runtime, is worth more than any 12-agent system. Joe is already building this.
- Your ~/.claude/skills/ folder IS this pattern. You have mod-watch, goldmine, creator-research, deploy-joeflow. Name it, ship it, give it an installer.
- The /grill-me pattern maps directly to how good client sessions should start. Relentless scoping before any code. Build a JoeFlow equivalent.
- context.md is the LFB Line session prep play: define domain terms once, cut prompt verbosity 50% every session.
- The /diagnose feedback loop ranking (failing test is best, bash-driving a human is last resort) is a direct checklist for any JoeFlow bug triage.
- Distribution as a feature: when you ship MCN+ tool skills, ship an installer command. One npx line beats a README every time.
- Skill catalogs are a pricing anchor. Pocock's is free, yours bundled with MCN+ is a compounding moat.
Terms worth knowing.
- Claude Code skill
- A markdown file stored in a .claude/skills/ directory that gives Claude Code a named, reusable behavior or workflow, invoked with a /slash command.
- Vibe coding
- A development pattern where a developer submits vague prompts, lets the agent guess at intent, and iterates reactively — often leading to misaligned output and wasted tokens.
- context.md
- A shared vocabulary or reference file in a Claude Code project that defines domain-specific terms, reducing the number of tokens needed to describe concepts in every prompt.
- TDD (Test-Driven Development)
- A software development practice where a failing test is written before any implementation code; the developer writes just enough code to make the test pass, then refactors.
- Horizontal slicing
- Writing all tests for a feature upfront in bulk before writing any code — contrasted with vertical slicing, where one test and its implementation are completed before moving to the next.
- Vertical slice (tracer bullet)
- Building one thin, complete feature path — test, implementation, and green bar — before starting the next, ensuring real behavior is verified at each step rather than imagined behavior.
- Red-green-refactor
- The three-step TDD cycle: write a failing test (red), write code to make it pass (green), then clean up the code without breaking the test (refactor).
- Feedback loop
- In debugging, the fastest repeatable mechanism for observing whether a fix changed the behavior — a failing automated test being the gold standard, a manual human verification step being the last resort.
- BMAD
- A Claude Code agent framework that structures work across 12 specialized sub-agents (product, architecture, UX, dev, QA, scrum master, etc.) using a defined methodology and constitution file.
- Agent orchestrator
- Software that coordinates multiple AI sub-agents, routes tasks between them, and manages their outputs — often adding complexity compared to simpler single-file skill approaches.
Things they pointed at.
Lines you could clip.
“Interview me relentlessly until we reach a shared understanding.”
“Same bug, same agent, half the tokens.”
“Build the right feedback loop, and the bug is 90% fixed.”
“Big frameworks own the process. Skills do the opposite.”
“Skills are the new package.json. Start curating yours or someone else will.”
“The fix for misalignment is friction applied to you.”
Word for word.
Don't just watch it. Burn it in.
See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.
The bait, then the rug-pull.
One folder. No runtime. No orchestrator. No twelve-agent hierarchy. Just markdown the agent reads on demand, and 68,000 GitHub stars in ninety days, more than Next.js collected in its first three years. Matt Pocock open-sourced his ~/.claude/skills/ directory and accidentally wrote the thesis statement for a new era of AI-assisted development.
Named ideas worth stealing.
The Skills Pattern
Folder of markdown files, each a SKILL.md. No runtime, no orchestrator. Agent reads on demand. Fork any one, delete any one.
/grill-me
Agent interviews developer relentlessly before writing any code. One question at a time. Kills vibe coding.
context.md shared vocabulary
Domain-specific terms defined once in context.md. Cuts repeated prompt verbosity in half. Same bug, same agent, roughly 50% fewer tokens.
Vertical slice TDD
- Write one failing test
- Make it pass
- Refactor
- Repeat
Bans horizontal slicing. Red-green-refactor per feature slice. Tests verify actual behavior, not imagined behavior.
/diagnose six-phase loop
- Reproduce
- Minimize
- Hypothesize
- Instrument
- Fix
- Regression-Test
Structured bug diagnosis. Build the right feedback loop before anything else. Failing test is best. Bash-driving a human is last resort.
Distribution as a feature
Ship an installer alongside the content. One command picks skills, picks agent, wires them in. Most open-source projects forget this.
How they asked for the click.
“Command on screen. Repos in the description. Skills are the new package dot JSON. Start curating yours or someone else will. Sub for the next one.”
Install command shown visually on screen, repo URL shown, subscribe ask buried at the very end. Extremely clean, non-pushy.
Visual structure at a glance.
