enhance-skills

enhance-skills

分析技能定义的触发质量、结构和可发现性。

工作流

1. 发现 - 查找所有 SKILL.md 文件
2. 解析 - 提取 frontmatter 和内容
3. 检查 - 根据以下知识运行所有模式检查
4. 筛选 - 应用确定性筛选
5. 报告 - 生成 Markdown 输出
6. 修复 - 如果存在 --fix 标志，则应用自动修复

---

技能知识参考

Frontmatter 字段（完整参考）

字段	必需	描述	验证
name	否	显示名称，默认为目录名称	小写，最多 64 个字符
description	推荐	技能的作用及使用时机	最多 1024 个字符，应包含触发条件
argument-hint	否	自动补全提示，例如 [file-path]	少于 30 个字符
disable-model-invocation	否	true = 仅手动调用（用于有副作用的操作）	布尔值，默认 false
user-invocable	否	false = 在 / 菜单中隐藏（仅自动调用）	布尔值，默认 true
allowed-tools	否	Claude 无需许可即可使用的工具	逗号分隔的列表
model	否	技能激活时使用的特定模型	opus、sonnet、haiku
context	否	fork = 在隔离的子 Agent 上下文中运行	fork 或省略
agent	否	执行所用的子 Agent 类型	Explore、Plan、general-purpose
hooks	否	限定于技能的生命周期钩子	PreToolUse、PostToolUse

目录结构

skills/my-skill/
├── SKILL.md           # Required - core definition (under 500 lines)
├── reference.md       # Optional - detailed documentation
├── examples.md        # Optional - usage examples
└── scripts/           # Optional - helper scripts
    └── helper.py

存储位置：

• 企业：托管设置
• 个人：~/.claude/skills/<name>/SKILL.md
• 项目：.claude/skills/<name>/SKILL.md

调用控制模式

仅手动（用于有副作用的技能）：

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

后台知识（仅自动调用，在菜单中隐藏）：

---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---

完整访问（默认 - 自动和手动均可）：

---
name: review
description: Use when user asks to review code. Checks quality and security.
---

触发短语

description 应包含触发上下文，以便自动发现：

• “当用户提出……时使用”
• “在……时使用”
• “在……时调用”

良好示例： "当用户要求‘审查代码’、‘检查 PR’或‘代码审查’时使用" 不佳示例： "审查代码"（没有触发上下文）

动态上下文注入

技能可以使用反引号语法注入动态内容：

---
name: pr-summary
description: Summarize PR changes
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

规则：

• 使用 !，后接反引号括起的命令
• 每个技能最多 3 次注入
• 每次注入都会占用上下文预算

字符串替换

变量	描述
$ARGUMENTS	调用时传入的所有参数
${CLAUDE_SESSION_ID}	当前会话 ID

上下文预算

• 技能描述的默认限制约为 15,000 个字符
• 超出限制的内容会被截断
• 使用 /context 命令检查
• 通过以下方式增加：SLASH_COMMAND_TOOL_CHAR_BUDGET=30000

子 Agent 执行

使用 context: fork 时：

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

Agent 类型：

Agent	用途	工具访问权限
Explore	只读代码库探索	仅 Read、Grep、Glob
Plan	侧重规划的推理	Read、分析工具
general-purpose	完整能力	所有工具

限定于技能的钩子

---
name: secure-operations
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

工具限制

使用限定范围的工具模式以确保安全：

模式	含义
Bash(git:*)	仅 git 命令
Bash(npm:*)	仅 npm 命令
Bash(gh:*)	仅 GitHub CLI
Read(src/**)	仅 src/ 中的文件

---

检测模式

1. Frontmatter 验证（高确定性）

必需：

• 使用 --- 分隔符的 YAML frontmatter
• name 字段（小写，最多 64 个字符）
• description 字段（最多 1024 个字符）

推荐：

• 用于跟踪的 version 字段
• 接受输入的技能应设置 argument-hint
• 用于安全控制的 allowed-tools
• 需要特定模型时设置 model

标记：

• 缺少 frontmatter 分隔符
• 字段值无效（名称含大写字母，description 超过 1024 个字符）

2. 触发质量（高确定性）

检查： 描述包含触发短语 触发模式： “Use when”、“Invoke when”、“Use when user asks”

标记：

• 描述缺少触发上下文
• 描述含糊，例如“有用的工具”或“能做点事”

3. 调用控制（高确定性）

检查： 为有副作用的技能提供保护

标记：

• 名称中包含 deploy/ship/publish，但未设置 disable-model-invocation
• 危险的自动调用技能（可能被意外触发）

4. 工具限制（高确定性）

检查： 工具的范围设置适当

标记：

• 未受限制的 Bash（应为 Bash(git:*) 或类似范围）
• 只读技能使用 Write/Edit
• 研究技能使用 Task 工具

5. 内容范围（中等确定性）

指南：

• SKILL.md 少于 500 行
• 大量内容放在 references/ 子目录中
• 最多 3 个动态注入

标记：

• SKILL.md 超过 500 行
• 超过 3 个 !backtick`` 注入
• 嵌入了大型示例（移至 examples.md）

6. 结构质量（中等确定性）

推荐章节：

• 用途/概述
• 必需的检查或工作流步骤
• 输出格式
• 示例（复杂时）

7. 上下文配置（中等确定性）

检查： 上下文设置是否合适

标记：

• 有 context: fork，但未指定 agent 类型
• 指定了 agent 类型，但没有 context: fork
• agent 类型与允许使用的工具不匹配

8. 反模式（低确定性）

• 描述含糊，未指定具体触发条件
• 职责过多（应拆分为多个技能）
• 明显需要输入的技能缺少 argument-hint
• 冗余的思维链指令（现代模型不需要“逐步思考”）

---

自动修复实现

1. 缺少 frontmatter

---
name: skill-name
description: "Use when..."
version: 4.2.0
---

2. 缺少触发短语

在描述前添加“Use when user asks...”前缀

3. 未受限制的 Bash

将 Bash 替换为 Bash(git:*) 或适当的范围

---

输出格式

## Skill Analysis: {skill-name}

**File**: {path}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Frontmatter Issues ({n})
| Issue | Fix | Certainty |

### Trigger Issues ({n})
| Issue | Fix | Certainty |

### Invocation Issues ({n})
| Issue | Fix | Certainty |

### Tool Issues ({n})
| Issue | Fix | Certainty |

### Scope Issues ({n})
| Issue | Fix | Certainty |

---

模式统计

类别	模式数	可自动修复
Frontmatter	5	2
触发条件	2	1
调用	3	1
工具	3	1
范围	3	0
结构	2	0
上下文	3	0
反模式	4	0
总计	25	5

---

### 示例：缺少触发短语

<bad_example>

name: code-review
description: "Reviews code for issues"

不好的原因：没有用于自动发现的触发上下文。 </bad_example>

<good_example>

name: code-review
description: "Use when user asks to 'review code', 'check this PR'. Reviews code for issues."

好的原因：明确的触发短语有助于自动发现。 </good_example>

示例：危险的自动调用

<bad_example>

name: deploy
description: "Deploys code to production"

不好的原因：有副作用的技能可能被意外自动调用。 </bad_example>

<good_example>

name: deploy
description: "Deploy to production environment"
disable-model-invocation: true

好的原因：仅手动调用可防止意外部署。 </good_example>

示例：未受限制的工具

<bad_example>

name: git-helper
allowed-tools: Bash

不好的原因：不受限制的 Bash 可以运行任何命令。 </bad_example>

<good_example>

name: git-helper
allowed-tools: Bash(git:*)

好的原因：仅限于 git 命令。 </good_example>

示例：过大的技能

<bad_example>

# Complex Analysis
[800 lines of detailed instructions]

不好的原因：大型技能会占用上下文预算（上限为 15K 字符）。 </bad_example>

<good_example>

# Complex Analysis
Core instructions here (under 500 lines).
For details, see `references/detailed-guide.md`.

好的原因：核心技能简洁，详细信息放在单独文件中。 </good_example>

示例：上下文/Agent 不匹配

<bad_example>

name: researcher
context: fork
# Missing agent type

不好的原因：使用分叉上下文却未指定 Agent 类型。 </bad_example>

<good_example>

name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob

好的原因：Agent 类型与允许使用的工具相匹配（Explore = 只读）。 </good_example>

---

限制

• 仅对高确定性问题应用自动修复
• 评估触发质量时，考虑技能的上下文
• 绝不删除内容，只提出改进建议
• 根据上方嵌入的知识参考进行验证