Introduction

"AI agents are only as good as the workflows they follow."

This is the No.58 article in the "One Open Source Project a Day" series. Today, we are exploring Agent Skills.

If last article's Symphony solved the question of "how to run AI agents at scale," then Agent Skills tackles an even more fundamental problem: how do you make an AI coding assistant genuinely behave like a senior engineer?

This project comes from Addy Osmani—Engineering Director at Google Chrome, legendary figure in frontend engineering, and the author of Learning JavaScript Design Patterns. He captures the state of AI tooling with a deceptively simple observation: AI agents take shortcuts. They skip specs, skip tests, skip security reviews—anything to deliver code that appears to work. Agent Skills exists to change that, encoding 20 carefully designed workflows that enforce the discipline of a senior engineer.

What You Will Learn

• What "structured workflows" are and how they fundamentally change AI agent behavior
• How Anti-Rationalization design eliminates common AI shortcuts before they happen
• How 7 Slash Commands span the full software development lifecycle
• How to install and use Agent Skills in Claude Code, Cursor, and other popular tools
• How Agent Skills compares to other AI coding improvement approaches

Prerequisites

• Daily experience with AI coding tools like Claude Code or Cursor
• Basic familiarity with the software development lifecycle (requirements → design → code → test → deploy)
• No specific programming language background required

Project Background

Project Introduction

Agent Skills is a pure-text (Markdown) collection of engineering workflows. It is not a framework, not an SDK—it is a set of "cognitive protocols" that can be directly loaded into AI tools. When you load these skills into Claude Code or Cursor, the AI no longer dives straight into writing code. Instead, it asks: Do we have a spec? Have we broken down the tasks? Are the tests passing?

The core philosophy is drawn from Google's internal engineering culture: Hyrum's Law (implicit interface dependencies will be exploited), the test pyramid, trunk-based development, and most critically—treating code as a liability, not an asset.

Author/Team Introduction

• Author: Addy Osmani
• Role: Engineering Director, Google Chrome
• Notable Works: Learning JavaScript Design Patterns, core contributor to Lighthouse, foundational author of numerous frontend best practices
• Motivation: While using AI coding tools daily, Addy observed that AI systematically skips "inconvenient but necessary" engineering steps. He responded by encoding years of accumulated engineering discipline into workflows AI agents can directly execute.

Project Data

• ⭐ GitHub Stars: 30,800+
• 🍴 Forks: 3,600+
• 👀 Watchers: 219
• 📝 Commits: 162
• 📄 License: MIT
• 🌐 Repository: addyosmani/agent-skills

Main Features

Core Utility

The core value of Agent Skills is this: converting implicit engineering discipline into explicit, AI-executable step-by-step checklists.

When a typical AI assistant is asked to "fix a bug," it writes code and says "done." An AI loaded with Agent Skills walks through: problem confirmation → root cause analysis → minimal reproduction → fix → test coverage → code review → documentation update—with clear verification criteria at each step.

Use Cases

1. Individual Developers Elevating AI Collaboration Quality

   • Load workflows into Claude Code or Cursor to have the AI help you build a feature end-to-end—not just the main logic while leaving you to clean up the edges.

2. Teams Standardizing AI Usage Norms

   • Place project-level workflow configurations in the team's code repository so every team member's AI assistant follows a consistent engineering standard.

3. Quality Gates for Automated Agent Pipelines

   • Use Agent Skills in CI/CD automation as a review framework for AI-generated code, preventing low-quality code from reaching the main branch.

4. AI Coding Education and Training

   • Learn best practices by observing how an AI handles various engineering challenges when constrained by disciplined workflows.

Quick Start

Method 1: Claude Code Plugin Marketplace (Recommended)

# Execute inside a Claude Code session
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Once installed, use Slash Commands directly:

# Define requirements
/spec I need a user authentication feature with OAuth 2.0 support

# Plan tasks
/plan

# Start implementation
/build

# Verify functionality
/test

# Code review
/review

# Reduce complexity
/code-simplify

# Deploy
/ship

Method 2: Local Clone (Works with All Tools)

# Clone the repository
git clone https://github.com/addyosmani/agent-skills.git

# Load in Claude Code
claude --plugin-dir /path/to/agent-skills

# Load in Gemini CLI
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Method 3: Reference Directly in CLAUDE.md

# CLAUDE.md
Load the following skills for this project:
- skills/build/incremental-implementation
- skills/verify/test-driven-development
- skills/review/code-review-and-quality

Core Characteristics

1. 20 Professional Skills

   • Covering all six development phases (Define, Plan, Build, Verify, Review, Ship), each skill has explicit trigger conditions, execution steps, and verification criteria.

2. 7 Slash Commands

   • /spec, /plan, /build, /test, /review, /code-simplify, /ship—compressing complex workflows into single commands.

3. 3 Expert Agent Personas

   • code-reviewer, test-engineer, security-auditor—allowing AI to examine your code from a specialized professional perspective.

4. Anti-Rationalization Design

   • Every skill file includes a built-in "excuse-and-rebuttal" table that pre-empts common AI shortcuts, e.g., "Requirements aren't confirmed yet, let's just start coding" → "No—first use /spec to lock down the requirements."

5. Verification-First

   • Every step requires concrete evidence upon completion—passing test screenshots, build artifacts, runtime data—not a subjective "it should be fine."

6. Tool-Agnostic

   • The same skill set works across Claude Code, Cursor, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, and Kiro IDE.

7. 4 Reference Checklists

   • Testing patterns, security, performance optimization, accessibility—professional checklists available on demand.

Project Advantages

Why Choose Agent Skills?

• Born from one of the most rigorous engineering cultures (Google Chrome), quality is battle-tested
• 30k+ Stars represent validation from a large real-world user base
• Pure Markdown means zero lock-in, always adjustable, no vendor dependency

Detailed Analysis

1. Skill File Anatomy: What Does a Skill Look Like?

Taking skills/build/incremental-implementation/SKILL.md as an example, every skill file follows a consistent anatomy:

---
name: incremental-implementation
description: Build features in small, testable increments
triggers:
  - "start implementation"
  - "begin coding"
  - "implement feature"
---

## Overview
[Purpose and scope of the skill]

## When to Use
[Specific scenarios that trigger this skill]

## Process
[Step-by-step workflow with explicit deliverables at each step]

### Step 1: Understand the task
- Confirm whether a spec already exists
- Clarify implementation boundaries (in scope / out of scope)
...

## Rationalizations (Excuses & Rebuttals)
| Common Excuse | Why It Doesn't Hold |
|:---|:---|
| "The feature is simple, just write it" | Simplicity is subjective; no spec means no acceptance criteria |
| "I'll add tests afterward" | Test debt almost never gets paid back |

## Red Flags
[Warning signs of workflow deviation, e.g., a single commit over 400 lines]

## Verification
[Proof required to confirm this skill was properly executed]

The elegance of this structure is that it is not documentation written for humans—it is a program written for AI to execute. Every field constrains the AI's behavioral boundaries.

2. The Six-Phase Workflow: A Full Loop from Idea to Production

Define → Plan → Build → Verify → Review → Ship
  ↓        ↓       ↓       ↓        ↓       ↓
/spec   /plan   /build   /test   /review  /ship
  ↓        ↓       ↓       ↓        ↓       ↓
Lock Req  Decomp  Increm  Prove   Quality  Safe
          Tasks   Impl    Tests   Gates    Deploy

Each phase is backed by specific skills:

Define: idea-refine, spec-driven-development

Plan: planning-and-task-breakdown

Build: incremental-implementation, test-driven-development, frontend-ui-engineering, source-driven-development, documentation-as-code, code-as-liability

Verify: browser-testing-with-devtools, debugging-and-error-recovery

Review: code-review-and-quality, security-and-hardening, performance-optimization, change-sizing

Ship: git-workflow-and-versioning, ci-cd-and-automation, shipping-and-launch, trunk-based-development, code-deprecation

3. Agent Personas: Putting AI in a "Professional Uniform"

This is one of the most creative designs in Agent Skills. Rather than having the same AI both write and review code, you make it "become" a pure specialist:

security-auditor persona example:

You are a security auditor. Your ONLY job is to find vulnerabilities.
Do NOT suggest new features. Do NOT improve code quality.
Focus EXCLUSIVELY on:
- Input validation gaps
- Authentication/Authorization flaws
- Injection vulnerabilities (SQL, XSS, SSTI...)
- Exposed secrets or credentials
- Insecure dependencies

When you invoke the security-auditor persona to review code, the AI fully enters the security expert's perspective—it won't be distracted by feature implementation. Applying the Single Responsibility Principle (SRP) at the AI usage level turns out to be surprisingly effective.

4. Anti-Rationalization: The Engineering Discipline Moat

This is one of the project's most distinctive innovations. Every skill file contains an "excuse-rebuttal" table specifically targeting the common avoidance behaviors AI (and humans) exhibit under pressure:

Project Links & Resources

Official Resources

• 🌟 GitHub: https://github.com/addyosmani/agent-skills
• 📚 Skill Anatomy Docs: docs/skill-anatomy.md
• 🤝 Contributing Guide: CONTRIBUTING.md
• 🛠️ Claude Code Guide: docs/claude-code.md

Target Audience

• Developers who use Claude Code, Cursor, or similar AI coding tools daily but find that AI frequently cuts corners
• Technical leads who want to standardize AI usage norms across their team
• Engineers interested in engineering best practices who want to apply Google engineering culture through AI tools
• AI application developers building automated agent pipelines who need quality assurance mechanisms

Summary

Key Takeaways

1. AI defaults to taking shortcuts—Agent Skills enforces engineering discipline through structured workflows
2. Pure Markdown implementation: zero dependencies, tool-agnostic, fully customizable
3. Covers the complete development lifecycle: from requirements spec to code deprecation, with 7 Slash Commands throughout
4. Anti-Rationalization design is the standout innovation—pre-emptively eliminating common AI shortcuts
5. From Google Chrome's Engineering Director: the underlying engineering philosophy has been validated at production scale

One-Line Review

If AI coding tools make you write code 10x faster, Agent Skills ensures what you write is also 10x better.

Find more useful knowledge and interesting products on my Homepage