文章目录

0. 【Claude基础】全部目录

1. Skills 设计哲学

1.1 命令行指令的局限性

CLAUDE.md，它能解决"每次启动都要重复说一遍项目规范"的问题。但用了一段时间你会发现，CLAUDE.md 有一个根本性矛盾：写得越全，加载越慢；写得越少，覆盖不够。

图片

假设你的团队有这些工作流：

  • PR 审查有一套 20 条评审清单

  • 安全扫描要跑 OWASP Top 10 检查

  • 发版前要根据 git log 生成 CHANGELOG

  • 数据库迁移要检查是否有锁表风险

把这些全塞进 CLAUDE.md，那个文件轻松超过 3000 行。每次启动 Claude Code，它都要把这 3000 行全部读一遍——哪怕你这次只是想改个 typo。这不仅浪费 token，还会让 Claude 在海量指令中迷失，降低执行质量。

另一个问题是隔离性。CLAUDE.md 里的所有指令对每次会话都生效。"PR 审查时检查测试覆盖率"这条规则，在你写代码时也会被 Claude 读到，虽然不会执行，但它占着上下文窗口。

Skills 就是为了解决这两个问题而设计的：按需加载，用到才读。

1.2 Skills vs CLAUDE.md 指令

在这里插入图片描述

简单说：CLAUDE.md 是"校规"，Skills 是"选修课教材"。校规人人都要读，教材只有选了那门课才发。

1.3 核心设计原则：渐进式加载

Skills 的加载是两阶段的：

阶段一：扫描 description。 Claude Code 启动时，会扫描所有已注册的 Skill 目录，只读取每个 SKILL.md 的 frontmatter 中的 description 字段。该字段总长度不超过 1536 字符，开销极小。

阶段二：按需加载完整内容。 当用户输入斜杠命令（如 /review-pr），或者 Claude 判断当前任务匹配某个 Skill 的 description 时，才会加载该 Skill 的完整 SKILL.md 内容、模板文件和脚本。

这就像一本书的目录和正文的关系。启动时只加载"目录"（description），确定需要哪一章之后，才翻到"正文"（完整 SKILL.md）。

1.4 上下文自动发现

除了手动用斜杠命令触发，Skills 还支持自动触发。当你在对话中说"帮我审查一下这个 PR"，Claude 会拿这句话去跟所有 Skill 的 description 做语义匹配。如果某个 Skill 的 description 写的是"审查 Pull Request，检查代码质量和安全问题"，匹配度足够高，Claude 就会自动加载并执行这个 Skill。

这个机制对 description 的质量要求很高——后面会详细讲怎么写好 description。

2. Skills 文件结构

2.1 目录组织规范

一个 Skill 的标准目录结构：

.claude/skills/<skill-name>/
├── SKILL.md           # 必需，技能定义文件
├── templates/         # 可选，提示词模板、输出模板
│   ├── review.md
│   └── report.md
└── scripts/           # 可选，辅助脚本
    ├── check.sh
    └── parse.py

SKILL.md 是唯一必需的文件。它包含 YAML frontmatter（元数据）和 Markdown 正文（具体指令）。

templates/ 目录放模板文件。比如 PR 审查的输出格式模板、变更日志的生成模板。Skill 正文中可以引用这些模板。

scripts/ 目录放辅助脚本。比如安全扫描的检查脚本、数据处理脚本。Skill 可以通过 !command 语法或指示 Claude 执行这些脚本。

命名规范：skill-name 使用小写字母 + 连字符，如 review-pr、security-scan、generate-changelog。

2.2 作用域层级

Skills 有三个作用域，从近到远：

项目级：.claude/skills/

放在项目根目录的 .claude/skills/ 下，随 Git 提交，团队所有人共享。适合团队工作流相关的 Skill，比如 PR 审查规范、部署检查清单。

my-project/
└── .claude/
    └── skills/
        ├── review-pr/
        │   └── SKILL.md
        └── deploy-check/
            └── SKILL.md

个人级：~/.claude/skills/

放在用户主目录下，跨项目生效，只有本人能用。适合个人习惯相关的 Skill，比如你自己的代码风格检查、个人笔记生成。

~/.claude/
└── skills/
    ├── my-code-style/
    │   └── SKILL.md
    └── note-taker/
        └── SKILL.md

插件级：通过 Plugin 分发

通过 Claude Code 的插件机制分发，可以从远程仓库安装。适合社区共享的通用 Skill。这个方式目前还在发展中，大多数情况下用项目级和个人级就够了。

优先级：当多个作用域存在同名 Skill 时，项目级 > 个人级 > 插件级。本地的优先于远程的。

3. SKILL.md Frontmatter 完全参考

SKILL.md 的核心是 YAML frontmatter。这里逐个字段讲解。

3.1 name — 技能标识符

---
name: review-pr
---

name 决定了斜杠命令的名称。上面的配置意味着你可以用 /review-pr 来触发这个 Skill。

命名规范：

  • 小写字母 + 连字符，不要用下划线或驼峰

  • 简短且具描述性：review-pr 比 do-pull-request-review 好

  • 避免跟内置命令冲突：不要用 help、clear、compact 这些已被占用的名字

如果省略 name，默认用目录名作为标识符。

3.2 description — 触发描述与匹配规则

---
name: review-pr
description: "审查 Pull Request 的代码变更，检查代码质量、安全漏洞和最佳实践"
---

description 有三个核心作用：

  1. 自动匹配依据：Claude 根据这个字段判断当前任务是否匹配该 Skill，包含触发场景、适用条件、排除规则

  2. 帮助信息：用户执行 /skills 或需要浏览可用技能时显示

  3. 启动加载唯一字段：Claude Code 启动时仅加载该字段，需严格控制长度

写好 description 的要点：

  • 动词开头：用"审查"、“检查”、“生成”、"分析"开头，明确动作

  • 包含关键词：把用户可能用到的关键词写进去。比如"PR"、“Pull Request”、"代码审查"都写上，增加匹配概率

  • 明确触发与排除规则：清晰说明什么场景下触发、什么场景不触发，提升匹配精准度

  • 不要太泛：写"审查 Pull Request 的代码变更"比"帮助处理代码相关工作"好得多

  • 严格控制长度：总字符数不能超过 1536 字符，超过部分会被截断，影响启动性能

正确的多行触发规则写法示例：

---
name: review-pr
description: |
  审查 Pull Request 的代码变更，检查代码质量、安全漏洞和最佳实践。
  触发场景：用户要求审查 PR、review 代码变更、检查 MR 时触发；用户提到 PR 编号（如 #123）、要求检查代码质量或安全问题时触发。
  排除场景：用户仅讨论 PR 流程而非要求执行审查、用户正在编写代码而非审查代码时，不触发。
---

3.3 allowed-tools — 工具访问控制

---
name: security-scan
allowed-tools:
  - Grep
  - Read
  - Bash(npm audit:*)
  - Bash(semgrep:*)
---

allowed-tools 限定了这个 Skill 能使用哪些工具。默认情况下 Skill 可以使用所有工具，但出于安全考虑，你可能想限制某些 Skill 的工具范围。

模式语法：

  • 工具名：直接写工具名，如 Grep、Read、Edit、Write、Bash、Glob

  • Bash 命令限定：Bash(command-prefix:*) 限制只能执行特定前缀的命令。Bash(npm audit:*) 意味着只能执行以 npm audit 开头的 Bash 命令

  • 通配符：* 表示匹配任意后缀

  • MCP 工具：mcp__server-name__tool-name 格式匹配 MCP 工具

实际使用建议：

  • 安全扫描类 Skill：限制为只读工具（Grep、Read），防止误修改

  • 代码生成类 Skill：允许 Edit、Write

  • 分析类 Skill：允许 Grep、Read、Bash（限定特定命令）

3.4 context: fork — 隔离执行

---
name: security-scan
context: fork
---

设置 context: fork 后，Skill 会在一个隔离的上下文中执行。它看不到当前会话的历史对话，执行完成后其内部对话也不会留在主会话中。

适用场景：

  • 重计算任务：安全扫描、全量测试等耗时操作，不希望产生的大量中间输出污染主会话

  • 独立分析：需要干净上下文的任务，不想被之前的对话影响判断

  • 并行执行：fork 模式的 Skill 可以在后台运行，不阻塞主会话

性能影响：fork 会创建一个新的 agent 线程，有一定的启动开销。对于简单的 Skill（几秒就能完成的），没必要用 fork。

3.5 disable-model-invocation — 禁止自动触发

---
name: dangerous-cleanup
description: "清理临时文件和构建产物"
disable-model-invocation: true
---

默认情况下，Claude 可能根据对话内容自动匹配并触发 Skill。如果你有一些危险操作的 Skill（比如删除文件、重置数据库），不想让它被自动触发，就设置 disable-model-invocation: true。

设了这个选项后，只能通过斜杠命令 /dangerous-cleanup 手动触发，Claude 不会自作主张去执行它。

3.6 paths — 目录限定

---
name: review-migration
paths:
  - "db/migrations/**"
  - "alembic/versions/**"
---

paths 用 YAML 列表指定 glob 模式，限定 Skill 只在特定目录的文件上生效。上面的例子意味着这个 Skill 只在数据库迁移目录的文件上工作。

这个字段主要影响自动触发的判断——当用户正在操作的文件匹配这些 path 时，Skill 更容易被自动触发。

3.7 effort — 推理深度控制

---
name: quick-lint
effort: low
---

effort 控制 Claude 执行这个 Skill 时的推理深度，可选值：

值 含义 适用场景
low 快速响应，浅层推理 格式检查、简单 lint、快速查询
medium 默认，平衡速度和深度 大多数任务
high 深度分析，更多推理步骤 复杂审查、安全扫描
max 最深推理，不计成本 架构分析、深度安全审计

选择建议：

  • 如果 Skill 的结果准确性很重要（安全审计、架构决策），用 high 或 max

  • 如果 Skill 是简单的模板填充或格式化工作，用 low 省 token

  • 不确定就不设，用默认的 medium

3.8 argument-hint — 自动补全提示

---
name: review-pr
argument-hint: "<PR编号> [审查级别]"
---

argument-hint 定义了自动补全时显示的参数提示。当用户输入 /review-pr 然后按 Tab 时，会看到 <PR编号> [审查级别] 的提示。

尖括号 <> 表示必填参数，方括号 [] 表示可选参数。这只是提示文本，不会做实际校验。

3.9 shell — 指定执行 Shell

---
name: windows-check
shell: powershell
---

shell 指定 !command 动态命令使用的 Shell。默认是 bash。如果你的 Skill 需要在 Windows 上用 PowerShell 执行命令，就设成 powershell。

4. 动态上下文注入

4.1 !command 语法详解

Skills 最强大的特性之一是动态上下文注入。在 SKILL.md 的正文中，你可以用 !command 语法嵌入命令，Skill 被加载时会自动执行这些命令，并把输出内联到上下文中。

语法格式：

## 当前分支信息

!git branch --show-current

## 最近 10 次提交

!git log --oneline -10

## PR 差异

!gh pr diff $0

每个 !command 行会被替换为命令的实际输出。Claude 看到的不是 !git branch --show-current，而是命令执行后的结果，比如 feature/user-auth。

4.2 实用示例

获取 Git 上下文：

## 当前 Git 状态

!git status --short
!git branch --show-current
!git log --oneline -5

获取 PR 信息：

## PR 详情

!gh pr view $0 --json title,body,files
!gh pr diff $0

获取项目依赖信息：

## 已知漏洞

!npm audit --json 2>/dev/null || echo "npm audit 未执行"

## 过期依赖

!npm outdated 2>/dev/null || echo "检查跳过"

获取测试状态：

## 最近测试结果

!npm test -- --reporter=min 2>&1 | tail -20

4.3 注意事项

执行超时：!command 有执行时间限制。如果命令执行时间过长（比如跑完整测试套件），会被超时终止。对于耗时命令，考虑用 timeout 包裹或限制输出：

!timeout 10 npm test -- --reporter=min 2>&1 | tail -20

输出过大：如果命令输出大量内容（比如完整的 npm audit JSON 报告），会浪费上下文窗口。用 head、tail、grep 过滤输出：

## 关键安全问题（仅高危以上）
!npm audit --json 2>/dev/null | jq '.vulnerabilities | to_entries[] | select(.value.severity == "high" or .value.severity == "critical")' | head -50

命令失败处理：如果命令执行失败，输出会包含错误信息。用 || echo "fallback" 提供降级方案，避免 Claude 看到一堆报错信息后困惑：

!gh pr diff $0 || echo "无法获取 PR diff，请确认 PR 编号是否正确"

参数引用：!command 中可以使用 $0、$1 等参数变量（下一节详细讲）。

5. 参数传递机制

5.1 $ARGUMENTS 与位置参数

当用户通过斜杠命令调用 Skill 时，可以传入参数：

/review-pr 456 high

Skill 可以通过以下变量接收参数：

变量 值 说明
$ARGUMENTS 456 high 完整输入字符串
$0 456 第一个位置参数
$1 high 第二个位置参数
$2 （空） 第三个位置参数（未提供）

位置参数按空格分割。$ARGUMENTS 保留完整的原始字符串，适合需要整体处理的场景。

5.2 在 SKILL.md 中使用参数

参数可以用在正文的任何位置，包括 !command 中：

---
name: review-pr
argument-hint: "<PR编号> [审查级别:normal|high|critical]"
---

# PR 审查

## PR 信息

!gh pr view $0 --json title,body,author,labels
!gh pr diff $0

## 审查要求

审查级别：$1（默认 normal）

根据上述 PR 变更内容进行审查，关注以下方面：
- 代码逻辑正确性
- 边界条件处理
- 错误处理是否完善

5.3 参数校验的最佳实践

SKILL.md 的 frontmatter 不提供参数校验功能，但你可以在正文中通过指令让 Claude 做校验：

## 参数校验

在执行审查之前，先检查以下条件：

1. `$0` 必须是一个数字（PR 编号）。如果不是数字，提示用户正确格式：`/review-pr <PR编号>`
2. `$1` 如果提供了，必须是 normal、high、critical 之一。如果不是，使用默认值 normal
3. 执行 `gh pr view $0` 验证 PR 是否存在。如果不存在，提示用户检查 PR 编号

这种方式利用 Claude 的自然语言理解能力做校验，比写正则表达式灵活得多。

6. 内置 Skill 解析

6.1 /less-permission-prompts

Claude Code 有一个内置 Skill：/less-permission-prompts。它的功能是扫描当前会话的历史记录，找出你在这次会话中批准过的所有工具调用，然后生成一份权限白名单配置。

使用场景：你在一个会话里反复批准了 Bash(npm test:*)、Edit、Write 等权限，每次都要点确认，很烦。执行 /less-permission-prompts 后，它会生成类似这样的配置建议：

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(git:*)",
      "Edit",
      "Write"
    ]
  }
}

你可以把这些规则加到 settings.json 里，下次就不用重复批准了。

6.2 从内置 Skill 学习设计模式

内置 Skill 的源码是学习 Skill 设计的好教材。它的设计模式有几个要点：

精准的 description：内置 Skill 的 description 包含了明确的触发关键词。“reduce permission prompts” 这个描述涵盖了用户可能说的"太多权限确认"、"减少弹窗"等变体，同时明确了适用场景，避免误触发。

渐进式执行：先分析（扫描历史），再建议（生成配置），最后确认（让用户决定是否应用）。不是一上来就改配置。

安全边界：生成的是建议，不是直接修改配置文件。让用户有最终决定权。

这三个模式——精准触发、渐进执行、安全边界——在你自己设计 Skill 时也应该遵循。

图片

7. 实战：创建常用 Skill

7.1 PR 审查技能

这个 Skill 自动拉取 PR 的 diff 和评论，按结构化清单输出审查意见。

---
name: review-pr
description: |
  审查 Pull Request (PR/MR) 的代码变更，检查代码质量、安全漏洞、性能问题和最佳实践，支持指定审查级别。
  触发场景：用户要求审查 PR、review 代码变更、检查 MR 时触发；用户提到 PR 编号、要求检查代码质量时触发。
  排除场景：用户仅讨论 PR 流程、编写代码而非执行审查时，不触发。
argument-hint: "<PR编号> [级别:normal|high|critical]"
allowed-tools:
  - Bash(gh:*)
  - Bash(git:*)
  - Grep
  - Read
  - Glob
effort: high
---

# PR 审查

## 参数处理

- PR 编号：$0（必需，如果为空则提示用户提供）
- 审查级别：$1（可选，默认 normal）
  - normal：常规检查
  - high：增加安全和性能审查
  - critical：逐行审查，不放过任何问题

## 获取 PR 上下文

!gh pr view $0 --json title,body,author,labels,baseRefName,headRefName 2>/dev/null || echo "ERROR: 无法获取 PR #$0，请确认编号是否正确"

### PR 变更文件

!gh pr diff $0 --name-only 2>/dev/null

### PR 已有评论

!gh api repos/{owner}/{repo}/pulls/$0/comments --jq '.[].body' 2>/dev/null | head -50

## 审查清单

请按以下清单逐项检查：

### 代码质量
- [ ] 函数职责是否单一，有没有超过 50 行的函数
- [ ] 变量命名是否清晰，有没有 `tmp`、`data`、`x` 这类模糊命名
- [ ] 是否有重复代码可以提取
- [ ] 错误处理是否完善，有没有吞掉异常
- [ ] 边界条件是否覆盖（空值、空数组、超大输入）

### 安全检查（high/critical 级别必查）
- [ ] 有没有 SQL 注入风险（字符串拼接 SQL）
- [ ] 有没有 XSS 风险（未转义的用户输入）
- [ ] 有没有硬编码的密钥、密码、token
- [ ] 文件操作有没有路径遍历风险
- [ ] 有没有不安全的反序列化

### 性能检查（high/critical 级别必查）
- [ ] 有没有 N+1 查询
- [ ] 循环内有没有数据库/网络调用
- [ ] 有没有未加索引的查询条件
- [ ] 大数据集有没有做分页

### 测试覆盖
- [ ] 新增功能是否有对应的测试
- [ ] 边界条件测试是否覆盖
- [ ] 是否有 mock/stub 的滥用

## 输出格式

按以下格式输出审查结果：

\```
## PR #$0 审查报告

### 概要
- 审查级别：[normal/high/critical]
- 变更文件数：X
- 风险评估：[低/中/高/严重]

### 问题清单

#### 🔴 必须修复（阻断合并）
1. [文件名:行号] 问题描述
   建议修复方案：...

#### 🟡 建议修改（不阻断但推荐）
1. [文件名:行号] 问题描述
   建议：...

#### 🟢 可选优化
1. [文件名:行号] 优化建议

### 总结
[一两句话总结本次审查的整体评价]
\```

7.2 安全扫描技能

这个 Skill 对项目代码做 OWASP Top 10 安全检查。

---
name: security-scan
description: |
  扫描项目代码中的安全漏洞，基于 OWASP Top 10 检查常见安全风险，包括注入、认证失效、敏感数据泄露等。
  触发场景：用户明确要求安全检查、漏洞扫描、安全审计时触发。
  排除场景：普通代码审查、仅提及安全关键词、修复已知安全问题时，不触发。
allowed-tools:
  - Grep
  - Read
  - Glob
  - Bash(grep:*)
  - Bash(find:*)
context: fork
effort: high
disable-model-invocation: true
---

# 安全漏洞扫描

## 扫描范围

扫描当前项目的所有源代码文件，跳过以下目录：
- node_modules/
- vendor/
- .git/
- dist/
- build/
- __pycache__/

## OWASP Top 10 检查清单

### A01: 失效的访问控制
搜索以下模式：
- 缺少权限检查的 API 端点
- 直接对象引用（用用户输入直接查询数据库记录）
- CORS 配置过于宽松（`Access-Control-Allow-Origin: *`）
- 目录遍历风险（路径中包含 `../` 或用户输入未过滤的路径拼接）

### A02: 加密机制失效
搜索以下模式：
- 使用 MD5、SHA1 做密码哈希（应该用 bcrypt/scrypt/argon2）
- 硬编码的密钥和密码（搜索 `password =`、`secret =`、`api_key =` 等）
- HTTP 而非 HTTPS 的 URL
- 禁用 SSL 校验（`verify=False`、`rejectUnauthorized: false`）

### A03: 注入
搜索以下模式：
- SQL 字符串拼接（`"SELECT * FROM " + `、f-string 中的 SQL）
- 命令注入（`os.system()`、`subprocess.call()` 使用 `shell=True`）
- 模板注入（未转义的变量插入 HTML）
- LDAP 注入、XML 注入等

### A04: 不安全设计
检查以下方面：
- 缺少速率限制的 API
- 没有验证码的登录/注册端点
- 缺少输入长度限制

### A05: 安全配置错误
搜索以下模式：
- 调试模式在生产配置中开启（`DEBUG = True`、`debug: true`）
- 默认凭据未修改
- 不必要的功能已启用
- 错误信息暴露堆栈跟踪

### A06: 自带缺陷和过时的组件
- 检查 package.json / requirements.txt 中是否有已知漏洞版本

### A07: 身份识别和身份验证失效
搜索以下模式：
- 弱密码策略（没有密码强度校验）
- 会话 token 在 URL 中传递
- 缺少多因素认证（MFA）相关代码

### A08: 软件和数据完整性故障
- 不安全的反序列化（`pickle.loads`、`yaml.load` 不带 `Loader`）
- 未校验的自动更新

### A09: 安全日志和监控失效
- 登录、权限变更等关键操作是否有日志记录
- 日志中是否包含敏感信息

### A10: 服务端请求伪造 (SSRF)
- 用户输入直接用于构造 HTTP 请求 URL
- 未限制内部网络地址访问

## 输出格式

按以下格式输出扫描结果：

\```
## 安全扫描报告

### 扫描统计

- 扫描文件数：X
- 发现问题数：X（严重：X / 高危：X / 中危：X / 低危：X）

### 漏洞详情

#### [严重] A03 注入 - SQL 注入

- 文件：src/db/query.py:42
- 代码：`cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")`
- 风险：攻击者可通过 user_id 参数执行任意 SQL
- 修复建议：使用参数化查询 `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`

### 修复优先级建议

1. 立即修复：[严重] 和 [高危] 问题
2. 尽快修复：[中危] 问题
3. 计划修复：[低危] 问题
\```

8. Skills 调试与优化

8.1 调试手段

开发 Skill 的过程中经常遇到"不触发"或"触发了但结果不对"的问题。以下是常用排查方法。

查看已加载的 Skills：在 Claude Code 会话中输入 /skills，会列出所有被发现的 Skill 及其 description。如果你的 Skill 不在列表里，说明目录结构或 frontmatter 格式有问题。

检查 SKILL.md 格式：frontmatter 必须是合法的 YAML，用 --- 包裹。常见错误：

  • 缩进用了 Tab 而不是空格

  • 冒号后面没有空格

  • 值中包含特殊字符但没有用引号包裹

  • 多行字符串没有正确使用 | 或 > 符号

# 错误
description:这是描述  # 冒号后没空格

# 正确
description: "这是描述"

手动触发测试：用斜杠命令直接触发 Skill，观察加载过程中是否有报错。如果 !command 执行失败，错误信息会直接出现在上下文中。

检查 !command 输出：如果 Skill 的行为不符合预期，可能是 !command 的输出跟你想象的不一样。单独在终端里跑一下那些命令，看看实际输出是什么。

8.2 触发不准确的排查

问题：Skill 应该触发但没触发

排查方向：

  1. 检查 description 是否包含了用户可能用到的关键词

  2. 检查 description 中的触发规则是否限制过严

  3. 检查 disable-model-invocation 是否设为了 true（如果是，只能手动触发）

  4. 检查 paths 是否限制了范围

优化方法：在 description 中加入更多同义词和触发场景。比如：

# 优化前
description: "审查 Pull Request"

# 优化后
description: "审查 Pull Request (PR/MR) 的代码变更，进行 code review，检查代码质量、安全漏洞和最佳实践"

问题：Skill 不该触发但触发了

排查方向：

  1. description 写得太宽泛，没有明确边界

  2. 缺少明确的排除规则

  3. 对于危险操作的 Skill，没有设置 disable-model-invocation: true

优化方法：在 description 中明确排除条件：

description:
 
|  扫描项目代码中的安全漏洞，基于 OWASP Top 10 检查常见安全风险。  触发场景：用户明确要求安全检查、漏洞扫描、安全审计时触发。  排除场景：用户仅提到"安全"关键词、普通代码审查、修复已知安全问题时，不触发。

8.3 上下文过大导致性能下降

Skill 加载后，其完整内容（包括 !command 输出）会注入到上下文窗口。如果 Skill 内容过大，会导致：

  • Claude 响应变慢

  • 重要信息被淹没在大量文本中

  • Token 用量飙升

控制 SKILL.md 正文长度：一个 Skill 的正文建议控制在 2000 字以内。如果确实需要更长的内容，考虑拆分成多个 Skill。

限制 !command 输出：永远在 !command 后面加 | head -N 或 | tail -N，防止输出爆炸：

# 不好
!git log

# 好
!git log --oneline -20

使用 context: fork：如果 Skill 本身会产生大量中间输出（比如安全扫描），用 context: fork 把它隔离到独立上下文中，不污染主会话。

按需拆分：一个"全能" Skill 不如几个"专精" Skill。比如把"PR 审查"拆成"代码质量审查"和"安全审查"两个独立 Skill，需要哪个加载哪个。

8.4 技能之间冲突的处理

当多个 Skill 的 description 相似时，可能出现误触发或竞争问题。

症状：用户说"帮我检查代码"，同时匹配了"代码审查" Skill 和"安全扫描" Skill，Claude 选了一个不合预期的。

解决方案：

  1. 差异化 description：让每个 Skill 的 description 有明显不同的关键词。“代码审查"强调"质量、规范、最佳实践”，“安全扫描"强调"漏洞、OWASP、安全审计”。

  2. 在 description 中明确互斥规则：

# review-pr 的 description
description: |
  审查 Pull Request 的代码变更，检查代码质量、规范和最佳实践。
  触发场景：用户要求常规代码审查、code review 时触发。
  排除场景：用户明确要求安全扫描、漏洞审计时，不触发此技能。

# security-scan 的 description
description: |
  扫描项目代码中的安全漏洞，基于 OWASP Top 10 做安全审计。
  触发场景：用户明确要求安全检查、漏洞扫描时触发。
  排除场景：普通代码审查、代码质量检查时，不触发此技能。

  1. 用 disable-model-invocation 兜底：对于容易误触发的 Skill，干脆禁止自动触发，强制手动使用斜杠命令。

  2. 命名空间：用前缀区分相关 Skill。比如 review-quality、review-security、review-perf，用户在输入时就能明确意图。

# elasticsearch # 大数据 # 搜索引擎
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区