Automation & Workflows · Blog Post

Addy Osmani's Agent Skills: 25 engineering workflows from spec to ship

Coding agents take the shortest path. They skip the spec, skip the tests, and call it done when the code "looks right." Addy Osmani's agent-skills repo packages the workflows a senior engineer would follow at each phase, from the first question to the production rollout, and wires them to nine slash commands so an agent follows them by default.

By Mehadi Hasan 8 min read

What it is

agent-skills describes itself as "production-grade engineering skills for AI coding agents." It is a set of SKILL.md files, each one a step-by-step workflow with checkpoints and exit criteria, organized around six phases of software delivery: Define, Plan, Build, Verify, Review, and Ship.

It is Addy Osmani's personal project, built with collaborators Federico Bartoli and Joan León, and MIT licensed. It is not a Google product. The README does say the skills borrow from Google's published engineering culture, citing Software Engineering at Google and Google's public engineering practices guide. That shows up as named ideas inside the workflows: Hyrum's Law in API design, the Beyonce Rule and a test pyramid in testing, ~100-line change sizing in code review, Chesterton's Fence in simplification, and trunk-based development in the git skill.

The repo was created in February 2026 and had about 118,000 GitHub stars as of November 17, 2026. It is under active development; the Claude Code plugin manifest was at version 0.6.16 when I read it.

What's inside

25 Skills (24 + 1 meta)
9 Slash commands
4 Review personas
7 Reference checklists

The pack has 25 skills: 24 lifecycle skills plus a meta-skill, using-agent-skills, that routes incoming work to the right one. Here is how the 24 split across phases:

  • Define: interview-me, idea-refine, spec-driven-development, constraint-driven-development
  • Plan: planning-and-task-breakdown
  • Build: incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
  • Verify: browser-testing-with-devtools, debugging-and-error-recovery
  • Review: code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
  • Ship: git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch

Around the skills sit four review personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor) and seven reference checklists covering definition of done, testing patterns, security, performance, accessibility, observability, and orchestration patterns. The repo also keeps an evals/ folder with one case file per skill to check that skills trigger and route as intended.

How it works

Every skill follows the same anatomy: frontmatter with a name and a "use when" description, then Overview, When to Use, Process, Rationalizations, Red Flags, and Verification. Two of those sections are what set this pack apart.

Rationalizations is a table of the excuses agents use to skip steps ("I'll add tests later") with a written rebuttal for each. Verification lists the evidence required before the skill counts as done: passing tests, build output, runtime data. "Seems right" never qualifies.

Skills load in two ways. They activate on their own when the work matches (designing an API pulls in api-and-interface-design, building UI pulls in frontend-ui-engineering). Or you call them through a slash command that maps to a phase:

  • /spec: Define what to build. Spec before code.
  • /plan: Break the spec into small, atomic tasks.
  • /build: Implement one slice at a time; /build auto runs the whole plan after one approval.
  • /test: Prove it works. Tests are the proof.
  • /constraints: Set the quality bar once and enforce it everywhere.
  • /review: Review before merge (use /agent-skills:review in Claude Code, where a built-in /review exists).
  • /webperf: Audit web performance. Measure before you optimize.
  • /code-simplify: Simplify the code. Clarity over cleverness.
  • /ship: Run the pre-launch checklist and get a go/no-go decision.

The spec skill is a good example of the gating. It runs Specify, Plan, Tasks, Implement, and a human reviews the output of each phase before the next starts. When one request bundles several separate capabilities, it first proposes a short capability map (modules, dependencies, build order) for you to approve, then writes one spec per module.

The lifecycle, as the README draws it

DEFINE   →  PLAN   →  BUILD   →  VERIFY  →  REVIEW   →  SHIP
/spec       /plan     /build     /test      /review     /ship

/ship is the most involved command. In Claude Code it runs the code-reviewer, security-auditor, and test-engineer personas as parallel subagents, then merges their three reports into one go/no-go decision with a rollback plan. If you have defined your own personas with the same names in .claude/agents/, yours take precedence.

Installation

The fastest route works across agents. It uses the open skills CLI, which the README says installs into 70+ agents including Claude Code, Cursor, Codex, Copilot, and Cline:

Any agent: skills CLI

npx skills add addyosmani/agent-skills

Add --list to browse first, or --skill test-driven-development to pull a single skill. One catch the README flags: a single-skill install copies only that skill's folder, not the shared references/ checklists, so links to those checklists won't resolve.

For Claude Code, the README recommends the plugin marketplace. This is also how you get the slash commands, personas, and hooks:

Claude Code: plugin marketplace

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

If the marketplace step fails with SSH errors, use the full HTTPS URL (https://github.com/addyosmani/agent-skills.git) in the first command instead.

Gemini CLI: native skills

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Codex CLI (v0.122+): plugin

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

The README also has setup guides for Cursor (skills in .cursor/skills/, short policies in .cursor/rules/), GitHub Copilot, Windsurf, OpenCode, Antigravity CLI, Kiro, and Command Code. The skills are plain Markdown, so any agent that accepts instruction files can use them. Note that the phase slash commands are Claude Code and Gemini CLI wrappers; in Copilot you call skills by name instead.

Using it day to day

The intended loop for a new feature is /spec, then /plan, then /build one task at a time. By default /build takes the next pending task, writes a failing test, writes the minimum code to pass it, runs the full suite and the build, commits, and stops. /build auto removes the stops between tasks after you approve the plan once. It still tests and commits each task separately, and pauses on failures or risky steps.

If the request is vague, start with interview-me. It asks one question at a time until it is about 95% confident it knows what you actually want. If nobody has written down a quality bar, /constraints interviews you for thresholds, writes a CONSTRAINTS.md, and watches for agents that silence checks or skip tests to get to green.

For an existing codebase, the repo's adoption guide suggests an incremental, verification-first rollout instead of switching on the full lifecycle on day one. That is sensible advice. The spec skill itself says not to use it for one-line fixes, typos, or changes where the requirement is already clear.

Pricing

Free and MIT licensed. There is no hosted service, paid tier, or account. You pay only for the tokens your coding agent uses to run the workflows. Expect that to go up on small tasks, because gated phases and parallel review personas add model calls.

My take

The strongest thing here is breadth. Most skill packs stop at the inner build loop: plan, TDD, review. This one keeps going into the parts agents usually ignore: security hardening, performance budgets, CI/CD, observability, deprecation, ADRs, and launch checklists. If you want an agent to carry a feature from a vague idea to a staged rollout, few packs cover that whole path in one install.

The anti-rationalization tables are the right idea. An agent that skips tests rarely says "I'm skipping tests." It says "this is a small change" or "I'll add coverage after." Writing those excuses down with rebuttals targets the actual failure, not just the missing step. The per-skill evals also signal that the maintainers check whether the skills route correctly, which most collections don't.

The tradeoffs: 25 skills is a lot of process. On a small change the gates are overhead, and the repo says as much. It also overlaps heavily with Superpowers and Spec Kit. The repo's own comparison doc puts it fairly: agent-skills is broad across the lifecycle with a human checkpoint per phase, while Superpowers is deeper on long autonomous runs. Pick one as your default rather than stacking them, or you'll get competing instructions for the same moment.

Who it suits: engineers and small teams using Claude Code, Gemini CLI, or Codex who want senior-level discipline across the whole lifecycle, and who are happy to review a spec and a plan before code appears. If you mostly want a fast inner loop for quick edits, install a few individual skills with --skill instead of the full pack.

Frequently asked questions

Is this an official Google project?

No. It is Addy Osmani's personal repo, built with collaborators Federico Bartoli and Joan León and released under the MIT license. The README says the skills borrow ideas from Google's published engineering practices, such as Software Engineering at Google, but it is not a Google product.

How many skills and commands does it include?

25 skills: 24 lifecycle skills plus the using-agent-skills meta-skill that routes work to the right one. It also ships 9 slash commands (/spec, /plan, /build, /test, /constraints, /review, /webperf, /code-simplify, /ship), 4 review personas, and 7 reference checklists.

Which agents does it work with?

The README has native install routes for Claude Code (plugin marketplace), Gemini CLI, Codex CLI, Antigravity CLI, and Command Code, plus setup guides for Cursor, GitHub Copilot, Windsurf, OpenCode, and Kiro. npx skills add addyosmani/agent-skills installs into many agents at once. The skills are plain Markdown, so any agent that reads instruction files can use them.

Do I need all 25 skills?

No. You can install single skills with npx skills add addyosmani/agent-skills --skill <name>. A single-skill install copies only that skill folder, not the shared references/ checklists, so links to those checklists will not resolve unless you copy them in yourself.