Agent Skills: AI Coding Best Practices

Project Overview

Agent Skills is a production-grade library of 20 reusable Markdown-based workflow instructions that encode senior-engineer best practices into AI coding agents, preventing them from cutting corners across the full software development lifecycle.

Project Background & Positioning

Why It Exists

AI coding agents are capable but undisciplined. Left unconstrained, they skip specifications, omit tests, ignore security reviews, and rationalize shortcuts with plausible-sounding excuses. Agent Skills was created by Addy Osmani—a developer advocate with deep roots in Google's engineering culture—to solve this by embedding opinionated, verifiable workflows directly into the agent's instruction layer. The project treats code as a liability, not an asset, and insists that "seems right" is never a substitute for measurable evidence.

How It Differs From Similar Projects

Most prompt libraries are ad-hoc collections of tips. Agent Skills is different in three ways:

Lifecycle coverage — Skills map to every phase: Define → Plan → Build → Verify → Review → Ship, rather than targeting just one stage.
Anti-rationalization guardrails — Each skill explicitly names common shortcuts agents take and provides documented rebuttals, making refusal harder than compliance.
Tool-agnostic portability — Because every skill is plain Markdown, it runs in Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, Kiro IDE, or any agent that accepts a system prompt, without modification.

Functional Categories

📋 Define — Specification Skills · 3 skills
Representative examples: system requirements, API contracts, data model design.
Purpose: Force agents to pin down requirements before a single line of code is written.

🗺 Plan — Architecture & Breakdown Skills · 4 skills
Representative examples: task decomposition, architecture planning, dependency mapping, timeline estimation.
Purpose: Ensure agents produce an auditable plan rather than diving directly into implementation.

🔨 Build — Implementation Skills · 4 skills
Representative examples: incremental delivery, modularity enforcement, code organization, trunk-based branching.
Purpose: Keep agents building in small, verifiable steps that remain mergeable at all times.

✅ Verify — Testing Skills · 4 skills
Representative examples: unit testing, integration testing, test coverage gates, test-pattern reference checklist.
Purpose: Make agents prove functionality with tests rather than assuming correctness.

🔍 Review — Quality Gate Skills · 3 skills
Representative examples: code review, security audit, performance review, accessibility checklist.
Purpose: Apply the same bar a senior engineer would use before approving a merge.

🚀 Ship — Deployment Skills · 2 skills
Representative examples: production readiness checklist, deployment strategy, rollback planning.
Purpose: Ensure agents consider observability, rollback, and on-call impact before pushing to production.

Core Highlights

20 lifecycle-spanning skills in one place — From first spec to production deploy, every phase has at least one dedicated skill with step-by-step procedures and verification gates.

Seven slash commands mapped to workflow stages — /spec, /plan, /build, /test, /review, /code-simplify, and /ship give teams a shared vocabulary for instructing agents, regardless of IDE.

Three specialist agent personas — A Code Reviewer, Test Engineer, and Security Auditor persona ship alongside the skills, letting teams spin up focused agents for dedicated quality work.

Four reference checklists — Standalone, linkable checklists for testing patterns, security practices, performance optimization, and accessibility standards act as lightweight compliance gates.

Engineering-principle anchoring — Skills embed named principles (Hyrum's Law, the Beyonce Rule, Chesterton's Fence) so agents can reason about why a practice exists, not just follow it mechanically.

First-class multi-tool integration — Dedicated config directories (.claude/, .cursor/, .windsurf/, .gemini/, .opencode/) and setup guides for each platform mean zero friction to adopt in any IDE.

Use Cases by Role

General Developers
Use the seven slash commands as a daily workflow driver. Run /spec before starting any feature, /build during implementation, and /review before opening a PR. The skills act as a senior engineer looking over your shoulder without the scheduling overhead.

DevOps / Platform Engineers
Focus on the Ship skills and the production-readiness checklist to ensure AI-generated deployment code considers rollback strategies, feature flags, and observability hooks before any change reaches production.

Data & Research Engineers
Use the Define and Plan skills to enforce clear data-contract and schema documentation before agents begin generating pipeline or transformation code. The test skills help enforce coverage on data-quality assertions.

Product Teams
Use the Spec skill as a requirements-translation layer: feed product briefs into an agent running the spec skill to get structured, developer-ready requirements documents that reduce back-and-forth with engineering.

Quick Start

🔍 How to Find Resources

Browse the skills/ directory in the repository for all 20 .md skill files, agents/ for the three specialist personas, and references/ for the four standalone checklists. The docs/ directory contains per-tool setup guides.

skills/          # 20 lifecycle skills
agents/          # code-reviewer, test-engineer, security-auditor
references/      # testing, security, performance, accessibility
docs/            # setup guides per IDE/tool

🛠 How to Install / Integrate

Option 1 — Claude Code plugin marketplace (recommended)

/plugin marketplace add addyosmani/agent-skills

Option 2 — Local clone for any tool

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# Claude Code — point to local plugin directory
claude --plugin-dir ./

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

Option 3 — Copy individual skills as system prompts

# Use any skill as a system prompt in any agent
cat skills/review.md   # paste into system prompt of your tool

Cursor / Windsurf / Kiro IDE — The .cursor/, .windsurf/, and .opencode/ directories contain ready-to-use configuration files. Follow the per-tool guide in docs/.

🤝 How to Contribute

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# Create a new skill following existing conventions
cp skills/review.md skills/my-skill.md
# Edit my-skill.md — include: goal, steps, verification gates, anti-rationalizations

# Submit a pull request
git checkout -b feat/my-skill
git add skills/my-skill.md
git commit -m "feat: add my-skill for <purpose>"
git push origin feat/my-skill
# Open PR at https://github.com/addyosmani/agent-skills/pulls

Project Structure

agent-skills/
├── skills/                  # 20 lifecycle skill Markdown files
│   ├── spec.md              # Define requirements
│   ├── plan.md              # Break work into tasks
│   ├── build.md             # Incremental implementation
│   ├── test.md              # Verification workflows
│   ├── review.md            # Quality gate before merge
│   ├── code-simplify.md     # Complexity reduction
│   └── ship.md              # Production deploy readiness
├── agents/                  # Specialist agent personas
│   ├── code-reviewer.md
│   ├── test-engineer.md
│   └── security-auditor.md
├── references/              # Standalone quality checklists
│   ├── testing-patterns.md
│   ├── security.md
│   ├── performance.md
│   └── accessibility.md
├── .claude/commands/        # Claude Code slash-command integration
├── .gemini/commands/        # Gemini CLI integration
├── .cursor/                 # Cursor IDE configuration
├── .windsurf/               # Windsurf IDE configuration
├── .opencode/               # Kiro / OpenCode IDE configuration
├── docs/                    # Per-tool setup guides
└── README.md                # Project overview and quick-start

Related Ecosystem

Upstream tools / platforms the skills target directly:

Claude Code (Anthropic) — primary recommended runtime; native plugin marketplace support
Cursor — popular AI-native IDE with .cursor/ config support
Windsurf (Codeium) — AI IDE with .windsurf/ config support
Gemini CLI (Google) — command-line agent with gemini skills install support
GitHub Copilot — system-prompt integration via Markdown
Kiro IDE / OpenCode — via .opencode/ config directory

Complementary projects and concepts:

Google's engineering philosophy (Hyrum's Law, trunk-based development)
OWASP security checklists (referenced in security skill)
WCAG accessibility guidelines (referenced in accessibility checklist)
Any prompt-engineering or meta-prompting framework that layers structured instructions onto LLM agents

License

MIT License


✅ Allowed	Use in personal, open-source, and commercial projects
✅ Allowed	Fork, modify, and redistribute with attribution
✅ Allowed	Bundle skills into proprietary AI products or SaaS tooling
❌ Prohibited	Removing the copyright notice from redistributed copies
ℹ️ Note	No warranty provided; contributors are not liable for production use outcomes

FAQ

Q: Do I need Claude Code specifically, or will any AI coding tool work?
A: Any tool that accepts Markdown as a system prompt will work. All 20 skills are plain .md files. Claude Code is the primary integration with the richest UX (slash commands, plugin marketplace), but Cursor, Windsurf, Gemini CLI, GitHub Copilot, and any generic agent work equally well.

Q: What makes a "skill" different from just pasting a prompt?
A: Each skill is a structured workflow, not a one-shot instruction. It includes an explicit goal, numbered steps with verification gates at each stage, and an "anti-rationalizations" section that anticipates and rebuts the shortcuts agents commonly take. This makes the skill significantly more robust than a simple prompt.

Q: Can I add my team's internal conventions to a skill?
A: Yes — and that is the encouraged workflow. Fork the repo, edit the relevant .md files to include your team's specific standards (e.g., internal testing frameworks, deployment checklists), and point your agents at your fork. The Markdown format was chosen specifically for easy customization.

Q: Does this slow down AI coding agents significantly?
A: The skills add steps, but they prevent the much costlier rework that follows undisciplined generation. The project treats this as a deliberate trade-off: slower initial output, far fewer defects reaching review or production.

Q: How do the three specialist personas differ from the 20 skills?
A: Skills are workflow instructions — they tell an agent how to perform a task. Personas (agents/) configure an agent's identity and priorities for focused work (e.g., always thinking like a security auditor). They are complementary: you can apply the security-audit skill using the security-auditor persona for the most thorough result.

Quick Links

Resource	URL
GitHub Repository	https://github.com/addyosmani/agent-skills
Plugin Marketplace (Claude Code)	`/plugin marketplace add addyosmani/agent-skills`
Issues & Discussions	https://github.com/addyosmani/agent-skills/issues
Releases	https://github.com/addyosmani/agent-skills/releases
Author	https://github.com/addyosmani

Summary

Agent Skills is a rare open-source project that solves a structural problem rather than a feature gap: it makes AI coding agents behave like disciplined senior engineers instead of overconfident juniors. With 25k+ GitHub stars, first-class support for every major AI coding platform, and a MIT license, it is immediately usable by any team already using AI in their development workflow. Developers who want consistent, auditable, production-ready output from their AI coding tools should consider making Agent Skills the first layer of their agent configuration.