快速判断
- 01这个 Skill 是干嘛的
- 把 API、界面和软件设计实践封装成供编码 Agent 调用的工程判断。
- 02它能解决什么问题
- 解决 Agent 只关注代码能运行，却忽略 API 质量、用户体验和系统设计的问题。
- 03它适合谁来用
- 适合希望把成熟软件设计原则纳入日常 AI 编码流程的工程师。
预览 · README.md
中文为 README 译文；English 保留 GitHub README 原文。
agent-skills
沉淀 API、界面与软件设计实践，帮助编码 Agent 在实现前做更好的工程判断。
主要能力
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
使用方式
仓库级安装会保留完整目录；本次核验的入口是 skills/api-and-interface-design/SKILL.md。使用前先阅读英文 README 与原始 SKILL.md，并按当前 Agent 的目录规范安装。
适用边界
它是方法与检查框架，不会替代项目自身的架构约束和测试基线。
许可与来源
来源：GitHub 公开仓库。核验许可：MIT。本页是贴近原仓库结构的中文导读，具体参数、依赖和更新记录以英文 README 为准。
Agent Skills
Production-grade engineering skills for AI coding agents.
Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.
<a href="https://trendshift.io/repositories/25200" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25200" alt="addyosmani%2Fagent-skills | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
DEFINE PLAN BUILD VERIFY REVIEW SHIP
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/spec /plan /build /test /review /ship---
Commands
8 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
| What you're doing | Command | Key principle |
|---|---|---|
| Define what to build | /spec | Spec before code |
| Plan how to build it | /plan | Small, atomic tasks |
| Build incrementally | /build | One slice at a time |
| Prove it works | /test | Tests are proof |
| Review before merge | /review | Improve code health |
| Audit web performance | /webperf | Measure before you optimize |
| Simplify the code | /code-simplify | Clarity over cleverness |
| Ship to production | /ship | Faster is safer |
Want fewer manual steps once the spec exists? /build auto generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping between tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.
Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.
---
Quick Start
Fastest path — any agent, one command. The open skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):
npx skills add addyosmani/agent-skills # install all 24 skills
npx skills add addyosmani/agent-skills --list # browse before installingOr grab individual skills:
npx skills add addyosmani/agent-skills --skill code-review-and-quality # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development # red-green-refactor, enforcedPrefer a native integration? Pick your tool below.
<details> <summary><b>Claude Code (recommended)</b></summary>
Marketplace install:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skillsSSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or use the full HTTPS URL to force HTTPS cloning during the marketplace-add step: ``
bash /plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills`If/plugin installstill fails withgit@github.com: Permission denied (publickey)on Windows or macOS, the recommended workaround is to configure Git once to rewrite GitHub SSH URLs to HTTPS for subprocess clones:`bash git config --global url."https://github.com/".insteadOf git@github.com:``
Local / development:
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills</details>
<details> <summary><b>Cursor</b></summary>
Put workflow skills under .cursor/skills/ (sync from agent-skills/skills/) and short policies in .cursor/rules/*.mdc — do not paste full skills into rules. See docs/cursor-setup.md.
</details>
<details> <summary><b>Antigravity CLI</b></summary>
Install as a native plugin for skills, subagents, and slash commands. See docs/antigravity-setup.md.
Install from the repo:
agy plugin install https://github.com/addyosmani/agent-skills.gitInstall from a local clone:
git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills</details>
<details> <summary><b>Gemini CLI</b></summary>
Install as native skills for auto-discovery, or add to GEMINI.md for persistent context. See docs/gemini-cli-setup.md.
Install from the repo:
gemini skills install https://github.com/addyosmani/agent-skills.git --path skillsInstall from a local clone:
gemini skills install ./agent-skills/skills/</details>
<details> <summary><b>Windsurf</b></summary>
Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.
</details>
<details> <summary><b>OpenCode</b></summary>
Uses agent-driven skill execution via AGENTS.md and the skill tool.
</details>
<details> <summary><b>GitHub Copilot</b></summary>
Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.
</details>
<details> <summary><b>Kiro IDE & CLI </b></summary> Skills for Kiro reside under ".kiro/skills/" and can be stored under Project or Global level. Kiro also supports Agents.md. See Kiro docs at https://kiro.dev/docs/skills/ </details>
<details> <summary><b>Codex</b></summary>
Install as a native Codex plugin (Codex CLI v0.122+):
codex plugin marketplace add addyosmani/agent-skillsCodex reads the root skills/ directory directly through .codex-plugin/plugin.json. Once installed, invoke skills in chat using @ (e.g., @spec-driven-development). See docs/codex-setup.md for local installation and troubleshooting.
</details>
<details> <summary><b>Other Agents</b></summary>
Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.
</details>
---
Adoption
Already installed? How you roll the pack out depends on your codebase. The Adoption Guide covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.
---
All 24 Skills
The commands above are entry points. The pack includes 24 skills total — 23 lifecycle skills plus the using-agent-skills meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
Meta - Discover which skill applies
| Skill | What It Does | Use When |
|---|---|---|
| using-agent-skills | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
Define - Clarify what to build
| Skill | What It Does | Use When |
|---|---|---|
| interview-me | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
| idea-refine | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
| spec-driven-development | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |
Plan - Break it down
| Skill | What It Does | Use When |
|---|---|---|
| planning-and-task-breakdown | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |
Build - Write the code
| Skill | What It Does | Use When |
|---|---|---|
| incremental-implementation | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
| test-driven-development | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
| context-engineering | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |
| source-driven-development | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
| doubt-driven-development | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
| frontend-ui-engineering | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
| api-and-interface-design | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
Verify - Prove it works
| Skill | What It Does | Use When |
|---|---|---|
| browser-testing-with-devtools | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |
| debugging-and-error-recovery | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
Review - Quality gates before merge
| Skill | What It Does | Use When |
|---|---|---|
| code-review-and-quality | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
| code-simplification | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
| security-and-hardening | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
| performance-optimization | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
Ship - Deploy with confidence
| Skill | What It Does | Use When |
|---|---|---|
| git-workflow-and-versioning | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
| ci-cd-and-automation | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
| deprecation-and-migration | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
| documentation-and-adrs | Architecture Decision Records, API docs, inline documentation standards - document the why | Making architectural decisions, changing APIs, or shipping features |
| observability-and-instrumentation | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
| shipping-and-launch | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
---
Agent Personas
Pre-configured specialist personas for targeted reviews:
| Agent | Role | Perspective |
|---|---|---|
| code-reviewer | Senior Staff Engineer | Five-axis code review with "would a staff engineer approve this?" standard |
| test-engineer | QA Specialist | Test strategy, coverage analysis, and the Prove-It pattern |
| security-auditor | Security Engineer | Vulnerability detection, threat modeling, OWASP assessment |
| web-performance-auditor | Web Performance Engineer | Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via /webperf |
See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.
---
Reference Checklists
Quick-reference material that skills pull in when needed:
| Reference | Covers |
|---|---|
| definition-of-done.md | Project-wide standing bar every change clears, contrasted with per-task acceptance criteria |
| testing-patterns.md | Test structure, naming, mocking, React/API/E2E examples, anti-patterns |
| security-checklist.md | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10 |
| performance-checklist.md | Core Web Vitals targets, frontend/backend checklists, measurement commands |
| accessibility-checklist.md | Keyboard nav, screen readers, visual design, ARIA, testing tools |
| observability-checklist.md | On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gate |
| orchestration-patterns.md | Endorsed multi-persona orchestration patterns, anti-patterns, and the "personas don't invoke personas" rule |
---
How Skills Work
Every skill follows a consistent anatomy:
┌─────────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ Frontmatter ─────────────────────────────┐ │
│ │ name: lowercase-hyphen-name │ │
│ │ description: Guides agents through [task].│ │
│ │ Use when… │ │
│ └───────────────────────────────────────────┘ │
│ Overview → What this skill does │
│ When to Use → Triggering conditions │
│ Process → Step-by-step workflow │
│ Rationalizations → Excuses + rebuttals │
│ Red Flags → Signs something's wrong │
│ Verification → Evidence requirements │
└─────────────────────────────────────────────────┘Key design choices:
- Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
- Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
- Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
- Progressive disclosure. The
SKILL.mdis the entry point. Supporting references load only when needed, keeping token usage minimal.
---
Project Structure
agent-skills/
├── skills/ # 24 skills (23 lifecycle + 1 meta)
│ ├── interview-me/ # Define
│ ├── idea-refine/ # Define
│ ├── spec-driven-development/ # Define
│ ├── planning-and-task-breakdown/ # Plan
│ ├── incremental-implementation/ # Build
│ ├── context-engineering/ # Build
│ ├── source-driven-development/ # Build
│ ├── doubt-driven-development/ # Build
│ ├── frontend-ui-engineering/ # Build
│ ├── test-driven-development/ # Build
│ ├── api-and-interface-design/ # Build
│ ├── browser-testing-with-devtools/ # Verify
│ ├── debugging-and-error-recovery/ # Verify
│ ├── code-review-and-quality/ # Review
│ ├── code-simplification/ # Review
│ ├── security-and-hardening/ # Review
│ ├── performance-optimization/ # Review
│ ├── git-workflow-and-versioning/ # Ship
│ ├── ci-cd-and-automation/ # Ship
│ ├── deprecation-and-migration/ # Ship
│ ├── documentation-and-adrs/ # Ship
│ ├── observability-and-instrumentation/ # Ship
│ ├── shipping-and-launch/ # Ship
│ └── using-agent-skills/ # Meta: how to use this pack
├── agents/ # 4 specialist personas
├── references/ # 7 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---
Why Agent Skills?
AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code.
Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.
Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.
---
How it compares
Wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md for an honest, side-by-side look at how the three are shaped differently and when to reach for each — including a link to a controlled head-to-head experiment.
---
Contributing
Skills should be 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).
See docs/skill-anatomy.md for the format specification and CONTRIBUTING.md for guidelines.
---
Team
agent-skills is built and maintained by:
| Name | GitHub | Role | |
|---|---|---|---|
| <img src="https://github.com/addyosmani.png?size=120" width="60" height="60" alt="Addy Osmani"> | Addy Osmani | @addyosmani | Creator |
| <img src="https://github.com/federicobartoli.png?size=120" width="60" height="60" alt="Federico Bartoli"> | Federico Bartoli | @federicobartoli | Collaborator |
| <img src="https://github.com/nucliweb.png?size=120" width="60" height="60" alt="Joan León"> | Joan León | @nucliweb | Collaborator |
---
License
MIT - use these skills in your projects, teams, and tools.