addyosmani/agent-skills

Production-grade engineering skills for AI coding agents.

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

9 slash commands that map to the development lifecycle. Each one activates the right skills automatically.

In Claude Code these install as plugin commands. Where a built-in command has the same name, as /review does, use the namespaced form: /agent-skills:review.

Want fewer manual steps once the spec exists? /build auto generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping between tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.

Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

Fastest path — any agent, one command. The open skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):

npx skills add addyosmani/agent-skills            # install all 25 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

Or grab individual skills:

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced

Installing one skill? A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory. The skill still works, but paths to supplementary shared checklists are unavailable. Use a whole-repo integration, clone the repository, or copy the needed checklist into a references/ directory inside the installed skill. This portability gap is tracked in #361.

Prefer a native integration? Pick your tool below.

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

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

agy plugin install https://github.com/addyosmani/agent-skills.git

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

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

gemini skills install ./agent-skills/skills/

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

cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill

Already installed? How you roll the pack out depends on your codebase. The Adoption Guide covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.

The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the using-agent-skills meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.

Pre-configured specialist personas for targeted reviews:

See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.

Quick-reference material that skills pull in when needed:

Every skill follows a consistent anatomy:

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│                                                 │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │                                                                                                
│  Overview         → What this skill does        │
│  When to Use      → Triggering conditions       │
│  Process          → Step-by-step workflow       │
│  Rationalizations → Excuses + rebuttals         │
│  Red Flags        → Signs something's wrong     │
│  Verification     → Evidence requirements       │
└─────────────────────────────────────────────────┘

Key design choices:

• Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
• Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
• Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
• Progressive disclosure. The SKILL.md is the entry point. Supporting references load only when needed, keeping token usage minimal.

The portable core stays in shared directories. Host-specific paths are native discovery conventions, not branding aliases; renaming or merging them would break the tools that scan those exact locations.

Tools without a checked-in adapter directory install or copy the shared skills/ core into their own native location. The Quick Start links the setup guide for each supported host.

AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code.

Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.

Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.

Wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md for an honest, side-by-side look at how the three are shaped differently and when to reach for each — including a link to a controlled head-to-head experiment.

Skills should be specific (actionable steps, not vague advice), verifiable (clear exit criteria with evidence requirements), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent).

See docs/skill-anatomy.md for the format specification, CONTRIBUTING.md for guidelines, and docs/advanced-per-agent-configuration.md for applying model routing, tool restrictions, and other per-agent runtime controls without breaking the portable SKILL.md frontmatter.

agent-skills is built and maintained by:

	Name	GitHub	Role
	Addy Osmani	@addyosmani	Creator
	Federico Bartoli	@federicobartoli	Collaborator
	Joan León	@nucliweb	Collaborator

MIT - use these skills in your projects, teams, and tools.