调研日期: 2026-02-08 调研目标: 全面掌握 Claude Code Skills 机制、最佳实践、社区生态
Skills 是 Claude Code 的模块化能力扩展系统。核心思想是渐进式披露 (Progressive Disclosure)：只在需要时加载详细指令，节省上下文窗口空间。
Skills 遵循 Agent Skills 开放标准（2025年12月发布），OpenAI 的 Codex CLI 和 ChatGPT 也采用了同一格式。
关键理解：Skills 不是外部进程或子代理，而是「按需注入的指令」，在主对话上下文中引导 Claude 的行为。
每个 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 执行任务所需的信息。
---
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 生命周期钩子
---
| 配置 | 用户可调用 | Claude 可调用 | 上下文加载时机 |
|---|---|---|---|
| 默认 | 是 | 是 | description 始终在上下文，调用时加载全文 |
disable-model-invocation: true | 是 | 否 | description 不在上下文，手动调用时加载 |
user-invocable: false | 否 | 是 | description 始终在上下文，调用时加载全文 |
| 变量 | 说明 |
|---|---|
$ARGUMENTS | 调用时传入的所有参数 |
$ARGUMENTS[N] / $N | 按索引访问参数（0开始） |
${CLAUDE_SESSION_ID} | 当前会话 ID |
!command`` 语法在 Skill 内容发送给 Claude 之前执行 shell 命令：
---
name: pr-summary
context: fork
agent: Explore
---
## PR 上下文
- PR diff: !`gh pr diff`
- 变更文件: !`gh pr diff --name-only`
这是预处理，Claude 只看到命令输出结果。
| 层级 | 路径 | 适用范围 | 优先级 |
|---|---|---|---|
| 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 命名空间，不会冲突。
packages/frontend/ 下的文件时，会自动发现 packages/frontend/.claude/skills/ 中的 Skills，支持 monorepo--add-dir 目录：通过 --add-dir 添加的目录中的 .claude/skills/ 会自动加载，支持热更新.claude/commands/ 中的文件仍然有效，同名时 Skill 优先Skill description 会加载到上下文中让 Claude 知道有什么可用。预算为上下文窗口的 2%，回退值为 16,000 字符。可通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖。
运行 /context 可查看是否有 Skills 因超出预算被排除。
Claude Code 不使用 embedding、分类器或正则匹配来决定触发哪个 Skill。系统将所有可用 Skills 的 name + description 格式化到 Skill tool 的 prompt 中，由 Claude 的语言模型在前向传播中做出决策。
这意味着：
<available_skills> 列表中选择最匹配的 Skill必须用第三人称（description 被注入系统提示词）：
两部分结构：做什么 + 什么时候用
# 好的 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"（具体到错误类型）
What skills are available?disable-model-invocation: true/skill-name 或 /skill-name arguments推荐方式：通过 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)
.env 必须加入 .gitignore，防止密钥泄露.claudeignore 保护 .env——已知存在绕过问题（2026年1月报告）.claude/settings.json 中）：
{
"permissions": {
"deny": ["Read(./.env)", "Read(./secrets/**)"]
}
}
Claude Code 运行脚本时，当前 shell 的环境变量可用。推荐：
.zshrc/.bashrc）中 export 常用 keypython-dotenv 显式加载：from dotenv import load_dotenv
load_dotenv()
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 脚本 | 简单任务 |
使用 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 标准）脚本应自行处理错误，而非抛给 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()
输出格式建议：
Field 'x' not found. Available: a, b, c）Anthropic 官方提供了 skill-creator Skill（在 anthropics/skills 仓库中），它是一个元 Skill：指导 Claude 创建新的 Skills。
| 步骤 | 内容 |
|---|---|
| Step 1 | 理解 Skill 需求：通过具体例子了解功能 |
| Step 2 | 规划可复用内容：确定脚本、参考文档、资源 |
| Step 3 | 初始化 Skill：运行 init_skill.py 创建目录结构 |
| Step 4 | 编辑 Skill：编写 SKILL.md、实现脚本、删除不需要的示例文件 |
| Step 5 | 打包：运行 package_skill.py 验证并生成 .skill 文件 |
| Step 6 | 迭代：真实使用、发现问题、改进 |
# Claude Code 中安装
/plugin marketplace add anthropics/skills
# 安装特定包
/plugin install document-skills@anthropic-agent-skills
| 仓库 | 特色 |
|---|---|
| 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 合集 |
| 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 | 多子代理并行开发 + 代码审查检查点 |
这是官方文档中的完整示例，展示了 Skill + 脚本的最佳组合：
---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...
Explore、Plan、general-purpose、自定义---
name: safe-reader
allowed-tools: Read, Grep, Glob
---
激活此 Skill 时，Claude 只能使用指定工具。
## 文档编辑流程
1. 修改 XML
2. **立即验证**：`python scripts/validate.py`
3. 验证失败 → 修复 → 再验证
4. **验证通过后**才继续
5. 重建文档
在 Skill 内容中包含「ultrathink」一词即可启用扩展思考模式。
核心质量：
脚本质量：
命名规范：
processing-pdfs、analyzing-datapdf-processing 或动作 process-pdfshelper、utils、tools 等模糊名称| 任务类型 | 自由度 | 指令方式 |
|---|---|---|
| 代码审查、风格指南 | 高 | 文本指令，多种方法都可 |
| 报告生成、API 调用 | 中 | 伪代码/脚本+参数 |
| 数据库迁移、部署 | 低 | 精确脚本，不可修改 |
---
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）
- 问题描述
- 修复建议
---
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: 最终简报
整理为结构化简报，标注来源可信度
## 关键原则
- 先建文件再搜索
- 增量保存不等到最后
- 标注可信度
#!/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()
| 位置 | Skills 数量 | 说明 |
|---|---|---|
~/.claude/skills/ | 50+ | 全局，含大量自动生成的模板 |
.claude/skills/ | 14 | 项目级，写作相关 |
ai-proofreading），存在重复此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。