在 Windsurf 中落地 agent-skills：用 .windsurfrules 承载工程技能的完整配置指南

agent-skills 是一组面向 AI 编码代理的"生产级工程技能包"，其中 docs/windsurf-setup.md 专门说明了如何在 Windsurf 中加载这些技能：项目级通过 .windsurfrules 规则文件组合关键技能，全局级通过 Settings → AI → Global Rules 跨项目生效。本文完整继承该文档的搭建步骤与配置模板，并结合仓库中三个被推荐技能的 SKILL.md 实际内容、references/ 检查清单和上下文工程原则，解释为什么 Windsurf 场景下要"少而精"地装载技能，以及如何在具体开发阶段按需追加技能与清单。

背景：Windsurf 为什么走"规则文件"路线

agent-skills 中的每个技能都是一个 Markdown 工作流文件（skills/<name>/SKILL.md），内置流程步骤、验证门槛、反合理化话术表和红旗清单。不同工具的加载方式不同：Claude Code 走插件市场，Cursor 走 .cursor/skills/ 加短规则，Codex 走原生插件。而 Windsurf 的机制是把技能内容放进它自己的规则配置体系，这也是 README.md 中 Windsurf 一节的结论："Add skill contents to your Windsurf rules configuration"。

仓库的 skills/context-engineering/SKILL.md 中给出了各工具规则文件的等价映射，可以佐证 .windsurfrules 在体系中的位置：

• .cursorrules 或 .cursor/rules/*.md（Cursor）
• .windsurfrules（Windsurf）
• .github/copilot-instructions.md（GitHub Copilot）
• AGENTS.md（OpenAI Codex）

也就是说，.windsurfrules 扮演的是"Level 1 常驻规则文件"的角色——每个会话都会进入上下文的稳定指令源。这一性质直接决定了后文的配置原则：常驻文件必须克制。

项目级配置：把关键技能拼进 .windsurfrules

Windsurf 用 .windsurfrules 存放项目专属的代理指令。官方给出的做法是：把最重要的几个技能文件用 --- 分隔符串联成一个合并规则文件。原始命令如下（docs/windsurf-setup.md Setup 一节）：

# Create a combined rules file from your most important skills
cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .windsurfrules
echo "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md >> .windsurfrules
echo "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .windsurfrules

实际操作时，把 /path/to/agent-skills 替换为你的本地克隆路径（git clone https://github.com/addyosmani/agent-skills.git），在目标项目根目录执行即可。执行后 .windsurfrules 的结构是三段完整的技能工作流，由 --- 分隔，Windsurf 会将其作为项目级指令整体注入。

为什么推荐这三个技能

这三个技能不是随意挑选的，它们分别覆盖"构建"与"评审"两个最容易出质量漏洞的环节，且体量可控（以当前仓库实测行数为据）：

技能	文件	规模	核心机制
test-driven-development	skills/test-driven-development/SKILL.md	398 行	RED-GREEN-REFACTOR 循环；修 bug 先写复现测试（Prove-It Pattern）；"测试是证据，'seems right' 不算完成"
incremental-implementation	skills/incremental-implementation/SKILL.md	249 行	薄垂直切片：实现→测试→验证→提交→下一片；纵向切片、契约先行切片、风险优先切片三种策略
code-review-and-quality	skills/code-review-and-quality/SKILL.md	396 行	五轴评审（正确性/可读性/架构/安全/性能）+ 合并前必审的准入门槛

三者组合起来形成闭环：TDD 保证每次改动的行为被测试证明，增量实现保证每次提交的系统状态可用，代码评审保证合并前过五轴检查。从源码内容看，TDD 技能的第一步就要求"先探测仓库自身的测试命令，绝不默认 npm test"，增量技能明确要求"任何多文件改动都走切片循环"，评审技能则规定"任何变更合并前都要评审——没有例外"，三者之间的触发条件互不重叠、天然衔接。

全局规则：跨项目复用的技能

对于希望在所有项目中都生效的技能，Windsurf 提供全局规则入口，操作步骤（docs/windsurf-setup.md Global Rules 一节）：

1. 打开 Windsurf → Settings → AI → Global Rules
2. 粘贴你最常用的技能内容

全局规则与 .windsurfrules 的区别在于作用域：前者随账户/环境跨所有项目生效，后者随项目仓库提交、只对当前项目生效。实践中常见分工是——通用纪律类技能（如 TDD）放全局，项目强相关的约定（如"本项目的切片粒度、提交规范"）放 .windsurfrules。需要注意 .windsurfrules 是项目文件，提交进版本库后团队成员共享同一套代理指令，这一点与 Git 协作语义一致。

推荐配置：把 .windsurfrules 控制在 2～3 个技能

文档给出的核心建议是：.windsurfrules 保持聚焦，只放 2-3 个关键技能，以留在上下文限额内。官方模板：

# .windsurfrules
# Essential agent-skills for this project

[Paste test-driven-development SKILL.md]

---

[Paste incremental-implementation SKILL.md]

---

[Paste code-review-and-quality SKILL.md]

这里的"上下文限额"约束并非经验之谈，而是与仓库自身的上下文工程原则一致。skills/context-engineering/SKILL.md 明确指出规则文件是 Level 1 常驻上下文，"Don't load all skills at once — it wastes context"（docs/getting-started.md 中的 Context-Aware Loading 一节持同样观点）。技能包总量为 25 个技能，若全部塞进 .windsurfrules，不仅挤占上下文窗口，还会稀释关键指令的权重。因此该文档的策略是：常驻文件只留"质量缺口最大"的技能，其余技能改为按需注入（下一节）。

一个可推断的取舍依据：常驻的三个技能合计约 1000 行 Markdown，而完整技能包还有 skills/security-and-hardening/SKILL.md（513 行）这样体量的文件——这解释了为什么安全类技能更适合"对话中临时粘贴"而非常驻。

使用技巧：选择性装载与按需注入

文档的 Usage Tips 给出三条实战原则，逐条展开：

1. Be selective — 按最大质量缺口选技能

Windsurf 的上下文有限，技能选择应针对"你最缺什么"。可以参照 docs/getting-started.md 的推荐分档：

• 最小集（新手起步）：spec-driven-development + test-driven-development + code-review-and-quality，覆盖"定义—证明—把关"三个关键环节；
• 全生命周期（成熟团队）：按阶段加载——立项时 spec-driven-development → planning-and-task-breakdown，开发中 incremental-implementation + test-driven-development，合并前 code-review-and-quality + security-and-hardening，部署前 shipping-and-launch。

由于 Windsurf 无法像插件体系那样自动发现技能，"按阶段加载"落到 Windsurf 上就是手动切换 .windsurfrules 内容或在对话中粘贴。

2. Reference in conversation — 按阶段临时粘贴技能

做特定阶段的工作时，把对应技能内容直接粘进聊天。文档举例：构建认证模块时粘贴 security-and-hardening。对应到仓库，skills/security-and-hardening/SKILL.md 覆盖 OWASP Top 10 预防、认证模式、密钥管理、依赖审计和三层边界体系，正是"处理用户输入、鉴权、数据存储、外部集成"时的完整工作流——这类阶段性强、体量大（513 行）的技能，临时粘贴比常驻更经济。

同理，其他阶段可临时注入的技能包括：

• 写 UI 时粘贴 skills/frontend-ui-engineering/SKILL.md（组件架构、设计系统、WCAG 2.1 AA 无障碍）
• 调试时粘贴 skills/debugging-and-error-recovery/SKILL.md（五步分诊：复现、定位、最小化、修复、加护栏）
• 设计 API 时粘贴 skills/api-and-interface-design/SKILL.md（契约先行、Hyrum's Law、单版本规则）

3. Use references as checklists — 把检查清单当核对单

粘贴 references/security-checklist.md 并要求 Windsurf 逐项核对。该清单是仓库中 7 个补充清单之一，共 205 行，结构上就是可勾选的核对单：Threat Modeling（从信任边界、资产识别、STRIDE 开始）、Pre-Commit Checks（含 git diff --cached | grep -i "password\|secret\|api_key\|token" 这类可执行检查）、Authentication、Authorization（防 IDOR）、Input Validation、Security Headers、CORS、Data Protection、Dependency Security、AI/LLM Security、Error Handling、OWASP Top 10 速查。

同目录可用的其他清单可按需换用：

清单	适用场景	与技能的关系
references/testing-patterns.md	写测试时的结构与反模式参考	配合 test-driven-development
references/security-checklist.md	提交前安全核对	配合 security-and-hardening
references/performance-checklist.md	Core Web Vitals 目标与前后端性能项	配合 performance-optimization
references/accessibility-checklist.md	键盘导航、读屏、ARIA、测试工具	配合 frontend-ui-engineering
references/definition-of-done.md	全项目统一的"完成"标准	配合所有技能

这种"技能常驻 + 清单临时"的组合，恰好复现了仓库"渐进式披露"（Progressive Disclosure）的设计理念：SKILL.md 是入口，补充材料只在需要时加载，从而把 token 开销压到最低（README.md "How Skills Work" 一节）。

验证配置是否生效

配置完成后，没有专门的命令行校验，但可以按以下信号验证：

1. 规则已注入：新开一个 Windsurf 会话，让代理执行一个小改动，观察它是否主动提到"先写一个会失败的测试"（TDD 技能的 RED 步骤措辞）或把改动拆成切片（增量技能的语言）。
2. 切片纪律生效：给一个多文件任务，代理应表现出"实现一小块→跑测试→提交"的节奏，而不是一次性铺出大段代码——这是 skills/incremental-implementation/SKILL.md 中"When you're tempted to write more than ~100 lines before testing"触发的典型行为。
3. 评审门槛生效：要求代理合并一个改动前自评，它应对照五轴（正确性、可读性与简洁、架构、安全、性能）逐项过一遍，并引用"只有当改动确定提升整体代码健康度时才批准"的准入门槛。

若代理完全没有任何上述行为，通常说明 .windsurfrules 未被识别（检查文件是否位于项目根目录、是否为 Windsurf 当前生效的规则文件位置），回到 Setup 一节重新生成。

小结

Windsurf 的集成路径本质上是"用规则文件承载技能"：.windsurfrules 常驻 2-3 个核心技能（TDD、增量实现、代码评审），全局规则收纳跨项目纪律，阶段性强或体量大的技能（如安全加固）在对话中临时粘贴，references/ 下的清单则作为逐项核对的检查单按需注入。整套配置的关键不在装了多少，而在于让常驻上下文始终装的是当前质量缺口最大的工作流——这正是 docs/windsurf-setup.md 三条 Usage Tips 的共同指向。