1. What Agent Skills Is

Agent Skills is a production-grade engineering skill pack for AI coding assistants. It encodes the way senior engineers work — their working methods, quality gates, and best practices across the full Define → Plan → Build → Verify → Review → Ship lifecycle — into Markdown workflows (Skills) that an agent can execute.

Put simply, it does not address whether an agent can write code, but whether an agent will skip the spec, the tests, and the security review — the key steps that make software reliable.

The project is maintained by Addy Osmani and contains 24 Skills, 8 Slash Commands, 4 expert Personas, and 7 reference checklists. It is pure Markdown with no runtime dependencies, and supports mainstream tools including Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Windsurf, and Copilot.

• Project repository: https://github.com/addyosmani/agent-skills
• Skill specification: https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md

2. Why You Need It

AI coding assistants default to the shortest path — if they can edit the code directly they skip the spec, if it “looks right” they skip the tests, if they can ship it first they skip the security review. That is fast during prototyping, but in production code it leaves behind a mountain of technical debt.

Agent Skills takes the approach of structuring a senior engineer’s judgment — when to write a spec, what to test, how to review, when it is acceptable to ship — so that the agent executes step by step instead of skipping on a hunch.

Without Agent Skills, the agent improvises from a generic prompt; with Agent Skills, the agent follows a verifiable workflow where every step has exit criteria and an anti-rationalization table.

3. Comparison: With and Without Agent Skills

3.1 The Same Requirement, Two Paths

Suppose you want the agent to implement a new API endpoint with authentication.

Without Agent Skills:

Verbal requirement description → agent writes code directly → maybe adds a few tests
     → "looks like it runs" so it commits → misses boundary validation, error semantics, security review
     → only after merging do you discover an auth bypass or missing regression tests

With Agent Skills:

/spec → write the PRD (goals, commands, structure, test strategy, boundaries)
     → /plan → break down into verifiable small tasks
     → /build → incremental TDD implementation (RED → GREEN → regression → commit)
     → /test → prove the behavior is correct
     → /review → five-axis code review + security-and-hardening
     → /ship → parallel fan-out across personas, merged into a go/no-go

3.2 Measured Comparison (Controlled Experiment)

Om Mishra ran a controlled comparison on Claude Code: same model (Sonnet 4.6), same repository, same prompt, swapping only the skill framework (Agent Skills vs Superpowers):

On this task Agent Skills showed broader verification depth — the full test suite surfaced a compatibility issue the feature tests did not cover. Superpowers, by contrast, invested more in upfront architectural reasoning, which suits exploratory work with no established pattern.

This is a single experiment, not a benchmark, but it illustrates the core trade-off: disciplined verification with broad coverage vs. autonomous execution weighted toward upfront reasoning.

3.3 When You Can Skip It

4. How It Works

Agent Skills encodes engineering practices as loadable Skill files, activated through two mechanisms: Slash Commands and automatic triggering.

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

4.1 Skill Anatomy

Each Skill is a SKILL.md with a fixed structure:

┌───────────────────────────────────────────────────────────┐
│  Frontmatter (name + description, including trigger conditions) │
│  Overview         → what it does, and why                 │
│  When to Use      → when to use it, when not to           │
│  Core Process     → step-by-step workflow                 │
│  Common Rationalizations → excuses + rebuttals            │
│  Red Flags        → violation signals                     │
│  Verification     → exit criteria + evidence requirements │
└───────────────────────────────────────────────────────────┘

Key design:

• Process, not prose: a Skill is a set of steps for the agent to execute, not reference documentation
• Anti-rationalization: excuses like “I’ll add the tests later” all have a rebuttal in the table
• Verification is non-negotiable: “looks right” is never enough; you need evidence such as test output and build results
• Progressive disclosure: at startup only the name + description enter the context; the full Skill loads on demand, and Supporting files are read on demand as well

4.2 The 24 Skills at a Glance

Grouped by lifecycle:

Skills also trigger automatically by task type — designing an API activates api-and-interface-design, doing UI work activates frontend-ui-engineering.

4.3 Slash Commands

Eight commands correspond to lifecycle entry points and automatically load the matching Skill:

/build auto does not skip verification — every task still goes through the full TDD loop and gets its own commit; it only removes the manual stepping between tasks.

4.4 Expert Personas

The agents/ directory provides four preconfigured review roles that can be combined with Skills:

/ship fans these personas out in parallel and merges them into a go/no-go decision.

4.5 Embedded Engineering Culture

The Skills bake in Google engineering practices — not as abstract slogans but written into the steps:

• API design: Hyrum’s Law, One-Version Rule
• Testing: Beyonce Rule, test pyramid 80/15/5, DAMP over DRY
• Review: change granularity ~100 lines, severity labels (Nit/Optional/FYI)
• Simplification: Chesterton’s Fence, Rule of 500
• Git: Trunk-based development, commit as save point
• CI/CD: Shift Left, feature flags
• Deprecation: Code as liability, compulsory vs advisory deprecation

5. Getting Started

5.1 Claude Code (Recommended)

Marketplace installation:

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

If you get an SSH error, use HTTPS instead:

1
2

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

Local development:

1
2

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

After installation, commands such as /spec, /build, and /review are immediately available.

5.2 Cursor

Option A: Rules directory (recommended)

1
2
3
4

mkdir -p .cursor/rules
cp /path/to/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md
cp /path/to/agent-skills/skills/code-review-and-quality/SKILL.md .cursor/rules/code-review-and-quality.md
cp /path/to/agent-skills/skills/incremental-implementation/SKILL.md .cursor/rules/incremental-implementation.md

Option B: Load on demand

Add frontend-ui-engineering.md when doing UI work and security-and-hardening.md when doing a security review, then remove them when you are done to keep the context under control.

Reference them explicitly when you use them: “Follow the test-driven-development rules for this change.”

5.3 Gemini CLI

1

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

5.4 Antigravity CLI

1

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

5.5 Other Agents

Skills are pure Markdown: just copy SKILL.md into CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, or the conversation’s system prompt. See each tool’s setup documentation for details.

5.6 Minimal Recommended Setup

If you would rather not load all 24 Skills at once, start with these three:

1. spec-driven-development — define what to do
2. test-driven-development — prove it was done right
3. code-review-and-quality — the quality gate before merging

Then load the using-agent-skills meta-skill so the agent routes to the remaining Skills automatically.

6. Command and Skill Mapping

/spec and /plan produce artifacts such as SPEC.md and tasks/plan.md, which serve as a human-and-agent-shared source of truth during development; before merging you can delete them or add them to .gitignore.

7. Usage Advice

1. Run /spec first for non-trivial work — anything over 30 minutes, spanning multiple files, or involving architectural decisions should have a spec
2. Do not load all Skills at once — keep 2–3 resident plus on-demand loading to control the context
3. Reference Skills explicitly — tell the agent “follow the test-driven-development flow”; do not assume it will read the rules
4. Trust the Verification — skipping the checklist is the same as not using the Skill
5. Use a Persona for review — give the agent the contents of agents/code-reviewer.md to catch different problems from another perspective
6. Pick only one primary framework — you can borrow from Matt Pocock’s grill-me or Superpowers’ worktree at the same time, but do not run two meta-skills as routers at once
7. /build auto has gates — it pauses for your confirmation when the spec does not exist, the working tree is dirty, or a step is high risk

A few design principles worth knowing:

• Process over knowledge: a Skill is a workflow, not an encyclopedia
• Evidence over assumption: every Verification step requires provable output
• Human checkpoint: every phase has a human review point; it is not a fully black-box autonomous system
• Multi-tool: the same set of Skills is reused across Claude Code, Cursor, Gemini, and more

8. Comparison with Other Skill Frameworks

How to choose:

• Want full-lifecycle discipline + multi-tool coverage → Agent Skills
• Want long autonomous runs weighted toward upfront reasoning → Superpowers
• Want low-ceremony, sharp day-to-day tools → Matt Pocock’s skills

You can cherry-pick individual Skills, but do not run two routers at the same time.

9. Reference Checklists

The references/ directory provides supplementary material that Skills reference on demand:

10. Summary

Agent Skills turns an AI coding assistant from “an intern who can write code” into “a production-grade partner that delivers by a senior engineer’s process.”

• Comparison: without Skills, the agent often skips spec/tests/security; with Skills, every phase has steps, an anti-rationalization table, and Verification evidence requirements
• Mechanism: 24 Markdown Skills + 8 Slash Commands + 4 Personas, routed by SDLC stage
• Usage: on Claude Code use /plugin install; on Cursor copy into .cursor/rules/; start non-trivial work from /spec

If you already use Cursor or Claude Code, start with the three Skills spec-driven-development + test-driven-development + code-review-and-quality, and run your next non-trivial requirement through /spec → /plan → /build — you will usually feel the difference.