From bbe2e8fa7d0c77ee60ac58b6d36708bb3817981e Mon Sep 17 00:00:00 2001 From: wehub-skill-sync Date: Mon, 13 Jul 2026 21:36:18 +0800 Subject: [PATCH] chore: import zh skill using-agent-skills --- README.wehub.md | 9 +++ SKILL.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 README.wehub.md create mode 100644 SKILL.md diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..bb14381 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,9 @@ +# WeHub 来源说明 + +- Skill 名称：`using-agent-skills` +- 中文类目：任务级 skill 路由与组合 +- 上游仓库：`addyosmani__agent-skills` +- 上游路径：`skills/using-agent-skills/SKILL.md` +- 上游链接：https://github.com/addyosmani/agent-skills/blob/HEAD/skills/using-agent-skills/SKILL.md +- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..b8963a2 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,189 @@ +--- +name: using-agent-skills +description: 发现并调用智能体技能。在启动会话或需要判断当前任务适用哪项技能时使用。这是一项元技能，负责管理所有其他技能的发现与调用方式。 +--- + +# 使用智能体技能 + +## 概述 + +智能体技能（Agent Skills）是一套按开发阶段组织的工程工作流技能。每项技能都编码了高级工程师遵循的特定流程。这项元技能帮助你发现当前任务适用的技能并加以应用。 + +## 技能发现 + +当任务到来时，识别出所属的开发阶段，并应用相应的技能： + +``` +任务到来 + │ + ├── 还不确定想要什么？ ─────────────→ interview-me + ├── 有个粗略概念，需要变体？ ───────→ idea-refine + ├── 新项目/新功能/新变更？ ─────→ spec-driven-development + ├── 有规格说明，需要拆解任务？ ───→ planning-and-task-breakdown + ├── 正在实现代码？ ───────────────→ incremental-implementation + │ ├── UI 相关工作？ ──────────→ frontend-ui-engineering + │ ├── API 相关工作？ ─────────→ api-and-interface-design + │ ├── 需要更好的上下文？ ─────→ context-engineering + │ ├── 需要文档验证的代码？ ───→ source-driven-development + │ └── 高风险/不熟悉代码？ ────→ doubt-driven-development + ├── 编写/运行测试？ ─────────────→ test-driven-development + │ └── 基于浏览器？ ───────────→ browser-testing-with-devtools + ├── 出问题了？ ──────────────────→ debugging-and-error-recovery + ├── 审查代码？ ──────────────────→ code-review-and-quality + │ ├── 太复杂了？ ─────────────→ code-simplification + │ ├── 安全顾虑？ ─────────────→ security-and-hardening + │ └── 性能问题？ ─────────────→ performance-optimization + ├── 提交/分支操作？ ────────────→ git-workflow-and-versioning + ├── CI/CD 流水线工作？ ──────────→ ci-cd-and-automation + ├── 弃用/迁移？ ─────────────────→ deprecation-and-migration + ├── 编写文档/ADRs？ ───────────→ documentation-and-adrs + ├── 添加日志/指标/告警？ ───────→ observability-and-instrumentation + └── 部署/上线？ ───────────────→ shipping-and-launch +``` + +## 核心操作行为 + +以下行为在所有时刻、所有技能中均适用，不可妥协。 + +### 1. 暴露假设 + +在实现任何非琐碎事项之前，明确陈述你的假设： + +``` +我所做的假设： +1. [关于需求的假设] +2. [关于架构的假设] +3. [关于范围的假设] +→ 现在纠正我，否则我将按这些假设推进。 +``` + +不要默默地填补模糊的需求。最常见的失败模式就是做出错误假设并未经核查地贸然推进。尽早暴露不确定性——这比返工代价更小。 + +### 2. 主动管理困惑 + +当你遇到不一致、冲突的需求或模糊的规格说明时： + +1. **停下来。** 不要凭猜测继续推进。 +2. 明确指出具体的困惑点。 +3. 呈现权衡方案或提出澄清问题。 +4. 等待问题解决后再继续。 + +**不好的做法：** 默默地选择一种理解，并希望它是对的。 +**好的做法：** "我在规格说明中看到 X，但在现有代码中看到 Y。哪个优先？" + +### 3. 必要时提出异议 + +你不是一个只会说"是"的机器。当某个方案存在明显问题时： + +- 直接指出问题所在 +- 解释具体的负面影响（尽可能量化——"这会增加约 200ms 延迟"，而不是"这可能会变慢"） +- 提出替代方案 +- 如果人类在了解全部信息后仍坚持决定，则接受 + +一味附和是一种失败模式。"当然可以！"然后实现一个糟糕的想法对任何人都没有帮助。诚实的技不同意见比虚假的一致更有价值。 + +### 4. 坚持简洁 + +你的自然倾向是过度复杂化。主动抵制这种倾向。 + +在完成任何实现之前，问问自己： +- 是否可以用更少的代码行完成？ +- 这些抽象是否值得其带来的复杂度？ +- 一位资深工程师看到后会不会说"你为什么不用……？" + +如果你写了 1000 行代码而 100 行就足够了，那你就失败了。偏爱平淡而明显的解决方案。花哨的写法代价高昂。 + +### 5. 保持范围纪律 + +只动你需要动的东西。 + +不要做以下事情： +- 删除你不理解的注释 +- "清理"与当前任务无关的代码 +- 作为副作用重构相邻系统 +- 未经明确批准就删除看似未使用的代码 +- 添加规格说明中没有的功能，只因为"看起来有用" + +你的工作是外科手术式的精准操作，而不是未经请求的翻新改造。 + +### 6. 验证，而非假设 + +每项技能都包含一个验证步骤。在验证通过之前，任务不算完成。"看起来没问题"永远不够——必须有证据（测试通过、构建输出、运行时数据）。 + +## 需要避免的失败模式 + +以下是一些看似高效实则制造问题的隐蔽错误： + +1. 未经核查就做出错误假设 +2. 没有管理好自己的困惑——迷失方向时仍硬着头皮推进 +3. 没有指出你注意到的不一致之处 +4. 没有就非显而易见的决策呈现权衡方案 +5. 对存在明显问题的方案一味附和（"当然可以！"） +6. 过度复杂化代码和 API +7. 修改与任务无关的代码或注释 +8. 删除你尚未完全理解的东西 +9. 因为没有规格说明就认为"显然应该这么做"而直接开干 +10. 因为"看起来没问题"就跳过验证 + +## 技能规则 + +1. **在开始工作之前检查是否有适用的技能。** 技能编码了可以防止常见错误的流程。 + +2. **技能是工作流，而非建议。** 按顺序执行步骤。不要跳过验证步骤。 + +3. **可以同时应用多项技能。** 一个功能实现可能涉及 `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `code-simplification` → `shipping-and-launch` 的序列。 + +4. **如有疑问，先从规格说明开始。** 如果任务非琐碎且没有规格说明，则从 `spec-driven-development` 开始。 + +## 生命周期序列 + +对于一个完整的功能，典型的技能序列如下： + +``` +1. interview-me → 挖掘用户真正想要什么 +2. idea-refine → 细化模糊的想法 +3. spec-driven-development → 定义我们要构建什么 +4. planning-and-task-breakdown → 拆解为可验证的单元 +5. context-engineering → 加载正确的上下文 +6. source-driven-development → 对照官方文档进行验证 +7. incremental-implementation → 逐片构建 +8. observability-and-instrumentation → 在构建过程中同时埋点（与第 7-9 步并行，而非在其后） +9. doubt-driven-development → 对非琐碎决策进行实时交叉审查 +10. test-driven-development → 证明每一片都能工作 +11. code-review-and-quality → 合并前审查 +12. code-simplification → 在保持行为不变的前提下减少不必要的复杂度 +13. git-workflow-and-versioning → 保持干净的提交历史 +14. documentation-and-adrs → 记录决策 +15. deprecation-and-migration → 在必要时退役旧系统并安全迁移用户 +16. shipping-and-launch → 安全部署 +``` + +并非每项任务都需要用到所有技能。一个 bug 修复可能只需要：`debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`。 + +## 快速参考 + +| 阶段 | 技能 | 一句话简介 | +|-------|-------|-----------------| +| 定义 | interview-me | 在任何计划、规格说明或代码存在之前，挖掘用户真正想要什么 | +| 定义 | idea-refine | 通过结构化的发散与收敛思维来细化想法 | +| 定义 | spec-driven-development | 先有需求和验收标准，再有代码 | +| 计划 | planning-and-task-breakdown | 拆解为小型、可验证的任务 | +| 构建 | incremental-implementation | 薄的垂直切片，逐个测试后再扩展 | +| 构建 | source-driven-development | 在实现之前对照官方文档进行验证 | +| 构建 | doubt-driven-development | 用对抗性新上下文审查每一个非琐碎决策 | +| 构建 | context-engineering | 在正确的时间提供正确的上下文 | +| 构建 | frontend-ui-engineering | 具有可访问性的生产级 UI | +| 构建 | api-and-interface-design | 具有清晰契约的稳定接口 | +| 验证 | test-driven-development | 先写出失败的测试，再让它通过 | +| 验证 | browser-testing-with-devtools | 使用 Chrome DevTools MCP 进行运行时验证 | +| 验证 | debugging-and-error-recovery | 复现 → 定位 → 修复 → 防护 | +| 审查 | code-review-and-quality | 五维度审查，配备质量门禁 | +| 审查 | code-simplification | 在保持行为不变的前提下减少不必要的复杂度 | +| 审查 | security-and-hardening | OWASP 防护、输入验证、最小权限原则 | +| 审查 | performance-optimization | 先测量，只优化重要的部分 | +| 发布 | git-workflow-and-versioning | 原子化提交，整洁的历史记录 | +| 发布 | ci-cd-and-automation | 每次变更自动通过质量门禁 | +| 发布 | deprecation-and-migration | 移除旧系统并安全迁移用户 | +| 发布 | documentation-and-adrs | 记录"为什么"，而不仅仅是"是什么" | +| 发布 | observability-and-instrumentation | 结构化日志、RED 指标、追踪、基于症状的告警 | +| 发布 | shipping-and-launch | 上线前检查清单、监控、回滚方案 |