AgentSkillsCN

create-skill-overrides

在内置 create-skill 技能的基础上，补充更多规则与最佳实践。当用户请求创建技能、编写 SKILL.md，或需要关于技能编写的指导时，在应用内置 create-skill 技能后，此技能可进一步补充额外的规则。

SKILL.md
--- frontmatter
name: create-skill-overrides
description: 扩展内置 create-skill 技能的额外规则和最佳实践。当用户请求创建 skill、编写 SKILL.md、或需要关于技能编写的指导时，在应用内置 create-skill 技能后使用此技能补充额外的规则。

Create Skill 扩展规则

这个技能扩展了内置的 create-skill 技能，提供额外的最佳实践和规则，帮助创建更高质量的 SKILL.md 文件。

核心原则

在创建 SKILL.md 时，始终遵循以下原则：

保持简洁

只包含代理需要知道但无法轻易推断的信息。代理已经很智能，避免过度解释。

✅ 好的示例:

markdown
## 使用 Vitest 测试

运行测试: `pnpm test`
测试文件必须放在 `__tests__` 目录

❌ 过于冗长:

markdown
## 使用 Vitest 测试

测试是软件开发的重要组成部分。我们使用 Vitest 作为测试框架，
因为它速度快且与 Vite 集成良好。Vitest 是由 Vite 团队开发的，
它提供了与 Jest 兼容的 API...

指导原则:

  • •每个句子都应该有实际价值
  • •删除显而易见的说明
  • •专注于特定于项目的知识
  • •避免教学式的解释

使用具体的命令

始终提供可直接执行的命令，而不是抽象描述。

✅ 具体: pnpm install、python scripts/validate.py

❌ 抽象: "安装项目依赖"、"运行验证脚本"

说明优先级

使用"必须"、"应该"、"可以"等词来表明重要性，帮助代理理解约束的严格程度。

markdown
## 代码风格

- **必须**: 使用 TypeScript strict 模式
- **应该**: 优先使用函数式组件
- **可以**: 使用 ESLint 自动修复小问题

优先级指南:

  • •必须 - 不可违反的硬性要求
  • •应该 - 强烈建议但有例外情况
  • •可以 - 可选的改进建议

包含上下文

解释为什么某个规则很重要，而不仅仅是说明是什么。简短的原因说明能帮助代理做出更好的决策。

markdown
## 验证流程

- 所有 API 端点必须有集成测试（防止生产环境中断）
- 使用 `pnpm test:api` 运行 API 测试

利用层级结构

使用清晰的标题层级让代理能够快速定位相关信息。

好的层级示例:

markdown
# 主标题

## 主要部分

### 子部分

#### 详细说明（如需要）

使用相对路径引用文件

在 SKILL.md 中引用其他文件时，统一使用 Markdown 链接格式 [描述](相对路径)。

✅ 好的示例:

markdown
详见[setup.ts](./config/setup.ts)
查看[usage.md](./examples/usage.md)
使用[validate.py](./scripts/validate.py)

❌ 避免:

markdown
详见 `config/setup.ts`（缺少链接）
详见 C:\project\config\setup.ts（绝对路径）
详见 /home/user/project/config/setup.ts（绝对路径）

为什么重要:

  • •链接可点击，方便代理和用户导航
  • •相对路径跨平台兼容
  • •保持文档的可移植性

避免操作系统特定的命令

在 SKILL.md 中提供命令时，使用跨平台的方式或工具无关的描述。

✅ 跨平台:

markdown
## 环境设置

- 创建配置文件 `.env`（复制 `.env.example` 的内容）
- 安装依赖: `pnpm install`
- 运行脚本: `node scripts/setup.js`

❌ 操作系统特定:

markdown
- 创建配置: `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. 这样的有序标记，使用层级标题或无序列表代替，减少维护负担。

✅ 推荐做法:

markdown
## 部署流程

### 准备阶段

- 确保所有测试通过: `pnpm test`
- 更新版本号: `pnpm version`

### 构建阶段

- 构建生产版本: `pnpm build`
- 验证构建输出: `pnpm validate:build`

或使用无序列表:

markdown
## 核心要素

- **简洁性** - 只包含必要信息
- **具体性** - 提供可执行的命令
- **可用性** - 跨平台兼容

❌ 避免:

markdown
## 部署流程

1. 准备阶段
   - 确保所有测试通过
   - 更新版本号

2. 构建阶段
   - 构建生产版本
   - 验证构建输出

为什么重要:

  • •插入新步骤时不需要重新编号所有后续项目
  • •删除步骤不会造成编号断层
  • •减少维护成本和出错风险
  • •标题层级提供了更好的语义结构

例外情况:

  • •如果顺序执行非常关键且需要明确强调步骤编号（如"严格按照步骤 1、2、3 执行"），可以使用有序编号
  • •在代码块或示例输出中引用特定步骤时

命令格式规范

可执行命令的写法

提供命令时，使用代码块格式：

markdown
运行测试:

\`\`\`bash
pnpm test
\`\`\`

或内联格式: `pnpm test`

脚本调用的写法

如果技能包含 scripts/ 目录中的脚本，明确说明如何调用：

markdown
## 验证工具

运行验证:

\`\`\`bash
python scripts/validate.py input.json
\`\`\`

参数说明:

- `input.json` - 要验证的输入文件

示例模式的使用

当技能需要展示输出格式或代码模式时，使用具体的示例而非抽象描述。

输出格式示例

markdown
## 报告格式

使用以下结构:

\`\`\`markdown

# 分析报告

## 摘要

[一段话概述关键发现]

## 详细发现

- 发现一 - 具体数据支持
- 发现二 - 具体数据支持

## 建议

- 具体可执行的建议 1
- 具体可执行的建议 2
  \`\`\`

代码模式示例

markdown
## 错误处理模式

使用此模式处理异步操作:

\`\`\`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 格式正确
  • • 代码块有正确的语言标记
  • • 示例代码完整可用
  • • 链接都有效

可用性

  • • 新手能够理解并遵循
  • • 有足够的示例支持
  • • 复杂概念有清晰的说明
  • • 避免了行话和假设

常见问题

何时需要提供命令的详细说明？

当命令的参数或行为不够直观时。例如：

markdown
运行特定测试:

\`\`\`bash
pnpm test -- --filter="auth\*"
\`\`\`

- `--filter` 参数支持 glob 模式
- 只运行匹配的测试文件

如何处理平台差异？

如果某个操作在不同平台上确实不同，提供描述而非命令：

markdown
## 环境设置

- 创建 `.env` 文件在项目根目录
- 复制 `.env.example` 的内容到 `.env`
- 根据你的环境修改配置值

SKILL.md 应该多详细？

遵循"最小必要信息"原则：

  • •包含：项目特定的知识、非显而易见的约定、关键的上下文
  • •排除：常识性内容、可以从代码推断的信息、过度的背景知识

如何组织复杂的工作流程？

使用清晰的子标题组织步骤：

markdown
## 部署流程

### 准备阶段

- 确保所有测试通过: `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 文件需要平衡以下要素：

  • •简洁性 - 只包含必要信息
  • •具体性 - 提供可执行的命令和清晰的示例
  • •可用性 - 跨平台兼容、工具无关
  • •结构化 - 清晰的层级和组织
  • •上下文 - 解释原因而非只陈述事实

遵循这些规则，你的技能文档将能帮助代理更好地理解和执行任务。