accelint-skill-manager

技能管理器

创建技能时绝对不要做的事

• 绝对不要编写讲解基础知识的教程——假设 Claude 已经了解标准概念、库和模式。专注于只有专家才掌握的知识。
• 绝对不要把触发信息放在正文中——“何时使用”指南只能放在描述字段中。正文会在激活决策后加载。
• 绝对不要把所有内容都塞进 SKILL.md——采用渐进式披露：在 SKILL.md 中放入核心工作流（理想情况下少于 500 行），详细内容放在 references/ 中，按需加载。
• 绝对不要使用泛泛的警告——“小心”和“避免错误”毫无用处。请提供具体的反模式，并说明具体原因。
• 绝对不要对所有任务都采用相同的自由度——创意领域（设计、架构）需要较高自由度和原则指导；脆弱的操作（文件格式、API）需要较低自由度和精确脚本。
• 绝对不要解释标准操作——假设 Claude 知道如何读取文件、编写代码和使用常见库。专注于不明显的决策和边缘情况。
• 绝对不要加入显而易见的流程——“第 1 步：打开文件，第 2 步：编辑，第 3 步：保存”是在浪费令牌。只加入 Claude 不会了解的领域专属工作流。
• 绝对不要省略反模式章节——它包含了一半的专家知识。缺少“绝对不要做的事”的技能，就缺少了它的价值所在：专家从惨痛教训中学到的经验。
• 绝对不要编写含糊的描述——“用于 X 的技能”会导致误触发和漏触发。描述必须包含用户实际会说的具体触发短语。
• 绝对不要混淆创建和审核事项——创建技能、重构技能和审核技能是不同的工作流。每种工作流的输入、输出和成功标准都不同。

创建技能前，请先自问

应用以下测试，确保技能确实能带来价值：

知识增量测试

• 这是否涵盖了专家需要多年才能学会的知识？ 如果是在解释基础知识或标准库的用法，那就是多余的。
• 我是在向 Claude 解释，还是在为 Claude 充实能力？ 技能应该为 Agent 提供专家知识，而不是教它们概念。
• 每个段落是否都值得占用上下文空间？ 令牌效率很重要——上下文空间还要与系统提示词、对话历史和其他技能共享。

激活效益

• 描述是否说明了是什么、何时使用，并包含关键词？ 含糊的描述会导致技能永远无法激活。
• 只看描述的 Agent 能否准确判断何时使用该技能？ 如果不明确，该技能就形同隐形。

自由度校准

• 如果 Agent 犯错，会有什么后果？ 后果越严重，自由度就应越低（精确脚本）；后果越轻，自由度就应越高（原则指导）。
• 是否只有一种正确做法，还是有多种有效方法？ 只有一种做法时，应明确规定；有多种方法时，应提供指导和示例。

令牌效率

• 能否在不丢失专家知识的前提下压缩内容？ 按需加载参考资料可以节省上下文。
• 是否有可以改写为脚本的重复流程？ 可复用代码应放在 scripts/ 中，而不是在指令中反复出现。

使用方法

此技能采用渐进式披露，以尽量减少上下文用量：

1. 从工作流开始（SKILL.md）

按照以下 4 步工作流创建或重构技能。

2. 查阅实现细节（AGENTS.md）

加载 AGENTS.md，了解文件系统约定、命名模式和结构规则。

3. 按需加载特定参考文件

下面的每个工作流步骤都会说明需要加载哪些参考文件。只加载当前步骤所需的文件：

• 目录结构 → references/file-system.md
• 描述字段规范 → references/skill.md
• AGENTS.md 模式 → references/agents.md
• 渐进式披露规则 → references/progressive-disclosure.md
• 参考文件格式 → references/references.md
• 脚本规范 → references/scripts.md
• 资源指南 → references/assets.md
• CHANGELOG 维护 → references/changelog.md

请勿一次性加载所有参考文件——只加载与你当前步骤相关的文件。

应遵循哪个工作流？

根据任务选择：

• 从头创建新技能 → 遵循技能创建工作流（步骤 1-4）
• 改进现有技能 → 跳转到步骤 4（编辑技能）
• 审查技能质量 → 遵循技能审查工作流

技能创建工作流

要创建或重构技能，请按顺序遵循“技能创建工作流”，只有在明确不适用时才跳过步骤。

复制此检查清单以跟踪进度：

- [ ] Step 1: Understanding - Gather concrete examples of skill usage
- [ ] Step 2: Planning - Identify reusable scripts, references, assets
- [ ] Step 3: Initializing - Check existing skills, create directory structure
- [ ] Step 4: Editing - Write agent-focused content with procedural knowledge and update CHANGELOG

在总结中说明应用了此技能中的哪些规则，以及应用原因。

步骤 1：通过具体示例了解技能

仅当已清楚了解技能的使用模式时，才跳过此步骤。即使处理的是现有技能，此步骤仍然很有价值。

要创建有效的技能，需要清楚了解该技能的具体使用方式。这些理解可以来自用户直接提供的示例，也可以来自经过用户反馈验证的生成示例。

示例：构建图像编辑器技能时，询问：

• “需要哪些功能？编辑、旋转，还是其他功能？”
• “有哪些使用示例？”
• “触发短语有哪些：‘去除红眼’、‘旋转图像’——还有其他的吗？”

先提出 2-3 个具体问题（功能、示例、触发短语），然后根据用户的回答继续追问，而不是一开始就提出所有问题。

当已明确技能应支持哪些功能时，结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请针对每个示例进行分析：

1. 考虑如何从头开始完成该示例
2. 确定反复执行这些工作流时，哪些脚本、参考文件和资源会有所帮助

示例：

• 针对“旋转此 PDF”的 pdf-editor 技能 → 保存 scripts/rotate-pdf.sh，避免每次都重写代码
• 针对“构建一个待办事项应用”的 frontend-app-builder 技能 → 保存 assets/hello-world/ 样板模板
• 针对“今天有多少用户登录？”的 big-query 技能 → 保存包含表结构的 references/schema.md

分析每个具体示例，列出可复用资源：脚本、参考文件和资源。

步骤 3：初始化技能

必须执行：创建目录结构前，先加载 references/file-system.md。

对于新技能： 复制 assets/skill-template/ 中的模板作为起点，并进行自定义。

对于要重构的现有技能： 直接跳转到步骤 4——该技能已存在。

创建前，检查是否有重叠的现有技能：

ls -la .claude/skills 2>/dev/null || echo "No project skills found"
ls -la ~/.claude/skills 2>/dev/null || echo "No global skills found"

如果存在相关技能，请简要提及：“我找到了 [列表]——是否应将其中任何技能纳入或合并？”

遵循 AGENTS.md 和参考文件中的目录结构与命名规范。

第 4 步：编辑 Skill

必须执行：加载 references/skill.md，了解 description 字段规范和 frontmatter 规则。

编辑（新生成或现有的）Skill 时，请记住，这个 Skill 是为另一个 Agent 实例创建的。重点纳入能为 Agent 提供帮助且不易显而易见的信息。考虑哪些流程知识、领域特定细节或可复用资源能帮助另一个 Agent 实例更有效地完成这些任务。

根据任务脆弱性调整自由度：

任务类型	自由度	指导形式	示例
创意／设计	高自由度	原则、思维模式、反模式	“采用大胆的美学风格”
代码审查	中等自由度	附示例的指南、决策框架	“优先级：安全性 > 逻辑 > 性能”
文件操作	低自由度	精确脚本、具体步骤、不允许变通	“使用确切命令：pandoc --flag”

判断标准：“如果 Agent 犯错，后果是什么？”

• 后果严重（文件损坏、数据丢失）→ 低自由度，使用精确脚本
• 后果中等（代码欠佳、风格问题）→ 中等自由度，提供示例
• 后果轻微（美学选择、存在多种有效方法）→ 高自由度，提供原则

如果要更新现有 Skill，可参考 assets/skill-template/ 中的模板，以进行较大的结构调整并保持一致性。保持一致至关重要，因此应倾向于大幅重新排版，以确保符合规范。

更新现有 Skill 时，请确保提升 frontmatter 中的 metadata.version 值。如果变更范围较大，则进行主版本升级，如 1.0 → 2.0；否则进行次版本升级，如 1.0 → 1.1。

版本控制：

• 主版本（1.0 → 2.0）： 大幅重写、破坏性变更、彻底重构
• 次版本（1.0 → 1.1）： 新增章节、重要补充、内容完善
• 修订版本（1.0.0 → 1.0.1）： Bug 修复、错别字修正（可选的第三位版本号）

CHANGELOG 维护： 更新 Skill 后，请使用 “Keep a Changelog” 格式更新或创建 CHANGELOG.md：

# Changelog

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features/capabilities with rationale

### Changed
- Modifications with why (always include rationale)

### Fixed
- Bug fixes with explanation

### Version
- Version bump note

记录变更内容及其原因——说明理由对后续维护者至关重要。如果改进源于测试，请链接到评估结果。CHANGELOG 版本必须与 frontmatter 中的 metadata.version 一致。

Skill 审计工作流

审计或审查现有 Skill（而非从头创建）时，请遵循以下结构化流程：

1. Frontmatter 审计

根据要求检查每个字段：

• name：使用小写字母，仅含连字符，不超过 64 个字符，并与目录名称一致
• description：以 “Use when” 开头，包含 WHAT／WHEN／KEYWORDS，并包含具体的触发短语
• license：必须存在（可选，但建议提供）
• metadata.version：必须存在、有意义，并与 CHANGELOG.md 的最新版本一致

2. 结构审计

对照预期章节检查：NEVER Do、Before [Action] Ask、How to Use、Main Workflow。注明缺少的章节。

3. CHANGELOG 和版本审计

检查 CHANGELOG.md 是否存在以及内容质量：

• 缺少 CHANGELOG： 标记为缺少文档
• 版本不匹配： 确认 CHANGELOG 最新版本与 frontmatter 的 metadata.version 一致
• 缺少理由： 确保变更说明包含 WHY，而不只是 WHAT
• 格式合规性： 检查是否符合 “Keep a Changelog” 结构
• 空章节： 确认 Added／Changed／Fixed 章节包含有意义的内容

4. 知识增量测试

针对每个内容块，询问：“Claude 已经知道这些内容了吗？”标记为 REDUNDANT 或 EXPERT-ONLY。计算冗余内容所占百分比。如果超过 50%，建议进行大幅修订。

5. 输出可执行的建议

• 按优先级排序，提供具体的改进建议
• 提供经过改进的 description（而非仅指出问题）
• 除审计报告外，还要提供改进后的 SKILL.md