wehub-resource-sync
a59bbacbf3
23 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Agent Skills
面向 AI 编程智能体（AI coding agents）的生产级工程技能。
技能将资深工程师在构建软件时所采用的工作流、质量关卡（quality gates）和最佳实践编码其中。这些技能被打包封装，以便 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
Commands
8 个斜杠命令（slash commands）对应开发全生命周期。每个命令都会自动激活相应的技能。
| 你在做什么 | 命令 | 核心原则 |
|---|---|---|
| 定义要构建什么 | /spec |
先写规格，再写代码 |
| 规划如何构建 | /plan |
小而原子的任务 |
| 增量式构建 | /build |
一次只做一个切片 |
| 证明它能工作 | /test |
测试即证明 |
| 合并前审查 | /review |
提升代码健康度 |
| 审计 Web 性能 | /webperf |
先测量，再优化 |
| 简化代码 | /code-simplify |
清晰优于炫技 |
| 发布到生产环境 | /ship |
更快即更安全 |
规格确定后想减少手动步骤？/build auto 会生成计划并在单次获批流程中实现所有任务——你只需批准计划一次，之后它会自主运行。它消除的是任务之间的人工介入，而非验证环节：每个任务仍采用测试驱动并单独提交，遇到失败或高风险步骤时会暂停。
技能也会根据你正在做的事自动激活——设计 API 会触发 api-and-interface-design，构建 UI 会触发 frontend-ui-engineering，以此类推。
Quick Start
最快路径——任意智能体，一条命令。 开源的 skills CLI 可安装到 70+ 种智能体（Claude Code、Cursor、Codex、Copilot、Cline 等）：
npx skills add addyosmani/agent-skills # install all 24 skills
npx skills add addyosmani/agent-skills --list # browse before installing
或单独获取各项技能：
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, enforced
更偏好原生集成？请在下方选择你的工具。
Claude Code（推荐）
Marketplace 安装：
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
SSH 报错？ Marketplace 通过 SSH 克隆仓库。如果你尚未在 GitHub 上配置 SSH 密钥，可以添加 SSH 密钥，或在 marketplace-add 步骤中使用完整的 HTTPS URL 强制 HTTPS 克隆：
/plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills如果
/plugin install在 Windows 或 macOS 上仍因git@github.com: Permission denied (publickey)失败，推荐的变通方案是配置 Git，将 GitHub SSH URL 重写为 HTTPS，供子进程克隆使用：git config --global url."https://github.com/".insteadOf git@github.com:
本地 / 开发：
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
Cursor
将工作流技能放在 .cursor/skills/（从 agent-skills/skills/ 同步），简短策略放在 .cursor/rules/*.mdc——不要把完整技能粘贴到 rules 中。参见 docs/cursor-setup.md。
Antigravity CLI
作为原生插件安装，支持技能、子智能体（subagents）和斜杠命令。参见 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 rules 配置中。参见 docs/windsurf-setup.md。
GitHub Copilot
使用 agents/ 中的智能体定义作为 Copilot 角色（personas），将技能内容放在 .github/copilot-instructions.md 中。参见 docs/copilot-setup.md。
Kiro IDE & CLI
Kiro 的技能位于 ".kiro/skills/"，可存放在项目级或全局级。Kiro 也支持 Agents.md。参见 Kiro 文档：https://kiro.dev/docs/skills/Codex
作为原生 Codex 插件安装（Codex CLI v0.122+）：
codex plugin marketplace add addyosmani/agent-skills
Codex 通过 .codex-plugin/plugin.json 直接读取根目录 skills/。安装后，在聊天中使用 @ 调用技能（例如 @spec-driven-development）。本地安装与故障排查参见 docs/codex-setup.md。
Other Agents
技能是纯 Markdown 文件——适用于任何接受系统提示词（system prompts）或指令文件的智能体。参见 docs/getting-started.md。
Adoption
已经安装好了？如何在你的代码库中推广这套技能包，取决于你的项目情况。Adoption Guide 涵盖两条路径：绿地项目从第一天起走完整生命周期，或在成熟代码库中以验证优先的方式渐进式推广。
All 24 Skills
上述命令是入口点。整套技能包共包含 24 项技能——23 项生命周期技能，加上 using-agent-skills 元技能（meta-skill）。每项技能都是结构化工作流，包含步骤、验证关卡和反合理化（anti-rationalization）对照表。你也可以直接引用任意技能。
Meta - 发现适用哪项技能
| Skill | What It Does | Use When |
|---|---|---|
| using-agent-skills | 将 incoming 工作映射到正确的技能工作流，并定义共享运行规则 | 开始会话或决定适用哪项技能时 |
Define - 明确要构建什么
| Skill | What It Does | Use When |
|---|---|---|
| interview-me | 一次一问的访谈，提取用户真正想要的（而非他们自认为应该想要的），直至约 95% 置信度 | 需求描述不足，或用户调用 "interview me" / "grill me" 时 |
| idea-refine | 结构化的发散/收敛思维，将模糊想法转化为具体方案 | 你有一个需要探索的粗略概念时 |
| spec-driven-development | 在写任何代码之前，撰写涵盖目标、命令、结构、代码风格、测试和边界的 PRD | 启动新项目、功能或重大变更时 |
规划（Plan）- 拆分任务
| 技能 | 作用 | 适用场景 |
|---|---|---|
| planning-and-task-breakdown | 将规格说明拆解为带有验收标准和依赖顺序的小型可验证任务 | 你有一份规格说明，需要可落地的实现单元 |
构建（Build）- 编写代码
| 技能 | 作用 | 适用场景 |
|---|---|---|
| incremental-implementation | 薄垂直切片——实现、测试、验证、提交。特性开关、安全默认值、便于回滚的改动 | 任何涉及多个文件的改动 |
| test-driven-development | 红-绿-重构（Red-Green-Refactor）、测试金字塔（80/15/5）、测试规模、DAMP 优于 DRY、Beyoncé 规则（Beyonce Rule）、浏览器测试 | 实现逻辑、修复 bug 或变更行为时 |
| context-engineering | 在正确的时间向 agent 提供正确信息——规则文件、上下文打包、MCP 集成 | 开始新会话、切换任务，或输出质量下降时 |
| source-driven-development | 将每项框架决策建立在官方文档之上——验证、引用来源、标注未经验证之处 | 你希望为任何框架或库编写有据可查、引用来源的权威代码时 |
| doubt-driven-development | 对每个进行中的非平凡决策进行对抗式全新上下文评审——CLAIM → EXTRACT → DOUBT → RECONCILE → STOP，并可经用户授权进行跨模型升级 | 风险较高（生产环境、安全、不可逆操作）、在不熟悉的代码中工作，或自信输出的验证成本现在低于日后调试成本时 |
| frontend-ui-engineering | 组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA 无障碍 | 构建或修改面向用户的界面时 |
| api-and-interface-design | 契约优先设计、海勒姆定律（Hyrum's Law）、单版本规则（One-Version Rule）、错误语义、边界验证 | 设计 API、模块边界或公共接口时 |
验证（Verify）- 证明它能工作
| 技能 | 作用 | 适用场景 |
|---|---|---|
| browser-testing-with-devtools | 通过 Chrome DevTools MCP 获取实时运行时数据——DOM 检查、控制台日志、网络追踪、性能分析 | 构建或调试任何在浏览器中运行的内容时 |
| debugging-and-error-recovery | 五步分诊：复现、定位、缩小、修复、防护。停线规则（stop-the-line rule）、安全降级 | 测试失败、构建中断或行为异常时 |
评审（Review）- 合并前的质量关卡
| 技能 | 作用 | 适用场景 |
|---|---|---|
| code-review-and-quality | 五维评审、变更体量控制（约 100 行）、严重级别标签（Nit/Optional/FYI）、评审速度规范、拆分策略 | 合并任何改动之前 |
| code-simplification | 切斯特顿栅栏（Chesterton's Fence）、500 行规则（Rule of 500），在保持行为完全一致的前提下降低复杂度 | 代码能跑，但可读性或可维护性低于应有水平时 |
| security-and-hardening | OWASP Top 10 防护、认证模式、密钥管理、依赖审计、三层边界体系 | 处理用户输入、认证、数据存储或外部集成时 |
| performance-optimization | 先测量再优化——Core Web Vitals 目标、性能分析工作流、打包分析、反模式检测 | 存在性能要求或怀疑出现性能回退时 |
发布（Ship）- 自信部署
| 技能 | 作用 | 适用场景 |
|---|---|---|
| git-workflow-and-versioning | 主干开发（trunk-based development）、原子提交、变更体量控制（约 100 行）、提交即存档点模式 | 进行任何代码改动时（始终适用） |
| ci-cd-and-automation | 左移（Shift Left）、越快越安全（Faster is Safer）、特性开关、质量关卡流水线、失败反馈闭环 | 搭建或修改构建与部署流水线时 |
| deprecation-and-migration | 代码即负债思维、强制与建议式弃用、迁移模式、僵尸代码清理 | 移除旧系统、迁移用户或下线功能时 |
| documentation-and-adrs | 架构决策记录（ADR）、API 文档、行内文档标准——记录为什么 | 做架构决策、变更 API 或发布功能时 |
| observability-and-instrumentation | 结构化日志、RED 指标、OpenTelemetry 追踪、基于症状的告警——边构建边埋点 | 添加遥测，或发布任何将在生产环境运行的内容时 |
| shipping-and-launch | 上线前清单、特性开关生命周期、分阶段发布、回滚流程、监控配置 | 准备部署到生产环境时 |
Agent 角色人设
面向针对性评审的预配置专家角色：
| Agent | 角色 | 视角 |
|---|---|---|
| code-reviewer | 资深 Staff Engineer | 五维代码评审，以「Staff Engineer 会批准吗？」为标准 |
| test-engineer | QA 专家 | 测试策略、覆盖率分析与 Prove-It 模式 |
| security-auditor | 安全工程师 | 漏洞检测、威胁建模、OWASP 评估 |
| web-performance-auditor | Web 性能工程师 | 支持 Quick/Deep 模式的 Core Web Vitals 审计及指标诚实规则；通过 /webperf 运行 |
参见 docs/agents.md 了解决策矩阵、编排规则，以及角色人设如何与技能和斜杠命令组合使用。
参考清单
技能在需要时会引用的速查资料：
| 参考文档 | 涵盖内容 |
|---|---|
| definition-of-done.md | 每项改动均需达到的项目级常驻标准，与每项任务的验收标准形成对照 |
| testing-patterns.md | 测试结构、命名、模拟（mocking）、React/API/E2E 示例、反模式 |
| security-checklist.md | 提交前检查、认证、输入验证、请求头、CORS、OWASP Top 10 |
| performance-checklist.md | Core Web Vitals 目标、前端/后端清单、测量命令 |
| accessibility-checklist.md | 键盘导航、屏幕阅读器、视觉设计、ARIA、测试工具 |
| observability-checklist.md | 值班问题、结构化日志、RED/USE 指标、追踪、基于症状的告警、上线前关卡 |
| orchestration-patterns.md | 推荐的多角色编排模式、反模式，以及「角色不调用角色」规则 |
技能如何工作
每个技能都遵循一致的结构：
┌─────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────┘
关键设计选择：
- 流程，而非散文。 Skills 是智能体遵循的工作流，而非供其阅读的参考文档。每个 Skill 都包含步骤、检查点与退出标准。
- 反合理化。 每个 Skill 都包含一张表格，列出智能体为跳过步骤而常用的借口（例如「我稍后再补测试」）及有据可查的反驳论点。
- 验证不可妥协。 每个 Skill 都以证据要求收尾——测试通过、构建输出、运行时数据。「看起来没问题」永远不够。
- 渐进式披露。
SKILL.md是入口点。辅助参考资料仅在需要时加载，以将 token 用量控制在最低。
项目结构
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
为何需要 Agent Skills？
AI 编程智能体默认走最短路径——这往往意味着跳过规格说明、测试、安全审查，以及那些让软件可靠的生产实践。Agent Skills 为智能体提供结构化工作流，强制执行资深工程师在生产代码中所秉持的同等纪律。
每个 Skill 都编码了来之不易的工程判断：何时写规格、测什么、如何审查、何时发布。这些不是泛泛的提示词——而是那种有主见、流程驱动的实践，区分生产级工作与原型级工作。
Skills 融入了 Google 工程文化中的最佳实践——包括 Software Engineering at Google 与 Google 的 engineering practices guide. 中的概念。你会在 API 设计中看到 Hyrum 定律（Hyrum's Law），在测试中看到 Beyoncé 规则（Beyonce Rule）与测试金字塔（test pyramid），在代码审查中看到变更规模与审查速度规范，在简化中看到切斯特顿栅栏（Chesterton's Fence），在 Git 工作流中看到主干开发（trunk-based development），在 CI/CD 中看到左移（Shift Left）与功能开关（feature flags），还有将代码视为负债的专用弃用 Skill。这些不是抽象原则——它们直接嵌入智能体逐步遵循的工作流中。
对比
想了解它与 Superpowers 或 Matt Pocock's skills? 相比如何？请参阅 docs/comparison.md，其中对各方案的形态差异、适用场景做了坦诚的并排对比——并附有受控 head-to-head experiment. 的链接。
贡献
Skills 应当 具体（可执行步骤，而非模糊建议）、可验证（明确的退出标准与证据要求）、久经实战（基于真实工作流），且 精简（仅包含引导智能体所需内容）。
格式规范见 docs/skill-anatomy.md，贡献指南见 CONTRIBUTING.md。
团队
agent-skills 由以下成员构建与维护：
| 姓名 | GitHub | 角色 | |
|---|---|---|---|
 |
Addy Osmani | @addyosmani | 创建者 |
 |
Federico Bartoli | @federicobartoli | 协作贡献者 |
 |
Joan León | @nucliweb | 协作贡献者 |
许可证
MIT — 可在你的项目、团队和工具中使用这些技能。