05:44Bitwise AI · Essay
A Google Director Open-Sourced His Claude Skills, 51K Stars on Github
How Addy Osmani packaged 14 years of Google engineering judgment into 23 markdown files -- and what is actually worth stealing.
June 11thThe 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.
READ IF YOU ARE…
- 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.
SKIP IF…
- 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.
Free for members
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.
00:00 – 00:47
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?
00:47 – 01:01
02 · Inside the repo
Walks the folder structure: engineering/, productivity/, personal/, misc/ — each leaf contains a single SKILL.md file. No runtime, no orchestrator.
01:01 – 01:36
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.
01:36 – 02:10
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.
02:10 – 02:37
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.
02:37 – 03:03
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.
03:03 – 03:34
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.
03:34 – 03:58
08 · Framework showdown
Bar chart: SpecKit 93K, GSD 61K, BMAD 46.7K, mattpocock/skills 68.8K. Just markdown beats two of three.
03:58 – 04:13
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.
04:13 – 04:34
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.
JoeFlow builder lens
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.
03:02toolSpecKit
03:02toolGSD (Get Stuff Done)
03:02toolBMAD
Lines you could clip.
01:36
“Interview me relentlessly until we reach a shared understanding.”
02:10
“Same bug, same agent, half the tokens.”
02:35
“Build the right feedback loop, and the bug is 90% fixed.”
03:34
“Big frameworks own the process. Skills do the opposite.”
04:31
“Skills are the new package.json. Start curating yours or someone else will.”
02:10
“The fix for misalignment is friction applied to you.”
Word for word.
Read-along
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.
metaphoranalogystory
Matt Pocock open sourced his dot claud folder. Just the markdown files he keeps in there. Ninety days later, 68,000 stars.
More than Next. Js got in its first three years. So what's actually in this folder?
And why are real engineers throwing out SpecKit and BMAD to copy it? Here's the whole repo, folder of folders.
Engineering, productivity, personal, misc.
Inside each folder, more folders. Inside those, a single file called skill dot m d.
That's it. No runtime, no orchestrator, no 12 agent hierarchy. Just mark down the agent reads on demand.
68,000 stars for a folder of text files. You know the loop.
You type a vague request. Agent guesses. Agent ships the wrong thing.
You fix the prompt. Agent guesses harder. Pocock has a name for this.
, and the whole repo is built to kill it. Skill number one, slash grill me.
The agent stops being polite. It interviews you about your plan, one question at a time, walks every branch of the decision tree, makes you commit before any code gets written.
Quote from the skill file. Interview me relentlessly until we reach a shared understanding. Pocock's most used skill by his own admission.
The fix for misalignment is friction applied to you. Skill number two solves verbosity.
Before, there's a problem when a lesson inside a section of a course is made real, given a spot in the file system. After, with a shared language file called context dot m d, there's a problem with the materialization cascade.
Same bug, same agent, half the tokens. Pocock calls this the single coolest technique in the repo. He's not wrong.
Skill number three slash TDD. Most people let the agent write all the tests first, then all the code.
Pocock's skill literally says, do not do this. One test, one implementation, one green bar, repeat.
He calls the wrong way, horizontal slicing. Tests written in bulk verify imagined behavior, not actual behavior.
Vertical slices, tracer bullets, red green refactor, boring, old, works.
Skill number four, slash diagnose. Six phases.
Reproduce, minimize, hypothesize, instrument, fix, regression test.
But the real trick is phase one, building a feedback loop. Pocock lists 10 ways, ranked, failing test at the top, driving a human with a bash script at the bottom, last resort.
Quote, build the right feedback loop, and the bug is 90 fixed.
Compare the field. SpecKit, 93,000 stars.
GitHub published, has a constitution file. GSD, get stuff done, 61,000 stars, opinionated framework just for Claude code.
BMAD, 46,000 stars, 12 specialized agents doing product, architecture, UX, dev, QA, scrum master.
Pocock's repo, just markdown, beats two of them already. Here's the thesis.
Big frameworks own the process. They give you 12 agents and a constitution and a methodology. And when something breaks, you don't know which layer to fix.
Skills do the opposite. Each one is a single file. You can read it.
You can fork it. You can delete it. No lock in.
No magic. No Kool Aid. The catalog is the artifact.
And here's the part that explains the star count. Pocock didn't just publish files. He shipped an installer.
One command picks your skills, picks your agent, Claude code, codex, whatever, wires them in, distribution as a feature. Most open source projects forget that part.
Verdict. If you're using Claude code, cursor, or codex, you're already running this pattern badly.
Steel Pocock's version. 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.
The Hook
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.
00:21concept
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.
Steal forAny project using Claude Code, Cursor, or Codex — replace monolithic CLAUDE.md with modular skill files
01:36concept
/grill-me
Agent interviews developer relentlessly before writing any code. One question at a time. Kills vibe coding.
Steal forAny session where the ask is vague
02:13concept
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.
Steal forAny project with domain jargon repeated in every prompt
02:57concept
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.
Steal forAny agent-driven feature build
02:35list
/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.
Steal forAny debugging session
04:08concept
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.
Steal forAny tool or framework Joe ships — bundle an installer, not just files
How they asked for the click.
VERBAL ASK
04:21link
“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.
MENTIONED ON CAMERA
FROM THE DESCRIPTION
Visual structure at a glance.
