Addy Osmani 使用 agent-skills 总览

使用 agent-skills 总览：addyosmani/agent-skills: using-agent-skills，适用于工程实践、代码质量与开发流程优化。

Skill Documentation

Addy Osmani 使用 agent-skills 总览

摘要

使用 agent-skills 总览：addyosmani/agent-skills: using-agent-skills，适用于工程实践、代码质量与开发流程优化。

> 来源: addyosmani/agent-skills — Google Chrome 团队领袖 Addy Osmani

> 原文件: skills/using-agent-skills/SKILL.md

> 模型推荐: 看 skill 类型挑

这个 skill 是干嘛的

Addy Osmani (Google Chrome 团队 Performance Lead,前端工程领域权威) 整理的 24 个工程方法论 skill 集合 — 覆盖 API 设计 / 浏览器测试 / CI/CD / 代码评审 / TDD / 安全 / 性能 / 部署 等。

michael 强调"skill 要有相应的指导功能,指导用户使用",所以加了下面两节让 Agent 和用户对接。

---

🤖 Agent 使用说明

1. 接到任务后,先按这个 skill 的触发关键词跑

2. 跑 Checklist 一遍,标记红线步骤

3. 红线步骤必须先完成(往往是 ask user 确认)

4. 完工前用 verification step 自检

5. 跑完了告诉用户结果,不要自行提交

👤 用户需要做什么?

1. 告诉 Agent 你要做什么(一句话即可)

2. 如果 skill 要求 ask user 凭证 / OAuth / 部署密钥,按提示提供

3. 完工后让 Agent 跑自检再交回

4. 全程 Agent 自动化,你只需回答"是/否"类决策点

---

原 skill 内容(addyosmani/agent-skills/using-agent-skills/SKILL.md,截断到 12k chars)

---

name: using-agent-skills

description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.

---

Using Agent Skills

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.

Skill Discovery

When a task arrives, identify the development phase and apply the corresponding skill:

Task arrives
    │
    ├── Don't know what you want yet? ──────→ interview-me
    ├── Have a rough concept, need variants? → 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
    │   ├── Need doc-verified code? ───→ source-driven-development
    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Too complex? ─────────────→ code-simplification
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Deprecating/migrating? ────────→ deprecation-and-migration
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation
    └── Deploying/launching? ─────────→ shipping-and-launch

Core Operating Behaviors

These behaviors apply at all times, across all skills. They are non-negotiable.

1. Surface Assumptions

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.

2. Manage Confusion Actively

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?"

3. Push Back When Warranted

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.

4. Enforce Simplicity

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.

5. Maintain Scope Discipline

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

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).

Per-skill verification is the local check. The project-wide bar that applies to *every* change, regardless of which skill is active, is the Definition of Done: tests pass, no regressions, behavior verified at runtime, docs updated. See `../../references/definition-of-done.md`. It complements each task's acceptance criteria rather than replacing them.

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"

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` → `code-simplification` → `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`.

Lifecycle Sequence

For a complete feature, the typical skill sequence is:

1.  interview-me                → Extract what the user actually wants
2.  idea-refine                 → Refine vague ideas
3.  spec-driven-development     → Define what we're building
4.  planning-and-task-breakdown → Break into verifiable chunks
5.  context-engineering         → Load the right context
6.  source-driven-development   → Verify against official docs
7.  incremental-implementation  → Build slice by slice
8.  observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
9.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
10. test-driven-development     → Prove each slice works
11. code-review-and-quality     → Review before merge
12. code-simplification         → Reduce unnecessary complexity while preserving behavior
13. git-workflow-and-versioning → Clean commit history
14. documentation-and-adrs      → Document decisions
15. deprecation-and-migration   → Retire old systems and move users safely when needed
16. 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`.

Quick Reference

| Phase | Skill | One-Line Summary |

|-------|-------|-----------------|

| Define | interview-me | Surface what the user actually wants before any plan, spec, or code exists |

| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |

| Define | spec-driven-development | Requirements and acceptance criteria before code |

| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |

| Build | incremental-implementation | Thin vertical slices, test each before expanding |

| Build | source-driven-development | Verify against official docs before implementing |

| Build | doubt-driven-development | Adversarial fresh-context review of every non-trivial decision |

| Build | context-engineering | Right context at the right time |

| Build | frontend-ui-engineering | Production-quality UI with accessibility |

| Build | api-and-interface-design | Stable interfaces with clear contracts |

| Verify | test-driven-development | Failing test first, then make it pass |

| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |

| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |

| Review | code-review-and-quality | Five-axis review with quality gates |

| Review | code-simplification | Preserve behavior while reducing unnecessary complexity |

| Review | security-and-hardening | OWASP prevention, input validation, least privilege |

| Review | performance-optimization | Measure first, optimize only what matters |

| Ship | git-workflow-and-versioning | Atomic commits, clean history |

| Ship | ci-cd-and-automation | Automated quality gates on every change |

| Ship | deprecation-and-migration | Remove old systems and migrate users safely |

| Ship | documentation-and-adrs | Document the why, not just the what |

| Ship | observability-and-instrumentation | Structured logs, RED metrics, traces, symptom-based alerts |

| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |

常见问题（FAQ）

使用「使用 agent-skill」这个 skill 能解决什么问题?

本 skill 专注于使用 agent-skill，addyosmani/agent-skills: using-agent-skills。它将相关流程标准化，帮助用户更快拿到可靠结果，减少重复手工操作。

什么情况下适合使用「使用 agent-skill」?

当你需要在使用 agent-skills 总览相关工作中获得稳定、可复用的产出时最适合——无论是单次任务还是纳入日常工作流，都能直接调用。

使用「使用 agent-skill」前需要准备什么?

需要一个具体的项目或任务上下文，最好带有代码仓库或需求文档。