Agent-Skills: Google's Open-Source Framework to Make AI Agents Write Production-Grade Code

Introduction

Teams using AI agents for code generation often find that agents take shortcuts — skipping specifications, tests, and security reviews — when not closely supervised. To address this, Google Chrome engineering manager Addy Osmani open-sourced agent-skills , a collection of 25 structured skills that codify senior engineers' production-grade practices into executable workflows for AI agents.

The project has garnered 103k stars on GitHub (github.com/addyosmani/agent-skills) and is designed to work with 70+ AI agents including Claude Code, Cursor, Codex, Copilot, and Cline via the skills CLI from vercel-labs.

Three Key Highlights

Highlight 1: Six-Phase Lifecycle with Nine Slash Commands

The 25 skills (24 lifecycle skills + 1 routing meta-skill) are organized into six phases:

DEFINE – /spec (write specification before code), /constraints (define quality standards once, enforce everywhere)

PLAN – /plan (break into atomic tasks with acceptance criteria)

BUILD – /build (implement one vertical slice at a time; /build auto runs autonomously but still tests per task), plus skills like source-driven-development (require official docs as source with citations) and doubt-driven-development (adversarial review for major decisions)

VERIFY – /test (test-driven proof), /code-simplify REVIEW – /review (five-axis review by code-reviewer persona), plus security, performance, and accessibility personas

SHIP – /ship (faster, safer releases), plus deprecation migration, observability, release checklist

Additional commands: /webperf for Core Web Vitals audit. Skills auto-activate by context (e.g., API design triggers api-and-interface-design, UI work triggers frontend-ui-engineering).

Highlight 2: Anti-Self-Rationalization Design

Each skill includes a Rationalizations table that lists common agent excuses (e.g., "I'll add tests later") and pre-rebuttals them at the skill level. Every skill also defines Red Flags (failure signals) and Verification requirements (evidence: passing tests, build artifacts, or runtime data). The principle: "looks right" is never enough.

Highlight 3: Distilled Google Engineering Culture

The skills embed battle-tested Google practices:

Hyrum's Law in API design: users depend on all observable behaviors

Beyoncé Rule in testing: admired code must have tests to prove it

Test pyramid 80/15/5 ratio (unit/integration/e2e)

Chesterton's Fence in simplification: understand why a fence exists before removing it

Trunk-based development and Shift Left in CI/CD

These are not generic best practices but concrete disciplines from production Google teams.

Skill Anatomy: Process, Not Prose

Each skill follows a fixed skeleton:

Frontmatter – name and trigger conditions

Overview

When to Use

Process – step-by-step workflow with checkpoints and exit criteria

Rationalizations – excuse/rebuttal table

Red Flags

Verification – evidence requirements

Four Key Design Choices

Process, not prose : skills are executable workflows with steps, checkpoints, and exit conditions — not reference documents to read.

Verification non-negotiable : every skill ends with evidence demands — tests pass, build output, or runtime data; one must be provided.

Progressive disclosure : SKILL.md is the entry point; supporting materials load on demand to control token usage.

Persona–skill separation : four expert personas ( code-reviewer five-axis review, test-engineer, security-auditor, web-performance-auditor) dispatched on demand; seven reference checklists (security, performance, accessibility, observability, etc.) available for skills to call.

Skill Distribution Across Phases

Define: 4 skills (including interview-me — asks one question at a time until 95% confidence)

Plan: 1 skill

Build: 7 skills (including source-driven-development and doubt-driven-development)

Verify: 2 skills

Review: 4 skills

Ship: 6 skills (deprecation migration, observability, release checklist)

Meta: 1 routing skill

Installation & Configuration

Quick Start (via skills CLI)

npx skills add addyosmani/agent-skills          # install all 25 skills
npx skills add addyosmani/agent-skills --list   # preview before install
npx skills add addyosmani/agent-skills --skill code-review-and-quality  # install single skill

Native Editor Integrations

Claude Code: /plugin marketplace add addyosmani/agent-skills Codex: codex plugin marketplace add Gemini CLI: gemini skills install Each tool has dedicated setup docs.

Typical Workflow

/spec

→ generates PRD covering goals, architecture, code style, tests, edge cases /plan → breaks into atomic tasks with acceptance criteria /build → implements slice by slice (use /build auto for autonomous execution; still tests per task, stops on failure) /test → red-green-refactor /review → five-axis review /ship → release

Known Pitfall: Single-Skill Install Misses Shared References

Installing a single skill via npx skills add ... --skill <name> copies only skills/<name>/ and omits the repo-level references/ directory containing shared checklists (security, performance, etc.). Tracked in issue #361 (github.com/addyosmani/agent-skills/issues/361). Workaround: install full set or manually copy references/.

Adoption Paths: New Projects vs. Legacy Codebases

The official Adoption Guide prescribes two distinct approaches:

New Projects: Full Lifecycle from Day One

Run /constraints first to write quality standards into CONSTRAINTS.md Every subsequent skill executes against that standard, turning "tribal knowledge" into "automated enforcement everywhere."

Legacy Codebases: Verification-First Incremental Adoption

Start with /test and /review to establish quality gates

Gradually introduce /spec and /constraints No big-bang rewrite required

Expert Personas in CI / Agent Pipelines

The four personas can be embedded in CI or agent workflows: code-reviewer: Staff-engineer standard five-axis review (changes ~100 lines, severity labels Nit/Optional/FYI) security-auditor: OWASP Top 10 defense + threat modeling web-performance-auditor: uses /webperf for Core Web Vitals audit

Applicable Scenarios

Developers using Claude Code / Codex / Cursor for serious engineering : want agent output to be merge-ready and production-grade, not just "runs."

New teams/projects lacking engineering standards : /constraints + spec workflow acts as a lightweight engineering template.

Tech leads incrementally improving legacy codebases : start with /review and /test to erect quality gates without touching architecture.

Pros, Cons & Pitfalls

Crowded space — compare before committing . Overlaps with superpowers (250k+ stars), mattpocock/skills (277k stars), and Spec-Kit. Official comparison doc ( docs/comparison.md) and third-party benchmarks linked; recommend trial install per your workflow, don't chase stars.

It's a prompt methodology, not a code asset . Actual results depend on underlying model capability and execution discipline. Skills can reject "add tests later" excuses but cannot overcome model ceiling.

Personal project, not Google product . Author is Google Chrome EM, but repo is unaffiliated with Google. 103k stars include personal-influence factor; discount that when evaluating.

Practical Gotchas

Claude Code marketplace SSH error : force HTTPS with full URL or run

git config --global url."https://github.com/".insteadOf [email protected]:

once.

Antigravity CLI legacy command wrapper has known compatibility limits; call namespaced skill names directly.

Single-skill install lacks references/ (issue #361); security/performance checklists missing.

Full 25-skill install consumes context — progressive disclosure mitigates, but for smaller models install only core skills: /spec, test-driven-development, code-review-and-quality.

Personal Perspective

Comparing with mattpocock/skills (which the author previously covered): Matt's repo is a personal toolbox made public — he encourages forking and customizing. agent-skills is clearly designed as a team-adoptable product: unified skill skeleton, routing meta, reference checklists, contribution guidelines, verification test cases, and CI. Engineering maturity is a notch higher.

The anti-self-rationalization tables are the most valuable insight: AI laziness is a specification problem, not a capability problem. If you don't pre-rebut excuses, the agent will use them. Encoding rebuttals into the skill — rather than relying on human oversight — is a more pragmatic design than adding ten more features. Also notable is the distinction between documentation and process: many teams' AI guidelines sit unread in Confluence; agent-skills turns standards into mandatory execution steps — a different path to governance adoption.

Caveats: the ceiling remains the underlying model's execution ability; skills can't compensate for poor test design. Long-term consistency and maintenance cost across 25 skills are real concerns. Recommendation: for new projects, start with /spec and /constraints for a week; for existing projects, install /review first and evaluate review quality against your team's bar. Treat it as a customizable standards template, not a one-click senior-engineer magic wand.