AI工具
Claude Code Skills 深度调研：AI编程助手的技能扩展机制
|花叔
Claude CodeSkillsAI编程Anthropic开发工具
Claude Code Skills 深度调研报告
调研日期: 2026-02-08 调研目标: 全面掌握 Claude Code Skills 机制、最佳实践、社区生态
1. Skills 的本质
Skills 是 Claude Code 的模块化能力扩展系统。核心思想是渐进式披露 (Progressive Disclosure)：只在需要时加载详细指令，节省上下文窗口空间。
Skills 遵循 Agent Skills 开放标准（2025年12月发布），OpenAI 的 Codex CLI 和 ChatGPT 也采用了同一格式。
关键理解：Skills 不是外部进程或子代理，而是「按需注入的指令」，在主对话上下文中引导 Claude 的行为。
2. SKILL.md 完整格式
2.1 文件结构
每个 Skill 是一个文件夹，SKILL.md 是唯一必需文件：
my-skill/
├── SKILL.md # 主指令文件（必需）
├── scripts/ # 可执行脚本（可选）
│ └── helper.py
├── references/ # 参考文档，按需加载（可选）
│ └── api-docs.md
├── assets/ # 模板、图片等资源（可选）
│ └── template.html
└── examples/ # 示例输出（可选）
└── sample.md
不要创建的文件：README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等。只包含 AI Agent 执行任务所需的信息。
2.2 Frontmatter 字段（完整参考）
---
name: my-skill # 显示名，也是 /slash-command 名
# 规则：小写字母、数字、连字符，最多64字符
# 不可包含 XML 标签、"anthropic"、"claude"
# 省略时使用目录名
description: | # 推荐字段，最多1024字符
做什么 + 什么时候用。
Claude 用此字段决定是否自动触发。
必须用第三人称写。
disable-model-invocation: true # 禁止 Claude 自动调用（仅手动 /name）
user-invocable: false # 从 / 菜单中隐藏（仅 Claude 可调用）
allowed-tools: Read, Grep, Glob # 限制 Skill 激活时可用的工具
model: claude-sonnet-4-20250514 # 指定使用的模型
context: fork # 在隔离子代理中运行
agent: Explore # context: fork 时使用的子代理类型
argument-hint: "[issue-number]" # 自动补全时的参数提示
hooks: ... # Skill 生命周期钩子
---
2.3 调用控制矩阵
| 配置 | 用户可调用 | Claude 可调用 | 上下文加载时机 |
|---|---|---|---|
| 默认 | 是 | 是 | description 始终在上下文，调用时加载全文 |
disable-model-invocation: true | 是 | 否 | description 不在上下文，手动调用时加载 |
user-invocable: false | 否 | 是 | description 始终在上下文，调用时加载全文 |
2.4 字符串替换变量
| 变量 | 说明 |
|---|---|
$ARGUMENTS | 调用时传入的所有参数 |
$ARGUMENTS[N] / $N | 按索引访问参数（0开始） |
${CLAUDE_SESSION_ID} | 当前会话 ID |
2.5 动态上下文注入
!command`` 语法在 Skill 内容发送给 Claude 之前执行 shell 命令：
---
name: pr-summary
context: fork
agent: Explore
---
## PR 上下文
- PR diff: !`gh pr diff`
- 变更文件: !`gh pr diff --name-only`
这是预处理，Claude 只看到命令输出结果。
3. 全局 Skills vs 项目 Skills
3.1 存储位置与优先级
| 层级 | 路径 | 适用范围 | 优先级 |
|---|---|---|---|
| Enterprise | managed settings | 整个组织 | 最高 |
| Personal（全局） | ~/.claude/skills/<name>/SKILL.md | 所有项目 | 次高 |
| Project（项目） | .claude/skills/<name>/SKILL.md | 仅此项目 | 次低 |
| Plugin | <plugin>/skills/<name>/SKILL.md | 启用插件处 | 命名空间隔离 |
覆盖规则：同名 Skill 高优先级覆盖低优先级：enterprise > personal > project。Plugin Skills 使用 plugin-name:skill-name 命名空间，不会冲突。
3.2 自动发现机制
- 嵌套目录发现：编辑
packages/frontend/下的文件时，会自动发现packages/frontend/.claude/skills/中的 Skills，支持 monorepo --add-dir目录：通过--add-dir添加的目录中的.claude/skills/会自动加载，支持热更新- 旧版兼容：
.claude/commands/中的文件仍然有效，同名时 Skill 优先
3.3 上下文预算
Skill description 会加载到上下文中让 Claude 知道有什么可用。预算为上下文窗口的 2%，回退值为 16,000 字符。可通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖。
运行 /context 可查看是否有 Skills 因超出预算被排除。
4. Skill 触发机制
4.1 核心原理：纯 LLM 推理
Claude Code 不使用 embedding、分类器或正则匹配来决定触发哪个 Skill。系统将所有可用 Skills 的 name + description 格式化到 Skill tool 的 prompt 中，由 Claude 的语言模型在前向传播中做出决策。
这意味着：
- 不是关键词匹配，而是语义理解
- description 的质量直接决定触发准确率
- Claude 从
<available_skills>列表中选择最匹配的 Skill
4.2 Description 写法最佳实践
必须用第三人称（description 被注入系统提示词）：
- 正确：「Processes Excel files and generates reports」
- 错误：「I can help you process Excel files」
- 错误：「You can use this to process Excel files」
两部分结构：做什么 + 什么时候用
# 好的 description
description: |
Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files or when the user mentions PDFs,
forms, or document extraction.
# 差的 description
description: Helps with documents
包含具体触发词：
description: |
系统化降低AI检测率至30%以下，通过三遍审校流程增加人味。
当用户提到"AI味太重"、"像AI写的"、"降低AI检测率"、
"更像人写的"、"自然一些"时使用此技能。
针对错误场景的具体写法：
# 不好："Helps with database problems"（太模糊）
# 好："Fix for PrismaClientKnownRequestError in serverless"（具体到错误类型）
4.3 控制触发行为
- 触发太少：检查 description 是否包含用户常说的词；试试
What skills are available? - 触发太多：让 description 更具体；添加
disable-model-invocation: true - 直接调用：
/skill-name或/skill-name arguments
5. 环境变量与密钥管理
5.1 在 Skill 脚本中使用 API Key
推荐方式：通过 os.getenv() 读取，密钥存放在 .env 文件中。
#!/usr/bin/env python3
import os
API_KEY = os.getenv("IMGBB_API_KEY")
if not API_KEY:
print("Error: IMGBB_API_KEY not set")
exit(1)
5.2 安全注意事项
.env必须加入.gitignore，防止密钥泄露- 不要依赖
.claudeignore保护.env——已知存在绕过问题（2026年1月报告） - 使用 permissions.deny 限制文件访问（在
.claude/settings.json中）：{ "permissions": { "deny": ["Read(./.env)", "Read(./secrets/**)"] } } - 绝不硬编码密钥在 SKILL.md 或脚本中
- 云环境优先用加密密钥管理，而非 dotenv
5.3 .env 加载方式
Claude Code 运行脚本时，当前 shell 的环境变量可用。推荐：
- 在 shell profile（
.zshrc/.bashrc）中export常用 key - 或在脚本中用
python-dotenv显式加载：
from dotenv import load_dotenv
load_dotenv()
6. 脚本执行方式
6.1 执行运行时
Skills 在 Claude Code 的代码执行环境中运行，有文件系统访问权限、Bash 命令和代码执行能力。
| 执行方式 | 适用场景 | 优势 |
|---|---|---|
python3 scripts/xxx.py | 简单脚本，无额外依赖 | 直接，无需安装 |
uv run scripts/xxx.py | PEP 723 内联依赖 | 零配置，自动解析依赖 |
bun run scripts/xxx.ts | TypeScript 脚本 | 快速，类型安全 |
bash scripts/xxx.sh | Shell 脚本 | 简单任务 |
6.2 PEP 723 内联依赖（推荐方式）
使用 uv run + PEP 723 是目前最推荐的脚本执行方式，实现零配置、零全局污染、缓存执行：
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "httpx>=0.27.0",
# "rich>=13.0.0",
# ]
# ///
import httpx
from rich import print
# 你的代码...
执行方式：uv run scripts/my-script.py
要点：
- 依赖声明在文件头部，与代码一体
uv自动创建临时虚拟环境（首次后缓存，毫秒级启动）- 不要使用
[tool.uv.metadata]（不是 PEP 723 标准） - 适合 500 行以下的独立脚本
6.3 错误处理最佳实践
脚本应自行处理错误，而非抛给 Claude：
# 好：显式处理错误
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"File {path} not found, creating default")
with open(path, 'w') as f:
f.write('')
return ''
# 差：直接崩溃让 Claude 处理
def process_file(path):
return open(path).read()
输出格式建议：
- 使用清晰的 stdout 输出，Claude 读取输出结果
- 错误信息要具体（如
Field 'x' not found. Available: a, b, c） - 脚本的输出消耗 token，内容消耗为零直到被执行
7. Skill Creator 的工作方式
Anthropic 官方提供了 skill-creator Skill（在 anthropics/skills 仓库中），它是一个元 Skill：指导 Claude 创建新的 Skills。
7.1 创建流程（6步）
| 步骤 | 内容 |
|---|---|
| Step 1 | 理解 Skill 需求：通过具体例子了解功能 |
| Step 2 | 规划可复用内容：确定脚本、参考文档、资源 |
| Step 3 | 初始化 Skill：运行 init_skill.py 创建目录结构 |
| Step 4 | 编辑 Skill：编写 SKILL.md、实现脚本、删除不需要的示例文件 |
| Step 5 | 打包：运行 package_skill.py 验证并生成 .skill 文件 |
| Step 6 | 迭代：真实使用、发现问题、改进 |
7.2 关键设计原则
- SKILL.md 是为另一个 Claude 实例写的，不是给人看的
- 渐进式披露三层：
- Metadata（name + description）：始终在上下文（约100词）
- SKILL.md body：触发时加载（建议 < 5000词 / 500行）
- 捆绑资源：按需由 Claude 读取（无上限）
7.3 安装官方 Skills
# Claude Code 中安装
/plugin marketplace add anthropics/skills
# 安装特定包
/plugin install document-skills@anthropic-agent-skills
8. 社区优秀 Skills 案例
8.1 主要社区仓库
| 仓库 | 特色 |
|---|---|
| anthropics/skills | 官方示例（docx/pdf/pptx/xlsx） |
| VoltAgent/awesome-agent-skills | 200+ Skills，含 Anthropic/Google/Vercel 等官方 |
| travisvn/awesome-claude-skills | 社区精选，含 obra/superpowers（20+ 实战技能） |
| ComposioHQ/awesome-claude-skills | 8000+ Skills 合集 |
8.2 值得学习的社区 Skills
| Skill | 亮点 |
|---|---|
| obra/superpowers | TDD、调试、协作模式等20+实战技能 |
| ios-simulator-skill | iOS 开发自动化 |
| playwright-skill | 浏览器自动化 |
| claude-d3js-skill | D3.js 数据可视化 |
| Trail of Bits Security Skills | CodeQL/Semgrep 安全分析 |
| python-uv-scripts | PEP 723 内联依赖最佳实践 |
| Claudeception | 自主提取 Skill 并持续学习 |
| subagent-driven-development | 多子代理并行开发 + 代码审查检查点 |
8.3 Codebase Visualizer（官方示例）
这是官方文档中的完整示例，展示了 Skill + 脚本的最佳组合：
- SKILL.md 提供指令
- scripts/visualize.py 生成交互式 HTML
- 用户说「可视化代码库」即可触发
- 只需 Python 内置库，无需安装
9. 高级模式
9.1 子代理执行（context: fork）
---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...
- Skill 内容成为子代理的 prompt
- 子代理没有对话历史，独立执行
- 结果汇总返回主对话
- agent 可选：
Explore、Plan、general-purpose、自定义
9.2 工具限制
---
name: safe-reader
allowed-tools: Read, Grep, Glob
---
激活此 Skill 时，Claude 只能使用指定工具。
9.3 反馈循环模式
## 文档编辑流程
1. 修改 XML
2. **立即验证**：`python scripts/validate.py`
3. 验证失败 → 修复 → 再验证
4. **验证通过后**才继续
5. 重建文档
9.4 扩展思考
在 Skill 内容中包含「ultrathink」一词即可启用扩展思考模式。
10. 最佳实践总结
10.1 Skill 编写检查清单
核心质量：
- description 具体、包含关键触发词
- description 同时说明「做什么」和「什么时候用」
- description 使用第三人称
- SKILL.md body < 500 行
- 详细内容放在独立参考文件中
- 无过时信息
- 术语一致
- 文件引用最多一层深
- 工作流有清晰步骤
脚本质量：
- 脚本自行处理错误
- 无魔法数字（所有常量有注释）
- 依赖项在说明中列出
- 使用前向斜杠（非反斜杠）
- 关键操作有验证/反馈循环
命名规范：
- 推荐动名词形式：
processing-pdfs、analyzing-data - 可接受：名词短语
pdf-processing或动作process-pdfs - 避免：
helper、utils、tools等模糊名称
10.2 自由度匹配原则
| 任务类型 | 自由度 | 指令方式 |
|---|---|---|
| 代码审查、风格指南 | 高 | 文本指令，多种方法都可 |
| 报告生成、API 调用 | 中 | 伪代码/脚本+参数 |
| 数据库迁移、部署 | 低 | 精确脚本，不可修改 |
10.3 迭代开发方法
- 先不用 Skill 完成任务，观察需要反复提供什么信息
- 让 Claude A 创建 Skill（Claude 原生理解 Skill 格式）
- 用 Claude B 测试 Skill（新会话，真实任务）
- 观察 Claude B 的行为，带着发现回到 Claude A 改进
- 重复直到 Skill 稳定可靠
11. SKILL.md 模板
11.1 纯指令型 Skill（高自由度）
---
name: code-review
description: |
Reviews code for bugs, performance, and maintainability.
Use when user asks for code review, PR review, or feedback on code quality.
---
# Code Review
## 审查流程
1. 分析代码结构和组织
2. 检查潜在 bug 和边界情况
3. 建议可读性和可维护性改进
4. 验证是否符合项目规范
## 输出格式
每个问题包含：
- 位置（文件:行号）
- 严重程度（P0/P1/P2）
- 问题描述
- 修复建议
11.2 脚本驱动型 Skill（低自由度）
---
name: convert-to-pdf
description: |
将 Markdown 文档转换为苹果设计风格 PDF。
当用户说"转PDF"、"生成PDF"、"导出文档"时使用。
disable-model-invocation: true
allowed-tools: Bash(python3 *)
---
# Markdown to PDF
运行转换脚本：
```bash
python3 scripts/convert.py $ARGUMENTS
参数
$0：输入的 Markdown 文件路径--title：自定义标题--author：自定义作者
依赖
首次使用需安装：pip3 install markdown2 weasyprint
### 11.3 调研型 Skill（带持久化）
```yaml
---
name: research
description: |
结构化网络调研，成果实时保存到文件防丢失。
当用户说"调研"、"搜索资料"、"查一下"、"最新信息"时使用。
---
# 调研流程
## Step 1: 创建调研文件
在搜索之前，先创建 `_knowledge_base/research-<主题>-<日期>.md`
## Step 2: 搜索并增量保存
每次 WebSearch 后立即追加发现到文件
## Step 3: 阶段摘要
每3次搜索保存一次阶段摘要
## Step 4: 最终简报
整理为结构化简报，标注来源可信度
## 关键原则
- 先建文件再搜索
- 增量保存不等到最后
- 标注可信度
11.4 PEP 723 脚本模板
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "httpx>=0.27.0",
# "rich>=13.0.0",
# ]
# ///
"""
简要说明此脚本的用途。
Usage:
uv run scripts/this-script.py [args]
"""
import sys
import httpx
from rich import print
def main():
if len(sys.argv) < 2:
print("[red]Error: Missing required argument[/red]")
sys.exit(1)
try:
# 主要逻辑
pass
except Exception as e:
print(f"[red]Error: {e}[/red]")
sys.exit(1)
if __name__ == "__main__":
main()
12. 花生现有 Skills 优化建议
12.1 当前状态
| 位置 | Skills 数量 | 说明 |
|---|---|---|
~/.claude/skills/ | 50+ | 全局，含大量自动生成的模板 |
.claude/skills/ | 14 | 项目级，写作相关 |
12.2 主要问题
- 全局 Skills 过多：50+ 个 Skill 的 description 可能超出上下文预算（16K字符）
- 中英文混杂：部分 Skill name 用中文（如「AI味审校」），部分用英文（如
ai-proofreading），存在重复 - 部分 description 过长或不够精准
- 脚本未使用 PEP 723 内联依赖
12.3 建议
- 清理全局 Skills：保留真正跨项目使用的（如 AI审校、图片上传），其余移到项目级
- 统一命名：全部使用英文连字符格式（Agent Skills 标准要求）
- 去重：中文名 Skill 和英文名 Skill 二选一
- 优化 description：确保每个都遵循「做什么 + 什么时候用」的两段式
- 脚本升级：convert.py 等脚本改用 PEP 723 内联依赖
