Create Skill 扩展规则
这个技能扩展了内置的 create-skill 技能，提供额外的最佳实践和规则，帮助创建更高质量的 SKILL.md 文件。
核心原则
在创建 SKILL.md 时，始终遵循以下原则：
保持简洁
只包含代理需要知道但无法轻易推断的信息。代理已经很智能，避免过度解释。
✅ 好的示例:
## 使用 Vitest 测试
运行测试: `pnpm test`
测试文件必须放在 `__tests__` 目录
❌ 过于冗长:
## 使用 Vitest 测试
测试是软件开发的重要组成部分。我们使用 Vitest 作为测试框架，
因为它速度快且与 Vite 集成良好。Vitest 是由 Vite 团队开发的，
它提供了与 Jest 兼容的 API...
指导原则:
- 每个句子都应该有实际价值
- 删除显而易见的说明
- 专注于特定于项目的知识
- 避免教学式的解释
使用具体的命令
始终提供可直接执行的命令，而不是抽象描述。
✅ 具体: pnpm install、python scripts/validate.py
❌ 抽象: "安装项目依赖"、"运行验证脚本"
说明优先级
使用"必须"、"应该"、"可以"等词来表明重要性，帮助代理理解约束的严格程度。
## 代码风格
- **必须**: 使用 TypeScript strict 模式
- **应该**: 优先使用函数式组件
- **可以**: 使用 ESLint 自动修复小问题
优先级指南:
- 必须 - 不可违反的硬性要求
- 应该 - 强烈建议但有例外情况
- 可以 - 可选的改进建议
包含上下文
解释为什么某个规则很重要，而不仅仅是说明是什么。简短的原因说明能帮助代理做出更好的决策。
## 验证流程
- 所有 API 端点必须有集成测试（防止生产环境中断）
- 使用 `pnpm test:api` 运行 API 测试
利用层级结构
使用清晰的标题层级让代理能够快速定位相关信息。
好的层级示例:
# 主标题
## 主要部分
### 子部分
#### 详细说明（如需要）
使用相对路径引用文件
在 SKILL.md 中引用其他文件时，统一使用 Markdown 链接格式 [描述](相对路径)。
✅ 好的示例:
详见[setup.ts](./config/setup.ts)
查看[usage.md](./examples/usage.md)
使用[validate.py](./scripts/validate.py)
❌ 避免:
详见 `config/setup.ts`（缺少链接）
详见 C:\project\config\setup.ts（绝对路径）
详见 /home/user/project/config/setup.ts（绝对路径）
为什么重要:
- 链接可点击，方便代理和用户导航
- 相对路径跨平台兼容
- 保持文档的可移植性
避免操作系统特定的命令
在 SKILL.md 中提供命令时，使用跨平台的方式或工具无关的描述。
✅ 跨平台:
## 环境设置
- 创建配置文件 `.env`（复制 `.env.example` 的内容）
- 安装依赖: `pnpm install`
- 运行脚本: `node scripts/setup.js`
❌ 操作系统特定:
- 创建配置: `touch .env`（仅 Unix/Linux）
- 创建链接: `ln -s source target`（仅 Unix/Linux）
- 查看进程: `ps aux | grep node`（仅 Unix/Linux）
- 复制文件: `cp source dest`（仅 Unix/Linux）
- 移动文件: `mv old new`（仅 Unix/Linux）
避免使用有序编号
避免使用 1. 2. 3. 这样的有序标记，使用层级标题或无序列表代替，减少维护负担。
✅ 推荐做法:
## 部署流程
### 准备阶段
- 确保所有测试通过: `pnpm test`
- 更新版本号: `pnpm version`
### 构建阶段
- 构建生产版本: `pnpm build`
- 验证构建输出: `pnpm validate:build`
或使用无序列表:
## 核心要素
- **简洁性** - 只包含必要信息
- **具体性** - 提供可执行的命令
- **可用性** - 跨平台兼容
❌ 避免:
## 部署流程
1. 准备阶段
- 确保所有测试通过
- 更新版本号
2. 构建阶段
- 构建生产版本
- 验证构建输出
为什么重要:
- 插入新步骤时不需要重新编号所有后续项目
- 删除步骤不会造成编号断层
- 减少维护成本和出错风险
- 标题层级提供了更好的语义结构
例外情况:
- 如果顺序执行非常关键且需要明确强调步骤编号（如"严格按照步骤 1、2、3 执行"），可以使用有序编号
- 在代码块或示例输出中引用特定步骤时
命令格式规范
可执行命令的写法
提供命令时，使用代码块格式：
运行测试:
\`\`\`bash
pnpm test
\`\`\`
或内联格式: `pnpm test`
脚本调用的写法
如果技能包含 scripts/ 目录中的脚本，明确说明如何调用：
## 验证工具
运行验证:
\`\`\`bash
python scripts/validate.py input.json
\`\`\`
参数说明:
- `input.json` - 要验证的输入文件
示例模式的使用
当技能需要展示输出格式或代码模式时，使用具体的示例而非抽象描述。
输出格式示例
## 报告格式
使用以下结构:
\`\`\`markdown
# 分析报告
## 摘要
[一段话概述关键发现]
## 详细发现
- 发现一 - 具体数据支持
- 发现二 - 具体数据支持
## 建议
- 具体可执行的建议 1
- 具体可执行的建议 2
\`\`\`
代码模式示例
## 错误处理模式
使用此模式处理异步操作:
\`\`\`typescript
try {
const result = await operation();
return { success: true, data: result };
} catch (error) {
console.error('Operation failed:', error);
return { success: false, error: error.message };
}
\`\`\`
验证清单
创建或更新 SKILL.md 后，使用此清单验证质量：
内容质量
- 每个说明都简洁明了，无冗余
- 所有命令都是具体可执行的
- 使用了优先级词汇（必须/应该/可以）
- 重要规则包含了原因说明
- 标题层级清晰合理
技术规范
- 所有文件引用使用
[描述](相对路径)格式 - 避免了操作系统特定的命令（如
touch、ln、ps等） - 所有命令都跨平台兼容
格式规范
- Markdown 格式正确
- 代码块有正确的语言标记
- 示例代码完整可用
- 链接都有效
可用性
- 新手能够理解并遵循
- 有足够的示例支持
- 复杂概念有清晰的说明
- 避免了行话和假设
常见问题
何时需要提供命令的详细说明？
当命令的参数或行为不够直观时。例如：
运行特定测试:
\`\`\`bash
pnpm test -- --filter="auth\*"
\`\`\`
- `--filter` 参数支持 glob 模式
- 只运行匹配的测试文件
如何处理平台差异？
如果某个操作在不同平台上确实不同，提供描述而非命令：
## 环境设置
- 创建 `.env` 文件在项目根目录
- 复制 `.env.example` 的内容到 `.env`
- 根据你的环境修改配置值
SKILL.md 应该多详细？
遵循"最小必要信息"原则：
- 包含：项目特定的知识、非显而易见的约定、关键的上下文
- 排除：常识性内容、可以从代码推断的信息、过度的背景知识
如何组织复杂的工作流程？
使用清晰的子标题组织步骤：
## 部署流程
### 准备阶段
- 确保所有测试通过: `pnpm test`
- 更新版本号: `pnpm version`
### 构建阶段
- 构建生产版本: `pnpm build`
- 验证构建输出: `pnpm validate:build`
### 发布阶段
- 发布到 npm: `pnpm publish`
- 创建 Git tag: `git tag v$(node -p "require('./package.json').version")`
与内置 create-skill 技能的配合
此扩展技能与内置的 create-skill 技能互补：
- 内置技能: 提供 SKILL.md 的基本结构、元数据规范、文件组织
- 此扩展: 提供编写风格、命令格式、跨平台兼容性、质量标准
在创建技能时，先应用内置 create-skill 技能建立基础结构，然后应用此扩展技能确保内容质量和规范性。
总结
创建高质量的 SKILL.md 文件需要平衡以下要素：
- 简洁性 - 只包含必要信息
- 具体性 - 提供可执行的命令和清晰的示例
- 可用性 - 跨平台兼容、工具无关
- 结构化 - 清晰的层级和组织
- 上下文 - 解释原因而非只陈述事实
遵循这些规则，你的技能文档将能帮助代理更好地理解和执行任务。