enhance-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

enhance-skills

技能增强

Analyze skill definitions for trigger quality, structure, and discoverability.

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

Workflow

工作流

Discover - Find all SKILL.md files
Parse - Extract frontmatter and content
Check - Run all pattern checks against knowledge below
Filter - Apply certainty filtering
Report - Generate markdown output
Fix - Apply auto-fixes if --fix flag present

发现 - 查找所有SKILL.md文件
解析 - 提取frontmatter和内容
检查 - 基于以下知识库运行所有模式检查
过滤 - 应用置信度过滤
报告 - 生成markdown输出
修复 - 如果传入--fix参数则自动修复问题

Skill Knowledge Reference

技能知识库参考

Frontmatter Fields (Complete Reference)

Frontmatter字段（完整参考）

Field	Required	Description	Validation
`name`	No	Display name, defaults to directory name	lowercase, max 64 chars
`description`	Recommended	What skill does and when to use	max 1024 chars, should include trigger
`argument-hint`	No	Autocomplete hint, e.g., `[file-path]`	keep under 30 chars
`disable-model-invocation`	No	`true` = manual only (for side effects)	boolean, default false
`user-invocable`	No	`false` = hidden from `/` menu (auto-only)	boolean, default true
`allowed-tools`	No	Tools Claude can use without permission	comma-separated list
`model`	No	Specific model when skill is active	opus, sonnet, haiku
`context`	No	`fork` = run in isolated subagent context	fork or omit
`agent`	No	Subagent type for execution	Explore, Plan, general-purpose
`hooks`	No	Skill-scoped lifecycle hooks	PreToolUse, PostToolUse

字段	必填	描述	校验规则
`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

Directory Structure

目录结构

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

Storage Locations:

Enterprise: Managed settings
Personal:
```
~/.claude/skills/<name>/SKILL.md
```
Project:
```
.claude/skills/<name>/SKILL.md
```

skills/my-skill/
├── SKILL.md           # 必填 - 核心定义（不超过500行）
├── reference.md       # 可选 - 详细文档
├── examples.md        # 可选 - 使用示例
└── scripts/           # 可选 - 辅助脚本
    └── helper.py

存储位置:

企业版: 托管设置中
个人版:
```
~/.claude/skills/<name>/SKILL.md
```
项目级:
```
.claude/skills/<name>/SKILL.md
```

Invocation Control Patterns

调用控制模式

Manual Only (for skills with side effects):

yaml

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

Background Knowledge (auto-only, hidden from menu):

yaml

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

Full Access (default - both auto and manual):

yaml

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

仅手动调用（适用于有副作用的技能）:

yaml

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

背景知识库（仅自动调用，菜单隐藏）:

yaml

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

完全访问（默认 - 支持自动和手动调用）:

yaml

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

Trigger Phrases

触发短语

Description should include trigger context for auto-discovery:

"Use when user asks..."
"Use when..."
"Invoke when..."

Good:

"Use when user asks to 'review code', 'check PR', or 'code review'"

Bad:

"Reviews code"

(no trigger context)

描述中应包含用于自动发现的触发上下文：

"Use when user asks..."
"Use when..."
"Invoke when..."

正面示例:

"Use when user asks to 'review code', 'check PR', or 'code review'"

反面示例:

"Reviews code"

（无触发上下文）

Dynamic Context Injection

动态上下文注入

Skills can inject dynamic content using backtick syntax:

yaml

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

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

yaml

---
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
```


**Rules:**
- Use `!` followed by backtick-wrapped command
- Limit to 3 injections per skill
- Each injection adds to context budget

PR diff: !
```
gh pr diff
```
PR comments: !
```
gh pr view --comments
```
Changed files: !
```
gh pr diff --name-only
```


**规则:**
- 使用 `!` 加反引号包裹的命令
- 每个技能最多3个注入项
- 每个注入项会占用上下文额度

String Substitutions

字符串替换

Variable	Description
`$ARGUMENTS`	All arguments passed when invoking
`${CLAUDE_SESSION_ID}`	Current session ID

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

Context Budget

上下文额度

Skill descriptions have ~15,000 character default limit
Content beyond limit is truncated
Check with
```
/context
```
command
Increase via:
```
SLASH_COMMAND_TOOL_CHAR_BUDGET=30000
```

技能描述默认有~15000字符上限
超出上限的内容会被截断
可使用
```
/context
```
命令查询额度
可通过环境变量调整:
```
SLASH_COMMAND_TOOL_CHAR_BUDGET=30000
```

Subagent Execution

子Agent执行

When using

context: fork

yaml

---
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 Types:

Agent	Purpose	Tool Access
`Explore`	Read-only codebase exploration	Read, Grep, Glob only
`Plan`	Planning-focused reasoning	Read, analysis tools
`general-purpose`	Full capabilities	All tools

使用

context: fork

时：

yaml

---
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`	规划类推理	支持读、分析类工具
`general-purpose`	全功能场景	所有工具

Skill-Scoped Hooks

技能级钩子

yaml

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

yaml

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

Tool Restrictions

工具权限限制

Use scoped tool patterns for security:

Pattern	Meaning
`Bash(git:*)`	Only git commands
`Bash(npm:*)`	Only npm commands
`Bash(gh:*)`	Only GitHub CLI
`Read(src/**)`	Only files in src/

使用作用域工具模式保障安全：

模式	含义
`Bash(git:*)`	仅允许git命令
`Bash(npm:*)`	仅允许npm命令
`Bash(gh:*)`	仅允许GitHub CLI命令
`Read(src/**)`	仅允许读取src/目录下的文件

Detection Patterns

检测规则

1. Frontmatter Validation (HIGH Certainty)

1. Frontmatter校验（高置信度）

Required:

YAML frontmatter with
```
---
```
delimiters
```
name
```
field (lowercase, max 64 chars)
```
description
```
field (max 1024 chars)

Recommended:

```
version
```
field for tracking
```
argument-hint
```
for skills accepting input
```
allowed-tools
```
for security
```
model
```
when specific model required

Flag:

Missing frontmatter delimiters
Invalid field values (uppercase name, description >1024 chars)

必填项:

用
```
---
```
包裹的YAML frontmatter
```
name
```
字段（小写，最多64字符）
```
description
```
字段（最多1024字符）

推荐项:

```
version
```
字段用于版本追踪
接收输入的技能需配置
```
argument-hint
```
配置
```
allowed-tools
```
保障安全
需要指定模型时配置
```
model
```

问题标记:

缺少frontmatter分隔符
字段值无效（name大写、description超过1024字符）

2. Trigger Quality (HIGH Certainty)

2. 触发质量校验（高置信度）

Check: Description includes trigger phrase Trigger patterns: "Use when", "Invoke when", "Use when user asks"

Flag:

Description without trigger context
Vague descriptions like "Useful tool" or "Does stuff"

检查项: 描述包含触发短语 触发模式: "Use when", "Invoke when", "Use when user asks"

问题标记:

描述无触发上下文
模糊描述例如"Useful tool"或"Does stuff"

3. Invocation Control (HIGH Certainty)

3. 调用控制校验（高置信度）

Check: Side-effect skills are protected

Flag:

Skills with deploy/ship/publish in name but
```
disable-model-invocation
```
not set
Dangerous auto-invocable skills (can accidentally trigger)

检查项: 有副作用的技能已做保护

问题标记:

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

4. Tool Restrictions (HIGH Certainty)

4. 工具权限校验（高置信度）

Check: Tools are appropriately scoped

Flag:

Unrestricted
```
Bash
```
(should be
```
Bash(git:*)
```
or similar)
Read-only skills with Write/Edit
Research skills with Task tool

检查项: 工具权限已合理设置作用域

问题标记:

无限制的
```
Bash
```
权限（应配置为
```
Bash(git:*)
```
或其他限定范围）
只读技能配置了Write/Edit权限
调研类技能配置了Task工具权限

5. Content Scope (MEDIUM Certainty)

5. 内容范围校验（中等置信度）

Guidelines:

SKILL.md under 500 lines
Large content in
```
references/
```
subdirectory
Max 3 dynamic injections

Flag:

SKILL.md over 500 lines
More than 3
```
!
```
backtick`` injections
Embedded large examples (move to examples.md)

规范:

SKILL.md不超过500行
大体积内容放入
```
references/
```
子目录
最多3个动态注入项

问题标记:

SKILL.md超过500行
超过3个
```
!
```
反引号注入项
嵌入大段示例（应移动到examples.md）

6. Structure Quality (MEDIUM Certainty)

6. 结构质量校验（中等置信度）

Recommended Sections:

Purpose/overview
Required checks or workflow steps
Output format
Examples (if complex)

推荐模块:

用途/概述
必要检查或工作流步骤
输出格式
示例（复杂技能适用）

7. Context Configuration (MEDIUM Certainty)

7. 上下文配置校验（中等置信度）

Check: Context settings are appropriate

Flag:

```
context: fork
```
without
```
agent
```
type
```
agent
```
type without
```
context: fork
```
Mismatch between agent type and allowed-tools

检查项: 上下文配置合理

问题标记:

配置了
```
context: fork
```
但未指定
```
agent
```
类型
指定了
```
agent
```
类型但未配置
```
context: fork
```
Agent类型和allowed-tools不匹配

8. Anti-Patterns (LOW Certainty)

8. 反模式（低置信度）

Vague descriptions without specific triggers
Too many responsibilities (should split into multiple skills)
Missing
```
argument-hint
```
for skills that clearly need input
Redundant chain-of-thought instructions (modern models don't need "think step by step")

无具体触发条件的模糊描述
职责过多（应拆分为多个技能）
需要输入的技能未配置
```
argument-hint
```
冗余的思维链指令（现代模型不需要"think step by step"这类提示）

Auto-Fix Implementations

自动修复实现

1. Missing frontmatter

1. 缺失frontmatter

yaml

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

yaml

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

2. Missing trigger phrase

2. 缺失触发短语

Add "Use when user asks..." prefix to description

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

3. Unrestricted Bash

3. 无限制Bash权限

Replace

Bash

with

Bash(git:*)

or appropriate scope

将

Bash

替换为

Bash(git:*)

或其他合适的作用域

Output Format

输出格式

markdown

undefined

markdown

undefined

Skill Analysis: {skill-name}

File: {path}

Summary

HIGH: {count} issues
MEDIUM: {count} issues

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 |

---

| Issue | Fix | Certainty |

---

Pattern Statistics

规则统计

Category	Patterns	Auto-Fixable
Frontmatter	5	2
Trigger	2	1
Invocation	3	1
Tool	3	1
Scope	3	0
Structure	2	0
Context	3	0
Anti-Pattern	4	0
Total	25	5

分类	规则数量	支持自动修复
Frontmatter	5	2
Trigger	2	1
Invocation	3	1
Tool	3	1
Scope	3	0
Structure	2	0
Context	3	0
Anti-Pattern	4	0
总计	25	5

Example: Missing Trigger Phrase

示例：缺失触发短语

<bad_example>

yaml

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

Why it's bad: No trigger context for auto-discovery. </bad_example>

<good_example>

yaml

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

Why it's good: Clear trigger phrases enable auto-discovery. </good_example>

<bad_example>

yaml

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

问题原因: 无自动发现所需的触发上下文。 </bad_example>

<good_example>

yaml

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

优势: 清晰的触发短语支持自动发现。 </good_example>

Example: Dangerous Auto-Invocation

示例：危险的自动调用配置

<bad_example>

yaml

name: deploy
description: "Deploys code to production"

Why it's bad: Side-effect skill could be auto-invoked accidentally. </bad_example>

<good_example>

yaml

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

Why it's good: Manual-only prevents accidental deployments. </good_example>

<bad_example>

yaml

name: deploy
description: "Deploys code to production"

问题原因: 有副作用的技能可能被意外自动触发。 </bad_example>

<good_example>

yaml

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

优势: 仅支持手动调用避免意外部署。 </good_example>

Example: Unrestricted Tools

示例：无限制的工具权限

<bad_example>

yaml

name: git-helper
allowed-tools: Bash

Why it's bad: Unrestricted Bash allows any command. </bad_example>

<good_example>

yaml

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

Why it's good: Scoped to only git commands. </good_example>

<bad_example>

yaml

name: git-helper
allowed-tools: Bash

问题原因: 无限制的Bash权限允许执行任意命令。 </bad_example>

<good_example>

yaml

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

优势: 限定仅允许执行git命令。 </good_example>

Example: Oversized Skill

示例：技能体积过大

<bad_example>

markdown

undefined

<bad_example>

markdown

undefined

Complex Analysis

[800 lines of detailed instructions]

**Why it's bad**: Large skills consume context budget (15K char limit).
</bad_example>

<good_example>
```markdown

[800 lines of detailed instructions]

**问题原因**: 大体积技能会消耗上下文额度（15K字符上限）。
</bad_example>

<good_example>
```markdown

Complex Analysis

Core instructions here (under 500 lines). For details, see

references/detailed-guide.md

**Why it's good**: Core skill is concise; details in separate files.
</good_example>

Core instructions here (under 500 lines). For details, see

references/detailed-guide.md

**优势**: 核心技能内容简洁，详细内容放入单独文件。
</good_example>

Example: Context/Agent Mismatch

示例：上下文/Agent配置不匹配

<bad_example>

yaml

name: researcher
context: fork

<bad_example>

yaml

name: researcher
context: fork

Missing agent type

**Why it's bad**: Fork context without specifying agent type.
</bad_example>

<good_example>
```yaml
name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob

Why it's good: Agent type matches allowed tools (Explore = read-only). </good_example> </examples>

**问题原因**: 配置了fork上下文但未指定Agent类型。
</bad_example>

<good_example>
```yaml
name: researcher
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob

优势: Agent类型和允许使用的工具匹配（Explore为只读类型）。 </good_example> </examples>

Constraints

约束

Only apply auto-fixes for HIGH certainty issues
Consider skill context when evaluating trigger quality
Never remove content, only suggest improvements
Validate against embedded knowledge reference above

仅对高置信度问题执行自动修复
评估触发质量时需考虑技能上下文
不得删除内容，仅可提出改进建议
基于上述内置知识库执行校验