The argument in one line.
The addyosmani/agent-skills repo matters not because all 23 files are novel, but because it proved that packaging senior engineering judgment as portable markdown is itself a distribution strategy -- one that reached 51,000 stars before most tech press noticed.
Read if. Skip if.
- You use Claude Code, Cursor, Codex, or Gemini CLI and want an honest verdict on whether installing this plugin is worth it.
- You are building or customizing your own agent skills or CLAUDE.md and want a reference for what Google-grade engineering habits look like codified.
- You want to understand what doubt-driven development actually means as an agent instruction, not as a philosophy.
- You want a step-by-step tutorial on using any specific skill -- this is a review and audit, not a walkthrough.
- You already follow Addy Osmani closely and have read the repo yourself.
The full version, fast.
Addy Osmani open-sourced his complete AI agent workflow as 23 markdown skill files totaling 253KB. The three skills with genuine teeth are doubt-driven development (a second agent attacks every non-trivial decision with a clean context, max 3 rounds, reviewer never sees the original conclusion), context engineering (a 5-level load hierarchy that forces a structured confusion block when sources conflict instead of letting the agent silently pick), and source-driven development (detect version from lockfile, fetch official docs, cite the URL in code comments -- Stack Overflow and training data are explicitly banned). The whole set loads into Claude Code, Gemini CLI, and opencode from a single shared folder. The honest audit: zero benchmarks, most files are standard practice wearing a lanyard, maybe 4 of 23 have genuinely new ideas. The recommendation even Hacker News agrees on: treat it as reference, steal three skills, adapt them to how you actually work.
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 · Intro
51K stars, growing 781/day, number 1 GitHub trending. Sets up the credibility and velocity of the repo.
02 · Who Is Addy Osmani
14 years Chrome DevTools, Google director, wrote the JavaScript Design Patterns book, latest project is Beyond Vibe Coding.
03 · Inside the Repo
23 skills, 22 covering the full software lifecycle, 1 meta-router skill. 253KB -- Google engineering handbook compressed.
04 · What's a Skill, Anyway
A skill is a folder with a SKILL.md file: name, description, instructions. Open standard -- Codex, Cursor, Copilot, Gemini CLI all load the same format. One-liners load at startup; full files load on match.
05 · Doubt-Driven Development
16KB, the biggest skill. A second agent with clean context attacks every non-trivial decision. Claim/Extract/Doubt/Reconcile/Stop, max 3 rounds. Reviewer never sees the original conclusion.
06 · Context Engineering
Agents mostly fail from wrong context, not low intelligence. Five-level load hierarchy. When sources conflict, agent surfaces a confusion block and asks -- never silently picks.
07 · Source-Driven Development
Detect version from lockfile, fetch official docs, implement, cite URL in code comment. Banned: Stack Overflow, blog posts, training data.
08 · One Repo, Three Agents
Same skills/ folder serves Claude Code (545B plugin.json, 7 slash commands), Gemini CLI (mirrored TOML files), opencode (10-byte symlink). AGENTS.md: skills=how, personas=who, commands=when.
09 · The Honest Audit
Zero benchmarks, no with/without comparisons. Git workflow skill triggers on any code change, always. Model can drop any markdown rule. 4 of 23 files have genuinely new ideas.
10 · The Lineage
January: Karpathy fan repo 172K stars (he did not publish it). Feb 3: Pocock 124K. Feb 15: Osmani 51K. Entire genre is 5 months old.
11 · What to Steal
One command installs everything, but the better move is reference not dependency. Steal doubt-driven-development, confusion block, interview-me. Adapt, do not bulk-install.
12 · Outro
A file. A folder. A format. Whose workflow goes viral next?
Lines worth screenshotting.
- Agents mostly fail from wrong context, not low intelligence -- that is the diagnosis the entire context-engineering skill is built on.
- The doubt loop never shows the reviewer your original conclusion, because showing it biases the reviewer toward agreement.
- If you cannot write the claim compactly, you have a vibe, not a decision -- the entry test for the doubt-driven development loop.
- Source-driven development bans Stack Overflow, blog posts, and the model own training data as primary sources.
- Confidence is not evidence -- when an agent cannot verify something, it ships an explicit unverified block instead of bluffing.
- The opencode port of the entire skills folder is a 10-byte symlink; the Claude Code adapter is a 545-byte plugin.json.
- One skills folder loads natively into Claude Code, Gemini CLI, and opencode -- it is an open standard, not a Claude exclusive.
- 23 skills do not flood context because agents only read the one-liner descriptions at startup; full files load on match.
- The repo hit 27K stars before the press noticed, got 2 points on Hacker News in April, then 376 points on the front page in May after a blog post.
- Only 4 of 23 files contain genuinely new ideas; the rest is good engineering practice with a famous name attached.
- The personal-workflow-as-viral-repo genre is five months old: Karpathy (Jan) to Pocock (Feb 3) to Osmani (Feb 15).
- Senior engineering judgment -- the kind absorbed over years of code review -- now ships as a markdown repo you install in one command.
Three skills worth stealing from 23.
The repo has 23 files but genuine novelty lives in roughly four of them -- and the honest audit the video runs is itself the lesson about how to evaluate any viral engineering resource.
- Doubt-driven development forces you to write a compact falsifiable claim before any review loop starts -- a vibe fails the entry test, which is the point.
- The reviewer never sees your original conclusion because showing it biases them toward agreement; clean context is the whole mechanism.
- Context engineering treats agent failures as a context problem, not an intelligence problem -- wrong information loaded at the wrong priority causes most errors developers blame on the model.
- When sources conflict, the right protocol is a structured confusion block that asks the human to resolve it, not a silent pick that buries the ambiguity.
- Source-driven development bans not just Stack Overflow but the model own training data as a primary source -- confidence in memory is not the same as verified, version-specific documentation.
- A single SKILL.md folder can serve Claude Code, Gemini CLI, and opencode simultaneously because the format is an open standard; agent lock-in is a choice, not a constraint.
- Most viral engineering repos are good checklists with a famous name on them -- the test for genuine novelty is whether any idea would be non-obvious to a senior engineer who had not seen it before.
- The personal-workflow-as-GitHub-repo is a five-month-old genre; the distribution insight (markdown as a credibility vehicle) may outlast the specific content of any individual repo.
Terms worth knowing.
- SKILL.md
- A markdown file with a name, one-line description, and detailed instructions that defines a single agent skill. The description is always loaded; the full file loads only when a task matches.
- Doubt-driven development
- An agent pattern where a second agent with a clean context attacks every non-trivial decision in a Claim/Extract/Doubt/Reconcile/Stop loop, capped at three rounds.
- Confusion block
- A structured output format the agent uses when sources conflict, presenting options A/B/C and asking the user to resolve the ambiguity instead of silently choosing.
- Source-driven development
- An agent protocol that requires detecting the exact dependency version from a lockfile, fetching official docs, implementing, and citing the source URL in a code comment. Stack Overflow and training data are banned as primary sources.
- Context engineering
- The discipline of deciding what information to load into an agent context and in what priority order. The skill defines a five-level hierarchy: rules files, specs, relevant source, error output, conversation.
- Hyrum Law
- The observation that with enough users, all observable behaviors of a system will be depended on by somebody, regardless of what the spec says.
- Beyonce rule
- A Google engineering rule: if you liked it, you should have put a test on it. Referenced in the repo to enforce test coverage on any behavior you care about preserving.
Things they pointed at.
Lines you could clip.
“If you cannot write the claim compactly, you have a vibe, not a decision.”
“Confidence is not evidence.”
“Skills are the how. Personas are the who. Commands are the when. Write your judgment once. Run it in any agent.”
“Senior engineering judgment, the thing you used to absorb over years of code review, now ships as a markdown repo.”
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.
A Google director put his entire AI agent workflow on GitHub. Not a blog post, not a talk -- 23 markdown files, 253KB, the kind of thing that hits 51,000 stars before most tech journalists notice the repo exists.
Named ideas worth stealing.
Doubt-Driven Development
- Claim
- Extract
- Doubt
- Reconcile
- Stop
A second agent with a clean context attacks every non-trivial decision. Max 3 rounds. Reviewer never sees original conclusion. Requires a compact falsifiable claim to start.
Context Engineering Hierarchy
- rules files
- specs
- relevant source
- error output
- conversation
Five-level priority order for context loading. Key rule: when sources conflict, surface a structured confusion block and ask -- never silently pick.
Source-Driven Development
- Detect version from lockfile
- Fetch official docs
- Implement
- Cite URL in code comment
Four-step protocol for grounding implementation in verified, version-specific documentation. Bans Stack Overflow, blog posts, and training data as primary sources.
How they asked for the click.
“Drop the repo in the comments, and subscribe if you want it audited.”
Low-pressure ask after the value delivery, framed as a mutual exchange. No merch, no link in bio.
Visual structure at a glance.
