squirrel-dev

name	squirrel-dev
description	本文档定义了 Skill 的设计与开发规范，旨在帮助开发者构建高命中率、高稳定性的 Skill 能力模块。 Use when this capability is needed.
metadata	{"author":"go-squirrel"}

Skill 编写规范

1. 概述

本文档定义了 Skill 的设计与开发规范，旨在帮助开发者构建高命中率、高稳定性的 Skill 能力模块。

1.1 什么是 Skill

一个 Skill 是一份清晰、严谨、可执行的指令文档，用于明确告诉模型——在什么条件下（When），按照哪些步骤（How），产出什么结果（What）。

1.2 常见认知误区

误区	说明
Skill 等同于一段 Prompt	Skill 是可长期复用、输入输出明确的能力模块，强调稳定、确定且易于工程化维护。Prompt 更偏向临时性、探索性和即兴交互
Skill 是写给人看的文档	Skill 的目标是下达指令，应使用模型可解析的结构化语言，明确约束行为边界
Skill 越复杂越强大	职责单一、边界清晰的 Skill 更容易被正确触发并稳定执行。复杂度与能力强度不挂钩

2. 设计标准与原则

2.1 元数据规范

Skill 的元数据（name 和 description）是模型发现和识别 Skill 的入口，直接影响触发准确率。

name 字段

用于识别 Skill，应遵循以下规范：

• 简洁、唯一的标识符
• 使用小写字母、数字和连字符（-）
• 推荐使用动名词（Gerund form）
• 长度不超过 64 个字符

✅ 好的例子：

• running-tests
• deploy-microservice
• database-migration

❌ 坏的例子：

• test-helper（语义模糊）
• data-skill-v2（冗余且含版本信息）
• deployService（命名不规范）

description 字段

用于描述 Skill 的能力及适用场景，应遵循以下规范：

• 使用第三人称，从模型视角描述
• 包含核心功能与触发时机的关键词
• 长度不超过 1024 个字符

✅ 好的例子：

"Review code for quality, correctness, and maintainability. Use when evaluating pull requests, refactoring existing code, or when the user asks for feedback on implementation details, edge cases, or potential bugs."

❌ 坏的例子：

• "I can help you review code"（第一人称）
• "Helps with code review"（缺乏触发时机）

2.2 指导方式的自由度分级

根据任务复杂度与容错要求，合理控制对模型的约束强度。

自由度等级	适用场景	指导方式	示例
高	存在多种有效方法；模型的决策依赖上下文	提供启发式策略（给原则）	代码审查：先看安全性，再看可读性
中	存在首选模式；允许一定程度的变通；行为受配置参数影响	提供模板/伪代码（给框架）	报告生成：按"摘要-分析-建议"结构
低	操作脆弱且易错；一致性至关重要；必须遵循特定序列	提供可执行的脚本（给代码）	数据库迁移：按固定顺序执行脚本

3. Skill 文件结构

3.1 基本结构

---
name: skill-name
description: Skill 的能力描述及适用场景
---

# Skill 标题

## 触发条件（When）

描述在什么情况下应该使用此 Skill。

## 执行步骤（How）

描述执行任务的具体步骤或原则。

## 输出结果（What）

描述期望的输出格式和内容。

3.2 高自由度示例

---
name: code-review
description: 当用户需要对代码进行审核时，基于代码实现与通用开发规范，分析逻辑正确性、可维护性和潜在风险，并给出改进建议。
---

# 代码审查

## 审查原则

1. 首先关注安全性问题
2. 其次关注代码可读性
3. 最后关注性能优化

## 审查要点

- 逻辑正确性
- 边界条件处理
- 错误处理机制
- 代码复用性

3.3 中自由度示例

---
name: report-generator
description: 当用户需要生成报告时，按照"摘要-分析-建议"的结构整理信息，输出清晰、条理化的报告内容。
template: |
  摘要：
  - 简要概述核心信息或问题点

  分析：
  - 详细分析背景、原因、数据或逻辑
  - 列出关键发现和关联因素

  建议：
  - 针对分析结果提出具体可行的改进方案或行动建议
  - 如有优先级或风险提示，可附上

3.4 低自由度示例

---
name: database-migration
description: 当用户需要执行数据库迁移时，按预定义顺序执行 SQL 或迁移脚本，确保数据和结构一致性。
template: |
  迁移计划：
  1. 准备阶段：
     - 备份现有数据库
     - 验证目标环境配置
  2. 执行阶段：
     - 按顺序执行迁移脚本
     - 验证每步执行结果
  3. 验证阶段：
     - 检查数据完整性
     - 验证应用功能正常

4. 编写最佳实践

4.1 职责单一原则

每个 Skill 应专注于单一职责，避免承担过多功能。

✅ 推荐：

• running-tests：执行测试
• fixing-lint-errors：修复 lint 错误
• generating-docs：生成文档

❌ 不推荐：

• dev-helper：开发助手（职责模糊）
• code-processor：代码处理器（范围过广）

4.2 最小必要信息原则

Skill 文档应以最小必要信息为目标，避免冗余解释与不必要的背景铺垫。

提示模型的上下文窗口是有限且宝贵的公共资源，每一个被加载的 Skill 都在竞争有限的上下文资源。

4.3 触发条件明确原则

触发条件应具体、可识别，避免模糊描述。

✅ 推荐：

当用户请求执行单元测试、集成测试，或使用 "test"、"测试" 等关键词时触发。

❌ 不推荐：

当需要测试时触发。

5. 可维护与可扩展

为了确保 Skill 在长期运行中保持稳定、易用且可持续拓展，需要从信息结构、工作流设计和脚本可靠性三个维度进行规划。

5.1 渐进式披露

SKILL.md 应当作为 Skill 的入口和导航，而不是一个包罗万象的大文件。详细的参考资料、示例、脚本或文档应拆分成独立文件，从而减轻模型初次加载的负担，让信息按需流动。

信息架构原则

一个 Skill 的目录可以随着功能扩展逐步演化：从单一文件演化为由多个参考文件和脚本组成的结构。通过渐进式披露，模型能快速抓住核心信息，再深入了解细节。

最佳实践

• 保持 SKILL.md 简洁：主体内容尽量控制在 500 行以内，只包含必要信息
• 避免深度嵌套：所有引用文件最好直接由 SKILL.md 链接，保持一层引用深度，避免链式引用（A → B → C），防止模型只读取部分内容
• 为长文件添加目录：对于超过 100 行的参考文件，在文件顶部添加一个目录（Table of Contents），帮助模型快速了解文件结构

示例

# SKILL.md

## 基础用法

描述如何触发 CI/CD 流水线：
- 检查 PR 状态
- 执行单元测试
- 更新 PR 测试状态

## 高级功能

详细说明请参见 `ci-advanced-features.md`：
- 并行执行多分支测试
- 条件触发不同类型的测试
- 自定义失败处理策略

## API 参考

所有方法与参数说明请参见 `ci-api-reference.md`：
- startPipeline(prId: string, branch: string)
- getPipelineStatus(pipelineId: string)
- cancelPipeline(pipelineId: string)

5.2 工作流与反馈闭环

对于包含多个步骤、且中间结果会影响最终质量的复杂任务，仅提供最终目标是不够的。必须显式定义工作流和检查清单，引导模型按步骤执行，并在关键节点建立 "验证 → 修正 → 再验证" 的反馈闭环。

工作流负责约束任务执行顺序，检查清单负责追踪任务的执行状态和质量。两者结合可以显著降低遗漏和跑偏的风险。

分析类任务的工作流

即使不涉及代码，分析类任务同样适合使用工作流。检查清单可以帮助模型明确以下信息：当前做到哪一步、是否可以进入下一步。

## 技术方案评估工作流

在开始执行前复制以下清单，并在每一步完成后显式标记状态。

- Step 1：明确业务目标与技术约束（性能、成本、时限）
- Step 2：列出所有可行的技术方案
- Step 3：从复杂度、可维护性、风险角度逐一评估
- Step 4：对关键差异点进行对比分析；(反馈闭环) 若发现关键信息不足，应返回 Step 2 或 Step 3 补充分析
- Step 5：给出结论性建议，并说明取舍理由；(反馈闭环) 若结论无法支撑目标约束，应重新审视 Step 1 的前提条件

代码类任务的工作流

代码类任务往往伴随不可逆或影响范围较大的操作，例如重构、依赖升级或配置变更。通过 "计划 → 验证 → 执行" 模式，可以有效降低误操作风险。

## 依赖版本升级工作流

- Step 1（Plan）：
  - 识别需要升级的依赖及当前版本
  - 阅读目标版本的 Release Notes 与 Breaking Changes
- Step 2（Plan）：
  - 更新依赖配置文件（如 package.json / go.mod）
  - 标注可能受影响的模块
- Step 3（Validate）：
  - 执行依赖冲突检查与静态构建（运行 dependency_check.sh）
  - 确认无版本冲突或构建失败
  - (反馈闭环) 若校验失败，必须回退到 Step 2 调整依赖配置
- Step 4（Execute）：
  - 安装新版本依赖
  - 运行完整测试集
- Step 5（Validate）：
  - 检查核心功能是否受影响
  - 对比升级前后的构建与运行结果
  - (反馈闭环) 若出现回归问题，应回滚升级并记录风险点

5.3 可执行脚本的加固原则

当 Skill 依赖可执行脚本时，脚本的健壮性应始终优先于代码的巧妙性。

Skill 本身不会理解或阅读你的代码逻辑，它只感知输入与输出。一旦脚本行为不可预测，模型就只能猜测，最终导致不稳定或错误的调用结果。因此，脚本必须做到：失败可预期、输出可理解、参数可解释。

显式处理错误，而不是让模型猜

不要将异常直接抛给模型处理。脚本应覆盖常见错误场景，并将技术异常转化为可理解、可决策的输出。

实践要点：

• 捕获常见异常（如文件缺失、权限不足、配置错误）
• 为每类错误返回清晰的错误原因和下一步建议

示例：

ERROR: Config file not found: ./deploy.yaml
HINT: Please check whether the file path is correct or run init-config.sh to generate a default config.

输出自解释的日志与验证结果

脚本的输出本身就是模型的上下文。一个好的脚本不仅说明发生了什么，还说明为什么会这样，以及接下来可以怎么做。

实践要点：

• 成功路径和失败路径都要有明确输出
• 验证类脚本应明确列出通过项与失败项

示例：

CHECK FAILED: Node.js version mismatch
- Required: >= 18.0.0
- Detected: 16.14.0

VALID OPTIONS:
1. Upgrade Node.js to a supported version
2. Switch to a compatible build image

避免魔法数字，让参数有来由

脚本中的常量（如 TIMEOUT = 30）如果缺乏解释，模型和人都无法判断它是否合理。任何影响行为的数值，都应该是可解释、可调整的。

实践要点：

• 为常量添加语义化名称
• 说明数值来源或设计依据
• 必要时允许通过参数覆盖默认值

示例：

TIMEOUT_SECONDS = 30  # Wait up to 30s because service startup usually completes within 10–20s

或在输出中体现：

INFO: Waiting for service to become healthy (timeout: 30s)

6. 反模式检查清单

在编写 Skill 时，应避免以下反模式：

反模式	问题	改进建议
名称过于宽泛	难以被正确识别	使用具体的动名词，如 running-tests
描述缺乏触发时机	命中率低	明确说明在什么场景下使用
步骤过于复杂	执行不稳定	拆分为多个职责单一的 Skill
包含冗余背景信息	浪费上下文	只保留必要的指令信息
使用第一人称	不符合规范	使用第三人称描述
输出格式不明确	结果不可预期	明确指定输出结构

7. 迭代优化流程

7.1 评测驱动

1. 定义测试用例：为 Skill 设计典型输入和期望输出
2. 执行评测：验证 Skill 在各种场景下的表现
3. 分析失败案例：识别触发失败或执行错误的原因
4. 迭代优化：根据评测结果调整 Skill 内容

7.2 失败优先

优先关注失败案例，分析失败原因：

• 触发失败：检查 name 和 description 是否准确
• 执行错误：检查步骤描述是否清晰
• 输出不符：检查输出格式定义是否明确

8. 注意事项

1. 避免版本信息：Skill 名称中不应包含版本号，版本管理应由外部系统处理
2. 保持稳定性：频繁修改 Skill 会导致行为不稳定，应谨慎变更
3. 文档同步：修改 Skill 后应及时更新相关文档
4. 测试验证：重大变更前应进行充分测试

---

Source: go-squirrel/squirrel-dev — distributed by TomeVault.