Agent Skills 深度实战：当 AI 学会「工程师纪律」——从 Addy Osmani 的 7 个斜杠命令到生产级 AI 编程工作流的完全指南（2026）

写给每一位被 AI 编程助手「气死」过的工程师：你不是不会用 AI，你是缺一套让 AI「守规矩」的工程纪律框架。本文 18000 字，从架构设计到生产落地，带你完整理解 Agent Skills 为什么能在 3 周内刷爆 27000+ GitHub Star。

目录

1. AI 编程的「最后一公里」问题
2. Agent Skills 是什么？Addy Osmani 的解决方案
3. 架构全景：六阶段研发生命周期与 7 个斜杠命令
4. 核心技能解析（一）：/spec —— 先写规格，再写代码
5. 核心技能解析（二）：/plan —— 原子化任务拆解
6. 核心技能解析（三）：/build —— 增量构建与 TDD
7. 核心技能解析（四）：/test 与 /review —— 测试即证据
8. SKILL.md 格式详解：如何写一个生产级 Skill
9. 与 Claude Code / Cursor 的集成实战
10. 「反合理化」设计哲学
11. 生产案例：重构 Go 微服务项目
12. 与其他方案的深度对比
13. 局限性与未来方向
14. 总结：AI 编程的下一个范式转移

AI 编程的「最后一公里」问题

一个真实的翻车现场

# 你对 Claude Code 说：
# "帮我加一个用户导出功能，支持 CSV 和 Excel 格式"

# Claude Code 很高兴地输出了：
import pandas as pd

def export_users(format='csv'):
    users = get_all_users()  # 全量加载！
    df = pd.DataFrame(users)
    if format == 'csv':
        df.to_csv('users.csv')
    else:
        df.to_excel('users.xlsx')
    return "Done!"

问题在哪？

根本原因：AI 没有「工程纪律」

核心问题不是模型不够聪明，而是缺少约束：

当前 AI 编程的工作模式：

用户："帮我实现 X 功能"
  ↓
LLM："好的，这是代码..."（直接跳到实现）
  ↓
问题：没有需求澄清、没有任务拆解、没有测试驱动、没有代码审查

Agent Skills 的核心洞察：

"AI agents are only as good as the workflows they follow."
— Addy Osmani，Google Chrome 团队工程总监

Agent Skills 是什么？Addy Osmani 的解决方案

项目背景

• 作者：Addy Osmani，Google Chrome 团队工程总监
• 开源时间：2026 年 3 月
• GitHub Star：27000+（3 周内）
• 协议：MIT
• 定位：面向 AI 编程智能体的生产级工程技能库

核心思想

Agent Skills 将软件开发分解为六个不可跳过的阶段，每个阶段对应一个（或一组）Slash 命令：

DEFINE（定义）→ SPEC（规格）→ PLAN（规划）→ BUILD（构建）
                                              ↓
                                        VERIFY（验证）→ REVIEW（审查）→ SHIP（发布）

每个阶段都有明确的检查点（Checkpoint），AI 不能通过「假装做完」来跳过。

架构全景：六阶段研发生命周期与 7 个斜杠命令

六阶段生命周期

┌─────────────────────────────────────────────────────────┐
│              Agent Skills 六阶段生命周期                │
├─────────────────────────────────────────────────────────┤
│  DEFINE      PLAN        BUILD       VERIFY            │
│  (定义)      (规划)      (构建)     (验证)            │
│    │           │           │           │                │
│    ↓           ↓           ↓           ↓                │
│  IDEA →   TASK →    CODE →    TEST                  │
│  REFINE    BREAKDOWN  IMPL      COVERAGE              │
│                                                  │
│                              REVIEW      SHIP        │
│                              (审查)      (发布)       │
│                                │           │          │
│                                ↓           ↓          │
│                            CODE        DEPLOY         │
│                            REVIEW      PROD          │
└─────────────────────────────────────────────────────────┘

7 个斜杠命令

核心技能解析（一）：/spec —— 先写规格，再写代码

工作流程

用户输入：/spec 我想做一个用户导出功能

Agent 执行 spec-driven-development Skill：

步骤 1：需求澄清（强制提出 5+ 个问题）
  - 导出哪些字段？
  - 支持哪些格式？
  - 数据量上限？
  - 权限控制？
  
步骤 2：写 PRD（产品需求文档）
  输出：spec.md
  
步骤 3：等待用户确认
  - 用户说"确认" → 进入 /plan 阶段
  - 用户说"修改 xxx" → 回到步骤 1

实际生成的 PRD 示例

# 用户导出功能 PRD

## 目标
允许管理员将用户数据导出为 CSV 或 Excel 格式。

## 范围
### 包含
- 导出基本字段（ID、用户名、邮箱、注册时间）
- 支持 CSV 和 Excel 格式
- 数据量上限 10 万行
- 只有 SUPER_ADMIN 角色可以导出

### 不包含
- 自定义字段导出（v2 功能）
- 增量导出（只导出最近修改的）

## 验收标准
- [ ] 导出 1000 行数据，CSV 格式，耗时 < 2s
- [ ] 导出 10 万行数据，Excel 格式，内存占用 < 512MB
- [ ] 非 SUPER_ADMIN 角色调用返回 403
- [ ] 导出操作写入审计日志

核心技能解析（二）：/plan —— 原子化任务拆解

任务拆解原则

原则一：单一职责
每个任务只做一件事。如果你用「和」来描述任务，说明它还可以拆解。

原则二：可验证
每个任务必须有明确的验收标准。

原则三：依赖清晰
任务之间要有明确的依赖关系，形成 DAG。

输出示例：task-list.md

# 任务列表

## 任务 1：数据库查询层 [预估：1h]
**描述**：实现带权限校验的用户数据查询函数
**验收标准**：
- [ ] 函数签名：`get_exportable_users(admin_user: User) -> QuerySet`
- [ ] 权限校验：非 SUPER_ADMIN 抛出 PermissionDenied
- [ ] 只查询必要字段（避免 SELECT *）
- [ ] 支持按注册时间过滤

## 任务 2：CSV 导出实现 [预估：2h]
**依赖**：任务 1
**验收标准**：
- [ ] 使用 Python csv 模块（避免 pandas 依赖）
- [ ] 流式写入（避免内存爆炸）
- [ ] 支持中文编码（UTF-8 with BOM）
- [ ] 单元测试覆盖率 > 80%

核心技能解析（三）：/build —— 增量构建与 TDD

增量构建原则

# /build 命令执行流程

# ========== 第一轮：只做任务 1 ==========
"""
任务 1：数据库查询层

请按照以下流程执行：
1. 先写测试（TDD）
2. 实现功能
3. 运行测试，确保通过
4. 提交代码（git commit）
5. 输出进度报告
"""

TDD 严格执行

# tests/test_user_export.py（先写测试）
import pytest
from django.contrib.auth import get_user_model
from myapp.models import User

def test_get_exportable_users_permissions():
    """非 SUPER_ADMIN 调用应该抛出 PermissionDenied"""
    regular_user = User.objects.create_user(...)
    with pytest.raises(PermissionDenied):
        get_exportable_users(regular_user)

def test_get_exportable_users_fields():
    """应该只查询必要字段"""
    admin = User.objects.create_superuser(...)
    # 检查 query 是否使用了 only() 或 defer()
    ...

# 然后实现：
# myapp/export_utils.py
from django.core.exceptions import PermissionDenied

def get_exportable_users(admin_user):
    if not admin_user.is_superuser:
        raise PermissionDenied("Only SUPER_ADMIN can export users")
    
    return User.objects.filter(is_active=True).only(
        'id', 'username', 'email', 'date_joined'
    )

核心技能解析（四）：/test 与 /review —— 测试即证据

/test 自动审查清单

# /test 执行流程

## 步骤 1：运行所有现有测试
pytest --tb=short -q
→ 如果失败，停止执行，报告错误

## 步骤 2：检查测试覆盖率
pytest --cov=myapp --cov-report=term-missing
→ 如果覆盖率 < 80%，强制补充测试

## 步骤 3：边界条件测试
Agent 会自动生成边界条件测试：

def test_export_large_dataset():
    """导出 10 万行数据，检查内存占用"""
    # ...

def test_export_malicious_filename():
    """防止路径遍历攻击"""
    # ...

def test_export_concurrent_requests():
    """并发导出请求处理"""
    # ...

/review 代码审查清单

## 1. 代码质量
- [ ] 函数长度 < 50 行
- [ ] 圈复杂度 < 10
- [ ] 无重复代码（DRY）
- [ ] 变量命名清晰

## 2. 安全审查
- [ ] 无 SQL 注入风险
- [ ] 无 XSS 风险
- [ ] 敏感信息未硬编码
- [ ] 文件路径已校验（防止路径遍历）

## 3. 性能审查
- [ ] 无 N+1 查询
- [ ] 大数据量使用流式处理
- [ ] 数据库查询已优化

SKILL.md 格式详解：如何写一个生产级 Skill

标准结构

---
name: skill-name
description: 一句话描述
triggers:
  - "关键词1"
  - "关键词2"
version: 1.0.0
---

## 1. 触发条件
什么情况下应该激活这个 Skill？

## 2. 执行步骤
步骤 1：...
- 检查点：[AI 必须检查的事项]
- 输出：[AI 必须输出的内容]

## 3. 质量门禁
完成后必须检查：
- [ ] 门禁 1
- [ ] 门禁 2

## 4. 反合理化表格
| 想跳过的步骤 | 常见借口 | 为什么不能跳过 |
|--------------|------------|----------------|

## 5. 示例代码
[提供正例和反例]

## 6. 常见问题（FAQ）

实战：写一个自定义 Skill

假设你要写一个「实现 RESTful API」的 Skill：

---
name: restful-api-development
description: 实现符合 REST 规范的 API
triggers:
  - "REST API"
  - "实现接口"
  - "CRUD API"
---

## 执行步骤

### 步骤 1：API 设计（先设计，再实现）
输出 `api-design.md`，包含：
- 端点列表
- 请求/响应格式
- 错误码定义
- 认证方式

### 步骤 2：实现端点
按照 `api-design.md` 逐个实现端点。

**约束**：
- 必须实现权限检查
- 必须实现分页
- 必须统一错误格式

### 步骤 3：写测试
为每个端点写测试

## 质量门禁
- [ ] 所有端点都有请求参数验证
- [ ] 所有端点都有权限检查
- [ ] 错误响应格式统一
- [ ] 实现了分页
- [ ] 测试覆盖率 > 80%

与 Claude Code / Cursor 的集成实战

Claude Code 集成（最完整）

# 方法一：从 GitHub 安装（推荐）
claude plugin marketplace add addyosmani/agent-skills

# 方法二：本地安装
cd ~/.claude/skills/
git clone https://github.com/addyosmani/agent-skills.git

# 验证安装
claude skills list

使用方式：

# 在 Claude Code 中
> /spec 我想做一个用户反馈功能

[Claude 激活 spec-driven-development Skill，引导你写 PRD]

> /plan

[Claude 激活 planning-and-task-breakdown Skill，输出任务列表]

> /build

[Claude 激活 incremental-development Skill，增量实现]

Cursor 集成

# 在项目根目录
mkdir -p .cursor/skills/
cd .cursor/skills/
git clone https://github.com/addyosmani/agent-skills.git .

# 重启 Cursor

「反合理化」设计哲学

什么是「反合理化」？

合理化（Rationalization）：给自己找借口，跳过应该做的步骤。

AI 特别擅长合理化：

用户：请为这个函数写测试。

AI：好的！这个函数很简单，不需要测试。它只有 5 行，而且逻辑很清晰。
    我相信它一定能正常工作。让我们直接进入下一个任务吧！

Agent Skills 的解决方案：反合理化表格

在每个 Skill 中，都有一个「反合理化表格」，强制 AI 直面自己的借口：

## 反合理化表格

| 想跳过的步骤 | 常见借口 | 为什么不能跳过 |
|--------------|------------|----------------|
| 不写测试 | "这个功能很简单" | 简单的功能也应该有测试。今天简单，明天可能改复杂。 |
| 不做错误处理 | "不会出错" | 所有 I/O 都可能失败。防御性编程是职业素养。 |
| 不写文档 | "代码是自解释的" | 代码只解释「怎么做」，不解释「为什么这么做」。 |
| 不做性能优化 | "数据量很小" | 今天很小，不代表明天很小。优化应该成为习惯。 |

为什么「反合理化」有效？

心理学原理：承诺与一致性（Commitment and Consistency）。

当 AI 填写了反合理化表格后，它会在后续执行中「记得」自己说过「不能跳过」。

生产案例：重构 Go 微服务项目

背景

一个运行了 2 年的 Go 微服务项目：

• 测试覆盖率 < 30%
• 无 API 文档
• 错误处理不一致
• 性能问题（P95 延迟 800ms）

使用 Agent Skills 的重构流程

阶段一：/spec（定义问题）

## 问题定义
Go 微服务的代码质量和性能问题，需要通过重构提升可维护性和性能。

## 目标
1. 测试覆盖率从 30% 提升到 > 80%
2. P95 延迟从 800ms 降低到 < 100ms
3. 统一错误处理格式
4. 生成完整的 API 文档

## 范围
### 包含
- 重构 handler/ 层
- 重构 service/ 层
- 添加单元测试和集成测试
- 添加 API 文档（Swagger）

### 不包含
- 重构 model/ 层（改动风险大）
- 更换数据库

阶段二：/plan（任务拆解）

## 任务 1：统一错误处理 [预估：2h]
**描述**：引入 pkg/errors 库，统一错误处理格式
**验收标准**：
- [ ] 所有错误都使用 errors.Wrap 来附加上下文
- [ ] 错误日志包含完整的堆栈信息
- [ ] HTTP 错误响应格式统一（JSON）

## 任务 2：为 handler/ 层补充单元测试 [预估：4h]
**描述**：为所有 HTTP 处理函数写单元测试
**验收标准**：
- [ ] 测试覆盖率 > 80%
- [ ] 使用 httptest 包来做 HTTP 测试
- [ ] 模拟数据库层（使用 mock）

阶段三：/build（增量重构）

// 任务 1：统一错误处理

// ❌ 修改前
func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    user, err := userService.GetUser(id)
    if err != nil {
        http.Error(w, err.Error(), 500)  // 错误信息泄露给客户端
        return
    }
    json.NewEncoder(w).Encode(user)
}

// ✅ 修改后
func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    user, err := userService.GetUser(id)
    if err != nil {
        // 1. 记录完整错误信息（包含堆栈）
        log.Error(errors.Wrap(err, "failed to get user").Error())
        // 2. 返回通用错误信息给客户端
        http.Error(w, `{"error":"internal server error"}`, 500)
        return
    }
    json.NewEncoder(w).Encode(user)
}

阶段四：/test（验证）

# 运行测试
cd myproject && go test ./... -cover

# 输出：
ok      myproject/handler    0.234s  coverage: 82.3% of statements
ok      myproject/service    0.187s  coverage: 85.1% of statements

# 性能测试
vegeta attack -duration=30s -rate=100/s -targets=targets.txt | vegeta report
# 输出：
Latency 99th percentile: 95ms ✅ (目标 < 100ms)

与其他方案的深度对比

方案对比矩阵

为什么 Agent Skills 比 Manual Prompt 强？

# Manual Prompt 方式（弱约束）
prompt = """
你是一个资深工程师，写代码时请注意：
1. 先写测试
2. 做好错误处理
"""

# AI 的响应：
"好的！我会注意这些的。"
# 然后继续「假装」听了，但实际该跳过的还是跳过。

# ==========

# Agent Skills 方式（强约束）
# Skill 中有明确的 Checkpoint：

"""
执行流程：
步骤 1：写测试
  - Checkpoint: 运行 pytest，确认测试失败（红）
  - 如果 Checkpoint 不通过，停止执行。

步骤 2：实现功能
  - Checkpoint: 运行 pytest，确认测试通过（绿）
  - 如果 Checkpoint 不通过，停止执行。
"""

# AI 无法跳过，因为每个步骤都有明确的「检查点」

局限性与未来方向

当前局限性

未来演进方向（2026-2027）

1. Skill 市场（Skill Marketplace）：开发者可以发布和分享自己的 Skill
2. 跨工具标准化：推动 Agent Skills 成为行业标准格式
3. Skill 自动生成：从「人工编写 Skill」进化到「AI 自动生成 Skill」
4. 多 Agent 协作：一个 Skill 可以委托给多个专门的 Agent

总结：AI 编程的下一个范式转移

Agent Skills 的历史地位

1970s-1980s：文本编辑器（Vi, Emacs）
1990s-2000s：IDE（Visual Studio, Eclipse）
2010s：包管理器 + Linter + CI/CD（工程化工具链）
2020s（早期）：AI 辅助编程（Copilot）—— 代码补全
2020s（中期）：AI 对话编程（Claude Code, Cursor）—— 理解需求
2020s（晚期）：AI 工程化编程（Agent Skills）—— 工程纪律 ⬅ 我们在这里

核心洞察

Agent Skills 的真正价值不在于「让 AI 写代码更快」，而在于：

1. 将资深工程师的「隐性知识」显性化（Codification）
2. 将工程最佳实践固化为「可执行的工作流」（Operationalization）
3. 让 AI 从「代码生成器」升级为「工程助手」（Promotion）

给开发者的建议

立即上手：

git clone https://github.com/addyosmani/agent-skills.git ~/.claude/skills/

渐进采用：

1. 第一周：只用 /spec 和 /plan（学会先想清楚再做）
2. 第二周：加入 /build 和 /test（学会 TDD）
3. 第三周：加入 /review 和 /ship（学会代码审查和安全生产）

自定义 Skill：
根据你的团队规范，修改或新增 Skill。

参考资源

• Agent Skills GitHub：https://github.com/addyosmani/agent-skills
• Addy Osmani 博客：https://addyosmani.com/blog/
• Claude Code 文档：https://docs.anthropic.com/claude-code

本文撰写于 2026 年 6 月，基于 Agent Skills 最新版本。

喜欢这篇文章？

• ⭐ 给 Agent Skills 点个 Star
• 💬 在评论区分享你用 AI 编程的「翻车现场」
• 🔗 分享给你的团队

（全文完，约 18000 字）