addyosmani/agent-skills - Production-Grade Engineering Skills for Coding Agents

addyosmani/agent-skills describes itself as “Production-grade engineering skills for AI coding agents” — 25 Markdown workflow skills that walk an agent through phases of software development, each with steps, verification gates and checklists. It is MIT licensed (“MIT - use these skills in your projects, teams, and tools”), created by Addy Osmani with collaborators Federico Bartoli and Joan León.

What distinguishes it from a skill grab-bag is that it is organised as a lifecycle rather than a toolbox.

The lifecycle is the design

The 24 working skills are grouped by phase, with one meta-skill — using-agent-skills — whose job is to map incoming work to the right one:

Define — interview-me (questions the user one at a time to clarify intent), idea-refine, spec-driven-development, constraint-driven-development (writes a quality bar to CONSTRAINTS.md and enforces it).
Plan — planning-and-task-breakdown, splitting specs into small verifiable tasks.
Build — incremental-implementation, test-driven-development, context-engineering, source-driven-development (grounds framework decisions in official docs, with citations), doubt-driven-development (adversarial review during implementation), frontend-ui-engineering, api-and-interface-design.
Verify — browser-testing-with-devtools (via Chrome DevTools MCP), debugging-and-error-recovery (a five-step triage: reproduce, localize, reduce, fix, guard).
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.

Alongside them come nine slash commands (/spec, /plan, /build, /test, /constraints, /review, /webperf, /code-simplify, /ship) and four agent personas: code-reviewer, test-engineer, security-auditor and web-performance-auditor.

A few of these are more interesting than their names suggest. source-driven-development insisting on citations to official documentation is a direct counter to the most common agent failure — confidently inventing an API. doubt-driven-development and the adversarial review personas are the same instinct applied to decisions rather than facts. And constraint-driven-development writing a quality bar into a file in the repository is the only one that leaves a durable artefact behind.

Putting the skills on disk

The generic route works for any host that reads skills from disk:

npx skills add addyosmani/agent-skills
npx skills add addyosmani/agent-skills --skill code-review-and-quality

Claude Code and Codex have marketplace routes:

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

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

Cursor, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro and Antigravity each have a setup guide under docs/.

The gotcha that will cost you an hour

This one is easy to miss and the README states it plainly: “A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory.”

So the --skill flag — the obvious move if you only want the code-review skill — silently leaves behind the shared checklists those skills refer to. The recommended fix is a whole-repo integration, or copying the needed checklist by hand. If you install one skill and it behaves thinly, this is why.

Several host-specific gaps are documented too:

GitHub Copilot — the lifecycle slash commands “are Claude Code commands and do not appear in Copilot,” so skills must be invoked by name.
Cursor — the repository ships no .cursor/ folder; you sync skills into your own project.
Antigravity — in affected releases legacy command wrappers “are not discoverable,” so call the namespaced skills directly.
SSH — the marketplace clones over SSH, so without keys configured you need an HTTPS workaround.

Who should take it

This suits someone who wants an agent to follow a process rather than improvise one, and who is willing to adopt the author’s opinions about that process — spec first, thin slices, verification gates, ADRs on the way out. If that matches how you already work, it removes a lot of prompt writing. If it does not, 25 skills of someone else’s methodology is a heavy thing to install.

The pragmatic entry point is the whole-repo install plus the meta-skill, then using two or three lifecycle commands on real work before deciding whether the rest earns its place. And do the whole-repo install rather than cherry-picking, at least until you know which skills depend on references/.