Agent Skills Complete Guide: Boost AI Coding Efficiency with Addy Osmani's Open-Source Framework

What Is Agent Skills?

Agent Skills is an open-source framework created by Addy Osmani (a senior engineer on the Google Chrome team and a well-known expert in web performance). Its goal is to provide production-grade engineering skills and best practices for AI coding assistants like Claude Code, Cursor, and Windsurf.

In simple terms, Agent Skills encodes the workflows, quality gates, and best practices that senior software engineers use during development into reusable skill packages. This allows AI agents to maintain consistently high standards at every stage of development, just like experienced engineers do.

Why Do We Need Agent Skills?

Current AI coding assistants (Claude Code, Codex, Gemini CLI, etc.) can generate code, but they often lack systematic engineering thinking:

• ❌ Writing code directly without writing specifications first
• ❌ Implementing too many features at once, with tasks that are too large
• ❌ Lacking awareness of test-driven development
• ❌ Code reviews that are superficial
• ❌ Insufficient verification before deployment

Agent Skills maps the complete development lifecycle through 7 slash commands, each automatically activating the corresponding skill module:

Project Highlights

• 🚀 38,971+ stars on GitHub, with an active community
• 🔧 Supports multiple AI platforms: Claude Code, Cursor, Windsurf, OpenClaw, and more
• 📦 Modular design: Each skill is independently packaged and can be enabled as needed
• 🎯 Automatic triggering: Relevant skills are automatically activated based on context (e.g., api-and-interface-design triggers when designing APIs)
• 🆓 Completely open-source and free: MIT license

Installing Agent Skills

Prerequisites

• Claude Code or another supported AI coding assistant installed
• A GitHub account (for Marketplace installation)

Method 1: Install via Claude Code Marketplace (Recommended)

# Add the plugin
/plugin marketplace add addyosmani/agent-skills

# Install
/plugin install agent-skills@addy-agent-skills

If you encounter SSH errors (Marketplace clones repositories via SSH by default), you can switch to an HTTPS URL instead:

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

Method 2: Local Installation (Suitable for Developer Debugging)

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

# Start Claude Code with the plugin directory specified
claude --plugin-dir /path/to/agent-skills

Method 3: For Cursor Users

For users of the Cursor editor, you can copy any SKILL.md file into the .cursor/rules/ directory:

# Copy all skill files
cp -r agent-skills/skills/* ~/.cursor/rules/

Alternatively, reference the remote repository in Cursor settings.

Method 4: Other AI Assistants

The core of Agent Skills is the Markdown-formatted skill description file (SKILL.md). In theory, any AI coding assistant that supports custom rules can use it:

• Windsurf: Place SKILL.md files in .windsurfrules/
• OpenClaw: Refer to the project's skills/ directory structure
• Custom Agents: Parse SKILL.md and inject it into the system prompt

Core Features in Practice

1. /spec — Write Specs Before Code

This is one of the most important principles of Agent Skills: clarify what you want to build before writing any code.

How to use:

/spec I want to build a REST API that supports user registration, login, and JWT authentication

The AI will generate a structured specification document, including:

• Functional requirements list
• API endpoint design
• Data model definitions
• Rationale for technology stack choices
• Acceptance criteria

Example output snippet:

## API Specification

### Endpoint Design

- POST /api/auth/register
  - Request body: { email, password, name }
  - Response: { userId, token }
  - Errors: 409 (email already exists), 400 (password too weak)

- POST /api/auth/login
  - Request body: { email, password }
  - Response: { token, expiresIn }

### Data Model

User:
  - id: UUID
  - email: string (unique, indexed)
  - password_hash: string (bcrypt)
  - created_at: timestamp

2. /plan — Small, Atomic Tasks

Once you have the specification, don't rush into coding. Use /plan to break down large tasks into small, atomic subtasks. Each task should:

• Be completable within 15–30 minutes
• Have clear inputs and outputs
• Be independently testable

How to use:

/plan Based on the specification above, plan the implementation steps

The AI will generate a task list like this:

## Implementation Plan

### Phase 1: Project Initialization
- [ ] Task 1.1: Initialize Node.js project, install express, jsonwebtoken, bcrypt
- [ ] Task 1.2: Configure ESLint + Prettier
- [ ] Task 1.3: Set up database connection (PostgreSQL + Prisma)

### Phase 2: User Model
- [ ] Task 2.1: Define User Schema
- [ ] Task 2.2: Write unit tests: create user, query user

### Phase 3: Authentication Logic
- [ ] Task 3.1: Implement password hashing utility function
- [ ] Task 3.2: Implement JWT generation and verification
- [ ] Task 3.3: Write integration tests: register → login → verify token
...

3. /build — Incremental Building

This is one of the most powerful commands. /build automatically generates a plan and executes all tasks one by one. You only need to approve the plan once, and then it can run autonomously.

Key design principles: - ✅ Removes the tedious step-by-step manual confirmation - ✅ Retains test-driven development and independent commits for each task - ✅ Automatically pauses on failures or high-risk steps

How to use:

/build Implement the plan above

The AI will: 1. Display the complete plan for your approval 2. Once approved, execute tasks one by one 3. Automatically run tests after each task completes 4. Commit to git after tests pass 5. Pause and wait for human intervention if errors occur

4. /test — Tests Are Proof

Agent Skills emphasizes Test-Driven Development (TDD). Before making any code changes, ensure there are corresponding tests.

How to use:

/test Write tests for the newly added user registration endpoint

The AI will generate: - Unit tests (Jest/Vitest) - Integration tests (Supertest) - Edge case tests (null values, duplicate emails, weak passwords, etc.)

5. /review — Improve Code Health

Use /review for code review before merging. This doesn't just check for bugs; it also focuses on:

• Code readability
• Performance pitfalls
• Security vulnerabilities
• Architectural consistency

How to use:

/review Review the recent PR #42

6. /code-simplify — Clarity Over Cleverness

This skill is specifically for refactoring complex code, following the principle of "clarity over cleverness."

How to use:

/code-simplify Simplify the logic in auth.middleware.js

The AI will: - Extract long functions into smaller ones - Eliminate deeply nested conditional statements - Replace obscure variable names with more intuitive ones - Add necessary comments

7. /ship — Faster and Safer

The final check before deployment. /ship ensures:

• All tests pass
• No uncommitted changes
• CI/CD pipeline is healthy
• Rollback plan is ready

How to use:

/ship Prepare for production deployment

Automatically Triggered Skills

In addition to manually calling slash commands, Agent Skills automatically activates relevant skills based on context:

This means you don't need to memorize all the commands—just describe your task naturally, and Agent Skills will automatically match the appropriate best practices.

Custom Skills

Agent Skills is designed to be modular, so you can create your own skills. Each skill is a SKILL.md file containing:

---
name: my-custom-skill
description: Description of my custom skill
---

## When to Use

Use this skill when the following conditions are met:
- Condition 1
- Condition 2

## Execution Steps

1. Step one
2. Step two
3. ...

## Notes

- Note 1
- Note 2

Simply place the file in the skills/ directory to make it effective.

Comparison with Other Tools

The biggest advantage of Agent Skills is its openness and community ecosystem—anyone can contribute skills, forming a shared library of best practices.

Summary

Agent Skills represents the next evolutionary direction for AI coding assistants: from "can write code" to "knows engineering".

By encoding the experience of senior engineers into reusable skill packages, it transforms AI agents from mere code generators into true engineering partners with systematic thinking.

Recommended reading path:

1. First, read the official documentation to understand the complete list of skills
2. Start with /spec and /plan to cultivate the habit of "think before you code"
3. Try /build to experience the power of automated execution
4. Customize or contribute new skills as needed

For developers using Claude Code, Cursor, or other AI coding assistants, Agent Skills is a productivity multiplier worth investing time in learning.

Related Links:

• Agent Skills GitHub Repository
• Addy Osmani's Personal Website
• Claude Code Official Documentation