# Squirrel Dev

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

- Skill: `tomevault-io/squirrel-dev` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/squirrel-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/squirrel-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/squirrel-dev

---

# 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 基本结构

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

# Skill 标题

## 触发条件（When）

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

## 执行步骤（How）

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

## 输出结果（What）

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

### 3.2 高自由度示例

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

# 代码审查

## 审查原则

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

## 审查要点

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

### 3.3 中自由度示例

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

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

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

### 3.4 低自由度示例

```yaml
---
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），帮助模型快速了解文件结构

#### 示例

```markdown
# 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 工作流与反馈闭环

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

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

#### 分析类任务的工作流

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

```markdown
## 技术方案评估工作流

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

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

#### 代码类任务的工作流

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

```markdown
## 依赖版本升级工作流

- 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）如果缺乏解释，模型和人都无法判断它是否合理。任何影响行为的数值，都应该是可解释、可调整的。

实践要点：

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

示例：

```bash
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](https://github.com/go-squirrel/squirrel-dev) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-21 -->