Agent Skills: Giving AI Coding Agents the Muscle Memory of a Senior Engineer

AI coding assistants can write code fast. What they can’t do reliably is follow a process—write a spec before writing code, add tests before shipping, run security checks before merging. They take the shortest path, and in production, the shortest path is usually the one that breaks.

Agent Skills by Addy Osmani is an open-source project that solves this. It encodes the workflows, quality gates, and best practices that senior engineers use into structured “skills” that AI agents can follow consistently. The pack includes 24 skills covering every phase of the software lifecycle, 8 slash commands mapped to key actions, and 4 specialist personas for targeted reviews.

This guide covers what Agent Skills contains, how to install it across 8 different AI coding tools, and how each component works under the hood. Everything here comes directly from the project’s documentation.

Why AI Agents Need Skills, Not Just Prompts

A prompt tells an agent what to build. A skill tells it how to build it. That’s a meaningful difference.

Agent Skills are not prompt collections. Each one is a structured workflow with steps, checkpoints, and exit criteria—closer to an operations manual than a system prompt. The project draws heavily from Google’s engineering culture, embedding concepts like Hyrum’s Law in API design, the Beyonce Rule in testing, Chesterton’s Fence in code simplification, and Shift Left with feature flags in CI/CD. These aren’t referenced as abstract principles. They’re woven into the step-by-step workflows that agents actually follow.

The Six-Phase Lifecycle and 8 Slash Commands

Agent Skills organizes development into six phases: Define → Plan → Build → Verify → Review → Ship. Each phase maps to a set of skills, and users trigger them through slash commands.

Here are the 8 commands that cover day-to-day development:

Skills also activate automatically based on context. Designing an API triggers api-and-interface-design. Building a UI triggers frontend-ui-engineering. You don’t need to memorize skill names—normal development behavior is the trigger condition.

The /build auto mode deserves special mention. Given a spec, it generates a plan and autonomously implements every task in a single approved pass. You approve the plan once, then it runs. But it doesn’t skip verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps. It removes the friction of human task-switching, not the quality gates.

All 24 Skills Broken Down

The pack contains 24 skills total: 23 lifecycle skills plus one meta-skill (using-agent-skills) that determines which skill applies to a given situation.

Define: Figure Out What You’re Actually Building

Premature coding is the most common failure mode with AI assistants. Three skills address it:

• interview-me — A one-question-at-a-time interview that keeps probing until the agent has ~95% confidence in what the user actually wants. Useful when requirements are vague.
• idea-refine — Alternates between divergent and convergent thinking to turn a rough concept into a concrete proposal.
• spec-driven-development — Produces a PRD covering objectives, commands, structure, code style, testing strategy, and boundaries before any code is written. The starting point for new projects, features, or significant changes.

Plan: Break the Work Down

• planning-and-task-breakdown — Decomposes a spec into small, verifiable tasks with acceptance criteria and dependency ordering. The output is directly actionable.

Build: Start Writing Code

This is the most skill-dense phase, with seven skills:

• incremental-implementation — Thin vertical slices: implement, test, verify, commit. Supports feature flags, safe defaults, and rollback-friendly changes. Use it for anything touching more than one file.
• test-driven-development — Red-Green-Refactor with the test pyramid (80% unit / 15% integration / 5% end-to-end), DAMP over DRY in test code, and the Beyonce Rule: if you change production code without changing tests, you’ve broken the contract.
• context-engineering — Feeds agents the right information at the right time—rules files, context packing, MCP integrations. Activate when switching tasks or when output quality drops.
• source-driven-development — Grounds every framework decision in official documentation: verify sources, cite them, flag anything unverified.
• doubt-driven-development — An adversarial review mechanism. Every non-trivial decision gets examined in a fresh context through a five-step cycle: Claim → Extract → Doubt → Reconcile → Stop. Kicks in for production, security, or irreversible changes.
• frontend-ui-engineering — Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility.
• api-and-interface-design — Contract-first design, Hyrum’s Law, One-Version Rule, error semantics, boundary validation.

Verify: Prove It Actually Works

• browser-testing-with-devtools — Uses Chrome DevTools MCP for live runtime data: DOM inspection, console logs, network traces, performance profiling. For anything that runs in a browser.
• debugging-and-error-recovery — Five-step triage: reproduce, localize, reduce, fix, guard. Includes a stop-the-line rule and safe fallbacks.

Review: Quality Gates Before Merge

• code-review-and-quality — Five-axis review framework. Change sizing targets ~100 lines. Severity labels (Nit / Optional / FYI). Review speed norms. Splitting strategies.
• code-simplification — Chesterton’s Fence (don’t remove something you don’t understand), Rule of 500, reducing complexity while preserving exact behavior.
• security-and-hardening — OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, a three-tier boundary system.
• performance-optimization — Measure-first approach. Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection.

Ship: Deploy With Confidence

• git-workflow-and-versioning — Trunk-based development, atomic commits, ~100-line change sizing, the commit-as-save-point pattern.
• ci-cd-and-automation — Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops.
• deprecation-and-migration — Treats code as a liability. Covers compulsory vs. advisory deprecation, migration patterns, zombie code removal.
• documentation-and-adrs — Architecture Decision Records, API docs, inline documentation standards. Documents the why, not just the what.
• observability-and-instrumentation — Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting. Instrument as you build, not after you ship.
• shipping-and-launch — Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup.

What Each Skill Actually Looks Like

Skills are executable workflows, not prose reference docs. Every skill follows a consistent anatomy:

Frontmatter with name and description. Overview explaining what the skill does. When to Use listing trigger conditions. Process as a step-by-step workflow with checkpoints and exit criteria. Rationalizations—an anti-rationalization table. Red Flags listing warning signs. Verification specifying what evidence is required.

Three design choices stand out.

The anti-rationalization table is the most distinctive part of the system. AI agents, like humans, find reasons to skip steps: “I’ll add tests later,” “this change is too small to test,” “let me get it running first then optimize.” Each skill pre-loads these excuses with specific rebuttals. Tests aren’t decoration you add afterwards—they’re evidence of behavior. Code without tests isn’t “mostly done”—it’s “unproven.”

Verification is non-negotiable. “Looks right” doesn’t count. Every skill ends with evidence requirements: test output, build logs, runtime data. Without evidence, the workflow doesn’t advance.

Progressive disclosure keeps token usage low. The SKILL.md file is the entry point. Supporting references load only when needed, which prevents information overload and keeps costs down for API-based models.

Four Specialist Personas

Beyond the lifecycle skills, Agent Ships includes four pre-configured agent personas, each with a specific review lens:

Personas follow an orchestration rule: personas don’t invoke personas. This prevents cascading delegation chains that get out of hand.

Reference Checklists

Six quick-reference checklists are pulled in by skills as needed:

• Definition of Done — Project-wide quality bar that every change must clear, distinct from per-task acceptance criteria
• Testing Patterns — Test structure, naming, mocking strategies, React/API/E2E examples, anti-patterns
• Security Checklist — Pre-commit checks, authentication, input validation, HTTP headers, CORS, OWASP Top 10
• Performance Checklist — Core Web Vitals targets, frontend/backend checklists, measurement commands
• Accessibility Checklist — Keyboard navigation, screen readers, visual design, ARIA, testing tools
• Observability Checklist — On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gates

Installation and Setup

Agent Skills supports eight AI coding tools. Here’s how to set each one up.

Claude Code (Recommended)

Install through the plugin marketplace:

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

If you hit SSH errors (the marketplace clones repos via SSH), either add your SSH key to GitHub or force HTTPS:

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

For local development:

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

Cursor

Copy any SKILL.md file into .cursor/rules/, or reference the full skills/ directory. Detailed steps are in docs/cursor-setup.md.

Antigravity CLI

Install as a native plugin for skills, sub-agents, and slash commands:

# From a remote repo
agy plugin install https://github.com/addyosmani/agent-skills.git

# From a local clone
git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

Gemini CLI

Install as native skills for auto-discovery, or add to GEMINI.md for persistent context:

# From a remote repo
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

# From a local clone
gemini skills install ./agent-skills/skills/

Other Tools

• Windsurf — Add skill contents to your Windsurf rules configuration (docs/windsurf-setup.md)
• OpenCode — Uses agent-driven skill execution via AGENTS.md and the skill tool (docs/opencode-setup.md)
• GitHub Copilot — Use agent definitions from agents/ as Copilot personas, skill content in .github/copilot-instructions.md (docs/copilot-setup.md)
• Kiro IDE & CLI — Skills go under .kiro/skills/ at project or global level; also supports Agents.md

All skills are plain Markdown files at their core. Any agent that accepts system prompts or instruction files can use them.

Project Structure

agent-skills/
├── skills/                  # 24 skills (23 lifecycle + 1 meta)
│   ├── interview-me/        #   Define
│   ├── idea-refine/         #   Define
│   ├── spec-driven-development/
│   ├── planning-and-task-breakdown/
│   ├── incremental-implementation/
│   ├── context-engineering/
│   ├── source-driven-development/
│   ├── doubt-driven-development/
│   ├── frontend-ui-engineering/
│   ├── test-driven-development/
│   ├── api-and-interface-design/
│   ├── browser-testing-with-devtools/
│   ├── debugging-and-error-recovery/
│   ├── code-review-and-quality/
│   ├── code-simplification/
│   ├── security-and-hardening/
│   ├── performance-optimization/
│   ├── git-workflow-and-versioning/
│   ├── ci-cd-and-automation/
│   ├── deprecation-and-migration/
│   ├── documentation-and-adrs/
│   ├── observability-and-instrumentation/
│   ├── shipping-and-launch/
│   └── using-agent-skills/
├── agents/                  # 4 specialist personas
├── references/              # 6 supplementary checklists
├── hooks/                   # Session lifecycle hooks
├── .claude/commands/        # 8 slash commands (Claude Code)
├── .gemini/commands/        # 8 slash commands (Gemini CLI)
├── commands/                # 8 slash commands (Antigravity CLI)
├── plugin.json              # Antigravity plugin manifest
└── docs/                    # Setup guides per tool

The Engineering Philosophy Behind It

Agent Skills draws from two specific bodies of work: Google’s Software Engineering at Google and Google’s engineering practices guide. The borrowing is practical, not decorative. Hyrum’s Law is a literal checklist item in the API design skill. The Beyonce Rule is an executable assertion in the TDD skill. Chesterton’s Fence is a concrete rule in the code simplification skill. Shift Left and feature flags are workflow steps in the CI/CD skill.

The project’s own contribution guidelines spell out what makes a good skill: 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).

The project is MIT-licensed. Use it in personal projects, teams, and tools without restrictions.

Quick Summary / Action Checklist

1. Identify which AI coding tool you’re using — Claude Code gets the smoothest install via plugin marketplace, others have their own paths
2. Start any project with /spec — defining requirements comes before writing code, always
3. Use /plan to break the spec into small tasks with acceptance criteria
4. /build for incremental implementation; /build auto if the spec is clear enough for one-shot autonomous execution
5. /test is mandatory, not optional — code without tests is unproven, not “mostly done”
6. Run /review and /webperf before merging
7. /code-simplify for readability issues
8. /ship handles the final deployment prep
9. Call specialist personas as needed — code review, security audit, performance audit, and test strategy each have their own expert
10. All skills are plain Markdown — fork them, modify them, extend them for your team

At a Glance

• What it is: Open-source structured engineering workflows for AI coding assistants
• Scale: 24 skills, 8 slash commands, 4 specialist personas, 6 reference checklists
• Core principles: Process over prompts, anti-rationalization, mandatory verification, progressive disclosure
• Supported tools: Claude Code, Cursor, Antigravity CLI, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro IDE
• Engineering roots: Google’s engineering culture — Hyrum’s Law, Beyonce Rule, Chesterton’s Fence, and more
• License: MIT

Frequently Asked Questions

How is Agent Skills different from writing a good prompt?

A prompt is a one-shot instruction. A skill is a complete workflow with checkpoints, exit criteria, and evidence requirements. The difference is like asking “build me a login page” versus “implement login following TDD with 80%+ test coverage and OWASP-compliant input validation.”

Does it only work with Claude Code?

No. Claude Code has the recommended install path, but the skills work with Cursor, Gemini CLI, Windsurf, Antigravity CLI, OpenCode, GitHub Copilot, and Kiro IDE. Every skill is a plain Markdown file that any agent accepting instructions can use.

Will /build auto skip quality checks?

No. It skips the manual handoff between tasks. Each task is still test-driven, committed individually, and it pauses on failures or risky steps.

Do I need to pick which of the 24 skills to install?

No. They all come as a package. The system activates the right skill based on what you’re doing, and you can override with slash commands at any time.

What’s the anti-rationalization table?

Every skill includes a table of excuses agents commonly use to skip steps (“tests are too slow,” “this change is too small to review”) paired with specific rebuttals. It’s the design feature that most clearly separates Agent Skills from standard prompt engineering.

How does Agent Skills compare to Superpowers or Matt Pocock’s skills?

The project’s docs/comparison.md has a side-by-side comparison with links to a controlled head-to-head experiment. The three projects take different approaches—Agent Skills focuses on lifecycle-wide engineering discipline.

Where do the engineering practices come from?

Primarily Google’s engineering culture, sourced from Software Engineering at Google and Google’s engineering practices guide. Concepts like Hyrum’s Law, the Beyonce Rule, Chesterton’s Fence, and Shift Left are embedded directly into workflows, not just cited.

Can I write my own skills?

Yes. docs/skill-anatomy.md has the format specification and CONTRIBUTING.md has the guidelines. A good skill is specific, verifiable, battle-tested, and minimal.