🔥 Addy Osmani 的 agent-skills：为 AI 编码智能体提供生产级工程技能
英文标题：🔥 addyosmani/agent-skills
Addy Osmani 发布了开源项目 agent-skills，为 AI 编码智能体提供覆盖全开发生命周期的 24 个结构化技能与 8 个斜杠命令。这些技能将高级工程师的工作流、质量门禁和最佳实践打包，从而让 AI 编码助手在每个阶段持续遵循规范。项目支持 Claude Code、Cursor、Gemini CLI 等主流工具，旨在减少手动操作并提升生成代码的可靠性，对希望提高 AI 辅助开发质量的团队具有重要意义。
5.1 KB
57.7 KB
中文
面向 AI 编码智能体的生产级工程技能。
技能编码了资深工程师在构建软件时使用的工作流、质量门禁和最佳实践。这些技能被打包，以便 AI 智能体在开发的每个阶段都能持续遵循它们。
DEFINE PLAN BUILD VERIFY REVIEW SHIP
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/spec /plan /build /test /review /ship
映射到开发生命周期的 8 个斜杠命令。每个命令会自动激活相应的技能。
| 你要做什么 | 命令 | 核心原则 |
|---|---|---|
| 定义要构建什么 | /spec |
规范先于代码 |
| 规划如何构建 | /plan |
小而原子的任务 |
| 增量构建 | /build |
一次一个薄切片 |
| 证明它有效 | /test |
测试就是证明 |
| 合并前评审 | /review |
改善代码健康度 |
| 审计网络性能 | /webperf |
优化前先测量 |
| 简化代码 | /code-simplify |
清晰优于取巧 |
| 发布到生产环境 | /ship |
更快即更安全 |
一旦规范存在，是否想减少手动步骤？/build auto 会生成计划并在一次批准的流程中实现每个任务——你只需批准计划一次，之后它就会自动运行。它消除了任务之间的人工干预，而非验证本身：每个任务仍然是测试驱动并单独提交，并在失败或存在风险步骤时暂停。
技能还会根据你正在做的事情自动激活——设计 API 会触发 api-and-interface-design，构建 UI 会触发 frontend-ui-engineering，以此类推。
Claude Code（推荐）
市场安装：
/plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills
遇到 SSH 错误？ 市场通过 SSH 克隆仓库。如果你没有在 GitHub 上设置 SSH 密钥，可以添加你的 SSH 密钥，或使用完整的 HTTPS URL 强制进行 HTTPS 克隆：
/plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills
本地/开发：
git clone https://github.com/addyosmani/agent-skills.git claude --plugin-dir /path/to/agent-skills
Cursor
将任何 SKILL.md 复制到 .cursor/rules/，或引用完整的 skills/ 目录。查看 docs/cursor-setup.md。
Antigravity CLI
作为技能、子智能体和斜杠命令的原生插件安装。查看 docs/antigravity-setup.md。
从仓库安装：
agy plugin install https://github.com/addyosmani/agent-skills.git
从本地克隆安装：
git clone https://github.com/addyosmani/agent-skills.git agy plugin install ./agent-skills
Gemini CLI
作为原生技能安装以实现自动发现，或添加到 GEMINI.md 以提供持久上下文。查看 docs/gemini-cli-setup.md。
从仓库安装：
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
从本地克隆安装：
gemini skills install ./agent-skills/skills/
Windsurf
将技能内容添加到你的 Windsurf 规则配置中。查看 docs/windsurf-setup.md。
OpenCode
通过 AGENTS.md 和 skill 工具使用智能体驱动的技能执行。
GitHub Copilot
使用 agents/ 中的智能体定义作为 Copilot 角色，并在 .github/copilot-instructions.md 中使用技能内容。查看 docs/copilot-setup.md。
Kiro IDE & CLI Kiro 的技能存放在 ".kiro/skills/" 下，可以存储在项目级或全局级。Kiro 也支持 Agents.md。查看 Kiro 文档 https://kiro.dev/docs/skills/
Codex / 其他智能体
技能是纯 Markdown 格式——它们可以和任何接受系统提示或指令文件的智能体一起工作。查看 docs/getting-started.md。
以上命令是入口点。该技能包共有 24 个技能——23 个生命周期技能加上 using-agent-skills 元技能。每个技能都是一个结构化工作流，包含步骤、验证门禁和反合理化表。你也可以直接引用任何技能。
元技能 - 发现适用的技能
| 技能 | 作用 | 何时使用 |
|---|---|---|
| using-agent-skills | 将传入的工作映射到正确的技能工作流，并定义共享操作规则 | 启动会话或决定哪个技能适用 |
定义 - 明确要构建什么
| 技能 | 作用 | 何时使用 |
|---|---|---|
| interview-me | 一次问一个问题的访谈，提取用户真正想要的，而不是他们认为他们应该要的，直到约 95% 的信心 | 需求描述不足，或用户调用 "interview me" / "grill me" |
| idea-refine | 结构化的发散/收敛思维，将模糊的想法转化为具体提案 | 你有一个需要探索的粗略概念 |
| spec-driven-development | 在任何代码之前编写涵盖目标、命令、结构、代码风格、测试和边界的 PRD | 开始一个新项目、功能或重大变更 |
规划 - 分解为任务
| 技能 | 作用 | 何时使用 |
|---|---|---|
| planning-and-task-breakdown | 将规范分解为小的、可验证的任务，包含验收标准和依赖排序 | 你有一个规范，需要可实施的单元 |
构建 - 实现（需要时使用正确的技能）
| 技能 | 作用 | 何时使用 |
|---|---|---|
| incremental-implementation | 薄垂直切片 - 实现、测试、验证、提交。特性开关、安全默认值、易于回滚的变更 | 任何涉及多个文件的变更 |
| test-driven-development | 红-绿-重构，测试金字塔 (80/15/5)，测试规模，DAMP 优于 DRY，碧昂丝规则，浏览器测试 | 实现逻辑，修复错误，或改变行为 |
| context-engineering | 在正确的时间向智能体提供正确的信息 - 规则文件、上下文打包、MCP 集成 | 开始会话、切换任务，或输出质量下降时 |
| source-driven-development | 将每个框架决策基于官方文档 - 验证、引用来源、标记未经验证的内容 | 你希望为任何框架或库生成权威、引用来源的代码 |
| doubt-driven-development | 对飞行中的每个重要决策进行对抗性全新上下文审查 - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP，可选用户授权的跨模型升级 | 风险很高（生产环境、安全、不可逆），在不熟悉的代码中工作，或者一个自信的输出现在验证比以后调试成本更低 |
| frontend-ui-engineering | 组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA 无障碍性 | 构建或修改面向用户的界面 |
| api-and-interface-design | 契约优先设计，Hyrum 定律，单一版本规则，错误语义，边界验证 | 设计 API、模块边界或公共接口 |
验证 - 测试并证明它有效
| 技能 | 作用 | 何时使用 |
|---|---|---|
| browser-testing-with-devtools | Chrome DevTools MCP 用于实时运行时数据 - DOM 检查、控制台日志、网络追踪、性能分析 | 构建或调试任何在浏览器中运行的东西 |
| debugging-and-error-recovery | 五步诊断：复现、定位、精简、修复、守卫。停止线规则，安全回退 | 测试失败，构建中断，或行为异常 |
审查 - 合并前的质量门禁
| 技能 | 作用 | 何时使用 |
|---|---|---|
| code-review-and-quality | 五轴审查，变更规模（~100 行），严重性标签（Nit/Optional/FYI），审查速度规范，拆分策略 | 在合并任何变更之前 |
| code-simplification | Chesterton 的栅栏，500 条规则，在保持精确行为的同时降低复杂性 | 代码可运行但读起来或维护起来比应有的更难 |
| security-and-hardening | OWASP Top 10 预防，认证模式，密钥管理，依赖审计，三层边界系统 | 处理用户输入、认证、数据存储或外部集成 |
| performance-optimization | 测量优先的方法 - Core Web Vitals 指标目标，性能分析工作流，包分析，反模式检测 | 存在性能要求或你怀疑性能退化 |
发布 - 自信部署
| 技能 | 作用 | 何时使用 |
|---|---|---|
| git-workflow-and-versioning | 基于主干的开发，原子提交，变更规模（~100 行），提交作为保存点模式 | 进行任何代码变更时（始终） |
| ci-cd-and-automation | 左移，更快即更安全，特性开关，质量门禁流水线，故障反馈循环 | 设置或修改构建和部署流水线 |
| deprecation-and-migration | 代码即负债心态，强制与建议性弃用，迁移模式，僵尸代码移除 | 移除旧系统，迁移用户，或使功能退役 |
| documentation-and-adrs | 架构决策记录，API 文档，内联文档标准 - 记录为什么 | 做出架构决策，更改 API，或发布功能 |
| observability-and-instrumentation | 结构化日志，RED 指标，OpenTelemetry 追踪，基于症状的告警 - 边构建边检测 | 添加遥测，或发布任何将在生产环境运行的东西 |
| shipping-and-launch | 发布前检查清单，特性开关生命周期，分阶段发布，回滚程序，监控设置 | 准备部署到生产环境 |
预配置的专业角色，用于有针对性的审查：
| 智能体 | 角色 | 视角 |
|---|---|---|
| code-reviewer | 高级主任工程师 | 五轴代码审查，采用“资深工程师会批准这个吗？”的标准 |
| test-engineer | QA 专家 | 测试策略、覆盖率分析和证明模式 |
| security-auditor | 安全工程师 | 漏洞检测、威胁建模、OWASP 评估 |
| web-performance-auditor | Web 性能工程师 | 使用快速/深度模式和指标诚实规则的 Core Web Vitals 审计；通过 /webperf 运行 |
查看 docs/agents.md 了解决策矩阵、编排规则，以及角色如何与技能和斜杠命令组合。
技能在需要时拉取的快速参考材料：
| 参考 | 涵盖内容 |
|---|---|
| definition-of-done.md | 项目范围内每个变更都必须满足的持久标准 |
English / 原文
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.
DEFINE PLAN BUILD VERIFY REVIEW SHIP
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/spec /plan /build /test /review /ship
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.
Claude Code (recommended)
Marketplace install:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
SSH 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 the HTTPS cloning:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills
Local / development:
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
Cursor
Copy any SKILL.md into .cursor/rules/, or reference the full skills/ directory. See docs/cursor-setup.md.
Antigravity CLI
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.git
Install from a local clone:
git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills
Gemini CLI
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 skills
Install from a local clone:
gemini skills install ./agent-skills/skills/
Windsurf
Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.
OpenCode
Uses agent-driven skill execution via AGENTS.md and the skill tool.
GitHub Copilot
Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.
**Kiro IDE & CLI ** 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/ Codex / Other Agents
Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.
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 |
| 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 |
| 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 |
| 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 |
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.
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 |
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.
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/ # 5 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
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.
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.
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.
MIT - use these skills in your projects, teams, and tools.