Agent Skills: Addy Osmani’s Production-Grade Pack

A coding agent left on its own defaults will skip the spec, paste code without tests, and call a two-second glance at the diff a review. Agent Skills, Addy Osmani’s open pack of engineering workflows for AI coding agents, treats that behavior as the bug. It ships the process senior engineers actually follow as installable skill files, and it has gathered 100,390 stars since its first commit in February.

View Agent Skills on GitHub

Process you install, not advice you read

The pack holds 25 skills: 24 that cover the development lifecycle, plus a meta-skill called using-agent-skills that routes incoming work to the right workflow. In Claude Code they surface as nine slash commands, one per phase of the loop the README diagrams from DEFINE to SHIP.

What you are doing	Command	The bar it sets
Define what to build	/spec	A PRD exists before any code
Plan the work	/plan	Small, verifiable tasks
Implement	/build	Thin slices, tested and committed one at a time
Prove it works	/test	Tests are proof, not decoration
Set the quality bar	/constraints	Decide once, enforce everywhere
Review before merge	/review	A five-axis check, not a glance
Audit web performance	/webperf	Measure before optimizing
Simplify the code	/code-simplify	Cut complexity, preserve behavior
Ship it	/ship	Staged rollout with a way back

You do not have to remember any of that. Skills also activate on their own: design an API and api-and-interface-design wakes up, build UI and frontend-ui-engineering does. Once a spec exists, /build auto will plan the whole job and then carry it out after a single approval. Every task is still tested and committed separately, and anything that fails or looks risky halts the run instead of getting pushed past.

The judgment inside the workflows is borrowed on purpose. The README credits Google’s published engineering culture, and you can see it: the API skill leans on Hyrum’s Law, testing encodes the Beyonce Rule, simplification guards Chesterton’s Fence, and the git workflow assumes trunk-based development. These are load-bearing ideas from Software Engineering at Google and Google’s engineering practices guide, rewritten as steps an agent follows, not paragraphs it skim-reads.

The excuse tables are the actual product

Plenty of repos collect prompt tips. The design choice that separates this pack is the rationalizations table that ends every skill: a list of the excuses agents produce when they want to skip a step, each with a written rebuttal. In the TDD skill, the excuse “I’ll write tests after the code works” gets a two-word answer: “You won’t.” That is the whole table’s attitude, and it works because the excuses are universal. You have heard every one of them from a model.

Verification closes the loop. Evidence requirements close every skill, and the TDD one states the bar plainly: “seems right” is not done. Done means the tests pass, the build confirms it, and the runtime numbers agree. A skill that cannot produce evidence is not finished, and the pack is structured so the agent cannot declare victory early.

The pack also audits itself. Each skill ships a Red Flags section listing the signs an agent is drifting off the workflow, and the repo grades its own catalog three ways: whether every skill is structurally sound, whether any two of them fight over the same kind of work, and whether a real recorded run of a skill does what that skill promises. The deterministic tiers run in CI, so a contribution that breaks routing gets caught before it merges rather than after you install it.

Two skills push further than the rest. doubt-driven-development questions each meaningful decision from a fresh, hostile context, working five named steps, CLAIM, EXTRACT, DOUBT, RECONCILE, and STOP, and can escalate to a second model when you authorize it. constraint-driven-development sits you down for a short interview about what good means, writes the answers into a CONSTRAINTS.md file, and then watches for the specific failure mode where an agent silences a check or skips a test to force a green run. Both exist because agents optimize for looking finished, and both make looking finished and being finished the same thing.

One install, seventy-plus agents

The fastest path is the open skills CLI from Vercel Labs, which installs the pack into 70-plus agents, Claude Code, Cursor, Codex, Copilot, and Cline among them:

npx skills add addyosmani/agent-skills

Claude Code also has a native route: /plugin marketplace add addyosmani/agent-skills followed by /plugin install agent-skills@addy-agent-skills. Codex ships a plugin integration from v0.122, Gemini CLI installs the skills natively, and the README documents setups for Cursor, Windsurf, OpenCode, Copilot, and more. The skills are plain Markdown, so any agent that reads instruction files can consume them even without an adapter.

Install the whole repo rather than a single skill when you can. The per-skill route has a portability gap that matters more than it looks like it would.

What does a per-skill install leave out?

Grab one skill with npx and you get exactly its folder: the workflow itself runs, but every path pointing at the shared references/ checklists now dangles. The maintainers document that gap in issue 361 instead of hiding it. Your escapes, cheapest last: install the entire pack, clone the repository locally, or manually drop the missing checklist beside the one skill you wanted. Since the whole-repo route is what carries the four review personas and the seven checklists, the single-skill shortcut saves you almost nothing.

Where to start, and when to pass

The repo’s adoption guide splits its advice by project age. A greenfield codebase is told to adopt every phase at once, while an existing one starts with verification and widens from there. The second route is the honest one for most teams. You already have code; you want the agent to stop making it worse before you hand it the spec template.

If you install three skills, make them interview-me, which interrogates an underspecified ask one question at a time until it roughly hits 95 percent confidence, test-driven-development, and code-review-and-quality, whose five-axis review caps changes around 100 lines and labels every finding by severity. Those three change what your agent produces this week. The other 22 can arrive when a real problem calls for them.

Skip the pack, or trim it, when your process is already written down and enforced by machines. If CI blocks untested code, review caps change size, and your constraints live in lint rules, the skills will mostly duplicate what you have. This pack is for the much larger group: teams whose senior-engineer standards exist in everyone’s head and nowhere else.

Whatever you install, you are betting on a live repo. Osmani maintains it with Federico Bartoli and Joan Leon, the issue tracker sits at 116 open items and gets triaged, and a commit landed the morning this review was written. The README also links an honest comparison against obra’s Superpowers and Matt Pocock’s skills, the two collections people weigh it against, so you can pressure-test the fit before adopting.

How is a skill file structured inside?

Every skill follows the same anatomy: YAML frontmatter with a name and a use-when description, then Overview, When to Use, a step-by-step Process, the Rationalizations table, Red Flags, and Verification with its evidence requirements. The SKILL.md file is only the entry point. Shared reference checklists, covering testing, security, performance, accessibility, and observability, load only when a step needs them, which keeps token usage down instead of stuffing the whole pack into every prompt. That progressive disclosure is why a 25-skill install does not bloat your context.

What are the four review personas?

Besides the lifecycle skills, the repo ships four pre-configured reviewer personas you can invoke on demand. code-reviewer applies a Senior Staff Engineer perspective and holds every change to the bar of “would a staff engineer approve this?” test-engineer brings a QA specialist’s test strategy and the Prove-It pattern. security-auditor runs vulnerability detection, threat modeling, and an OWASP assessment. web-performance-auditor does Core Web Vitals audits in Quick or Deep mode under a metric-honesty rule, and backs the /webperf command. One orchestration rule from the reference material keeps them composable: personas do not invoke other personas.

How does it compare with Superpowers and Matt Pocock’s skills?

The repo’s own comparison page maps the three collections honestly, and the shapes really do differ. Agent Skills is the broad one: it walks a feature from definition to launch and puts a human checkpoint between the phases. Superpowers, from Jesse Vincent, is a methodology for long autonomous runs: a strict pipeline of brainstorming, planning, and subagent-driven execution, with git worktree isolation and roughly 14 skills concentrated on the core build cycle. Matt Pocock’s skills, roughly 30 of them, are one expert’s daily Claude Code workflow, centered on a grilling loop that interrogates requirements one question at a time.

The page’s practical guidance: take a feature front to back and Agent Skills covers the ground from specification to security review to launch; hand off a large ambiguous chunk and Superpowers is built for it; want a sharp daily requirements loop and Pocock’s toolkit is the lightest.

A third-party controlled experiment by Om Mishra, same model, repo, and prompt with only the framework changed, found Agent Skills reached code sooner, roughly 8 minutes where Superpowers needed 12, and validated more often, seven passes against five, while Superpowers reasoned harder upfront. One task, one developer, but it frames the choice cleanly: validate broadly as the work advances, or reason hard in front and trust the plan.

Osmani’s bet is that agent reliability is a workflow problem, not a model problem. The skills do not make an agent smarter; they make skipping the work harder, and the excuse tables are aimed at the exact failure you have watched in your own sessions. Install spec-driven-development and code-review-and-quality first, give the rest a real problem to solve, and browse the companion catalog before choosing.