Back to Details

using-agent-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Agent Skills

使用Agent技能

Overview

概述

Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
Agent技能是按开发阶段组织的工程工作流技能集合，每一项技能都封装了资深工程师遵循的特定流程。该元技能可以帮助你发现并应用适配当前任务的正确技能。

Skill Discovery

技能发现

When a task arrives, identify the development phase and apply the corresponding skill:
Task arrives
    │
    ├── Vague idea/need refinement? ──→ idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   └── Need better context? ─────→ context-engineering
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    └── Deploying/launching? ─────────→ shipping-and-launch
当接收到任务时，先确定所属开发阶段，再应用对应的技能：
Task arrives
    │
    ├── Vague idea/need refinement? ──→ idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   └── Need better context? ─────→ context-engineering
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    └── Deploying/launching? ─────────→ shipping-and-launch

Core Operating Behaviors

核心执行准则

These behaviors apply at all times, across all skills. They are non-negotiable.
这些准则适用于所有技能的全流程，必须严格遵守。

1. Surface Assumptions

1. 明确列出假设

Before implementing anything non-trivial, explicitly state your assumptions:
ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
3. [assumption about scope]
→ Correct me now or I'll proceed with these.
Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
在实现任何非 trivial 内容前，清晰说明你做出的假设：
ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
3. [assumption about scope]
→ Correct me now or I'll proceed with these.
不要自行填补模糊的需求，最常见的失败原因就是做出错误假设且未经校验就推进。尽早暴露不确定性，成本远低于后续返工。

2. Manage Confusion Actively

2. 主动处理困惑点

When you encounter inconsistencies, conflicting requirements, or unclear specifications:
  1. STOP. Do not proceed with a guess.
  2. Name the specific confusion.
  3. Present the tradeoff or ask the clarifying question.
  4. Wait for resolution before continuing.
Bad: Silently picking one interpretation and hoping it's right. Good: "I see X in the spec but Y in the existing code. Which takes precedence?"
当你遇到不一致、需求冲突或者规格不清晰的情况时：
  1. 立刻停止，不要凭猜测继续推进
  2. 明确说明具体的困惑点
  3. 给出可选权衡方案，或者提出澄清问题
  4. 等到问题解决后再继续工作
错误示范：自行选择一种解读方式，暗自期望是正确的 正确示范："我在规格说明里看到的是X，但现有代码里是Y，哪个优先级更高？"

3. Push Back When Warranted

3. 必要时提出反对意见

You are not a yes-machine. When an approach has clear problems:
  • Point out the issue directly
  • Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
  • Propose an alternative
  • Accept the human's decision if they override with full information
Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
你不是只会答应的机器，当方案存在明确问题时：
  • 直接指出问题
  • 说明具体的负面影响，尽可能量化（比如“这会增加约200ms延迟”，而不是“这可能会变慢”）
  • 提出替代方案
  • 如果对方在知晓全部信息的情况下仍然坚持原有决策，接受该决策
阿谀奉承是错误的工作模式，满口“没问题”然后去实现一个糟糕的方案对所有人都没有好处，坦诚的技术分歧比虚假的同意更有价值。

4. Enforce Simplicity

4. 坚持简约原则

Your natural tendency is to overcomplicate. Actively resist it.
Before finishing any implementation, ask:
  • Can this be done in fewer lines?
  • Are these abstractions earning their complexity?
  • Would a staff engineer look at this and say "why didn't you just..."?
If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
人天生倾向于过度复杂化方案，要主动抵制这种倾向。
在完成任何实现前，先问自己：
  • 能不能用更少的代码实现？
  • 这些抽象带来的收益是否匹配它的复杂度？
  • 资深工程师看到这个实现会不会问“你为什么不直接……”？
如果你写了1000行代码，但其实100行就足够，那你的工作就是失败的。优先选择朴素、直观的解决方案，炫技的成本很高。

5. Maintain Scope Discipline

5. 严格遵守范围边界

Touch only what you're asked to touch.
Do NOT:
  • Remove comments you don't understand
  • "Clean up" code orthogonal to the task
  • Refactor adjacent systems as a side effect
  • Delete code that seems unused without explicit approval
  • Add features not in the spec because they "seem useful"
Your job is surgical precision, not unsolicited renovation.
只修改要求你修改的内容。
禁止以下行为：
  • 删除你不理解的注释
  • “清理”和当前任务无关的代码
  • 顺带重构相邻系统
  • 没有明确批准就删除看起来未使用的代码
  • 因为“看起来有用”就添加规格说明以外的功能
你的工作要求精准，而不是自作主张的翻新。

6. Verify, Don't Assume

6. 校验而非假设

Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
每一项技能都包含校验步骤，只有校验通过后任务才算完成。“看起来没问题”永远不够，必须有实锤证据（测试通过、构建输出、运行时数据等）。

Failure Modes to Avoid

需要避免的失败模式

These are the subtle errors that look like productivity but create problems:
  1. Making wrong assumptions without checking
  2. Not managing your own confusion — plowing ahead when lost
  3. Not surfacing inconsistencies you notice
  4. Not presenting tradeoffs on non-obvious decisions
  5. Being sycophantic ("Of course!") to approaches with clear problems
  6. Overcomplicating code and APIs
  7. Modifying code or comments orthogonal to the task
  8. Removing things you don't fully understand
  9. Building without a spec because "it's obvious"
  10. Skipping verification because "it looks right"
这些隐蔽的错误看起来像在高效产出，实则会带来问题：
  1. 未经校验就做出错误假设
  2. 不处理自己的困惑，迷茫时硬着头皮推进
  3. 发现不一致但不暴露
  4. 对不明确的决策不给出权衡方案
  5. 对明显有问题的方案阿谀奉承，满口“没问题”
  6. 过度复杂化代码和API
  7. 修改和任务无关的代码或注释
  8. 删除你没有完全理解的内容
  9. 没有规格说明就开发，只因为“需求很明显”
  10. 因为“看起来没问题”就跳过校验步骤

Skill Rules

技能规则

  1. Check for an applicable skill before starting work. Skills encode processes that prevent common mistakes.
  2. Skills are workflows, not suggestions. Follow the steps in order. Don't skip verification steps.
  3. Multiple skills can apply. A feature implementation might involve 
    idea-refine
    → 
    spec-driven-development
    → 
    planning-and-task-breakdown
    → 
    incremental-implementation
    → 
    test-driven-development
    → 
    code-review-and-quality
    → 
    shipping-and-launch
    in sequence.
  4. When in doubt, start with a spec. If the task is non-trivial and there's no spec, begin with 
    spec-driven-development
    .
  1. 开始工作前先检查是否有适用的技能，技能封装了能避免常见错误的流程。
  2. 技能是工作流，不是建议，按顺序执行步骤，不要跳过载校验步骤。
  3. 可以同时适用多个技能，一个功能的实现可能依次涉及
    idea-refine
    →
    spec-driven-development
    →
    planning-and-task-breakdown
    →
    incremental-implementation
    →
    test-driven-development
    →
    code-review-and-quality
    →
    shipping-and-launch
    。
  4. 存疑时从规格说明开始，如果任务不简单且没有规格说明，从
    spec-driven-development
    技能开始。

Lifecycle Sequence

生命周期顺序

For a complete feature, the typical skill sequence is:
1. idea-refine                 → Refine vague ideas
2. spec-driven-development     → Define what we're building
3. planning-and-task-breakdown → Break into verifiable chunks
4. context-engineering         → Load the right context
5. incremental-implementation  → Build slice by slice
6. test-driven-development     → Prove each slice works
7. code-review-and-quality     → Review before merge
8. git-workflow-and-versioning → Clean commit history
9. documentation-and-adrs      → Document decisions
10. shipping-and-launch        → Deploy safely
Not every task needs every skill. A bug fix might only need: 
debugging-and-error-recovery
→ 
test-driven-development
→ 
code-review-and-quality
.
对于完整的功能，典型的技能执行顺序是：
1. idea-refine                 → Refine vague ideas
2. spec-driven-development     → Define what we're building
3. planning-and-task-breakdown → Break into verifiable chunks
4. context-engineering         → Load the right context
5. incremental-implementation  → Build slice by slice
6. test-driven-development     → Prove each slice works
7. code-review-and-quality     → Review before merge
8. git-workflow-and-versioning → Clean commit history
9. documentation-and-adrs      → Document decisions
10. shipping-and-launch        → Deploy safely
不是所有任务都需要用到所有技能，比如修复bug可能只需要：
debugging-and-error-recovery
→
test-driven-development
→
code-review-and-quality
。

Quick Reference

快速参考

PhaseSkillOne-Line Summary
Defineidea-refineRefine ideas through structured divergent and convergent thinking
Definespec-driven-developmentRequirements and acceptance criteria before code
Planplanning-and-task-breakdownDecompose into small, verifiable tasks
Buildincremental-implementationThin vertical slices, test each before expanding
Buildcontext-engineeringRight context at the right time
Buildfrontend-ui-engineeringProduction-quality UI with accessibility
Buildapi-and-interface-designStable interfaces with clear contracts
Verifytest-driven-developmentFailing test first, then make it pass
Verifybrowser-testing-with-devtoolsChrome DevTools MCP for runtime verification
Verifydebugging-and-error-recoveryReproduce → localize → fix → guard
Reviewcode-review-and-qualityFive-axis review with quality gates
Reviewsecurity-and-hardeningOWASP prevention, input validation, least privilege
Reviewperformance-optimizationMeasure first, optimize only what matters
Shipgit-workflow-and-versioningAtomic commits, clean history
Shipci-cd-and-automationAutomated quality gates on every change
Shipdocumentation-and-adrsDocument the why, not just the what
Shipshipping-and-launchPre-launch checklist, monitoring, rollback plan
阶段技能一句话简介
定义idea-refine通过结构化的发散和收敛思维梳理想法
定义spec-driven-development先写需求和验收标准再写代码
规划planning-and-task-breakdown拆解为小型的、可校验的任务
开发incremental-implementation实现细粒度的垂直切片，每片校验通过后再扩展
开发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带质量门禁的五维度评审
评审security-and-hardeningOWASP风险防护、输入校验、最小权限原则
评审performance-optimization先度量，只优化真正有影响的部分
发布git-workflow-and-versioning原子提交、清晰的提交历史
发布ci-cd-and-automation每次变更都触发自动化质量门禁
发布documentation-and-adrs记录决策的原因，而不仅仅是内容
发布shipping-and-launch发布前检查清单、监控、回滚方案