AI 圈子的更新速度太快了，新概念真是层出不穷，一不留神跟不上就会被忽悠了。来一起看看，Agent Skill是Claude Code中的模块化功能组件，本质上是预定义的工具调用规范。它允许AI助手在特定场景下自动调用相应的工具，实现复杂任务的自动化处理。
从架构角度看，Agent Skill = 触发条件 + 执行逻辑 + 返回结果的标准化封装。

Claude Code 中创建、管理和共享技能（Skills），用更工程化的方式扩展 Claude 的能力。本文基于原文完整翻译，并在每一部分加入我们的理解与说明，同时以配图展示流程与逻辑。

前置条件（Prerequisites）

• 需要 Claude Code 版本 1.0 或以上
• 了解基础使用：Claude Code

我们的理解与说明

• 前置条件关乎环境与版本，尤其是技能发现与工具管控等能力可能随版本演进；建议在团队环境统一版本，避免行为差异。

什么是 Agent Skills（What are Agent Skills?）

技能把知识与能力打包为可发现的模块。每个技能包含一个 SKILL.md（说明与指令），以及可选的辅助文件（脚本、模板等）。

技能是“模型触发”的：Claude 会根据你的请求与技能的描述，自动决定是否使用技能。这不同于斜杠命令（用户显式输入 /command 触发）。

优势：

• 针对你的工作流扩展能力
• 通过 git 在团队中共享专业知识
• 降低重复提示的成本
• 组合多个技能解决复杂任务

更多参见：Agent Skills overview

深入架构与实战案例可阅读工程博客：[Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)。

我们的理解与说明

• 技能本质是“上下文+策略”的标准化单元。通过描述（description）建立触发语义，降低提示工程的重复工作；结合脚本与模板把可执行步骤固化为“工程工件”。
• 多技能组合能形成“多智能体协作”的雏形，前提是描述清晰与职责聚焦。
  

创建技能（Create a Skill）

技能以目录形式存储，包含 SKILL.md。

个人技能（Personal Skills）

• 存储路径：~/.claude/skills/

mkdir -p ~/.claude/skills/my-skill-name

适用：个人工作流/偏好、实验性技能、效率工具。

项目技能（Project Skills）

• 存储路径：项目内 .claude/skills/

mkdir -p .claude/skills/my-skill-name

适用：团队工作流/约定、项目特定知识、共享脚本。
项目技能需纳入 git，团队成员自动可用。

插件技能（Plugin Skills）

• 一些 Claude Code 插件会捆绑技能，安装插件后自动可用。

我们的理解与说明

• 三类技能对应三种发布与共享渠道：个人、项目、插件。建议在项目内沉淀通用技能（版本管理与协作更好），个人技能做偏好化增强；插件适合广泛复用与分发。
  

编写 SKILL.md（Write SKILL.md）

创建带 YAML frontmatter 与 Markdown 内容的 SKILL.md：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

字段要求：

• name：仅小写字母、数字、连字符（≤64字符）
• description：描述技能做什么以及何时使用（≤1024字符）

description 是技能发现的关键，应同时包含“能力与触发场景”。
最佳实践参见：best practices

我们的理解与说明

• name 是身份标识，description 是“何时匹配”的语义锚点；建议写入“领域关键词+操作动词+触发场景”。
• 在 Instructions 中给出可执行步骤，降低理解成本；Examples 提供边界与示例，提升召回准确性。

添加辅助文件（Add supporting files）

与 SKILL.md 同目录添加：

my-skill/
├── SKILL.md (required)
├── reference.md (optional documentation)
├── examples.md (optional examples)
├── scripts/
│   └── helper.py (optional utility)
└── templates/
    └── template.txt (optional template)

在 SKILL.md 中引用：

For advanced usage, see [reference.md](reference.md).

Run the helper script:
```bash
python scripts/helper.py input.txt
```

Claude 按需读取这些文件，采用渐进披露控制上下文。

我们的理解与说明

• 把“长文档”拆分到 reference.md，把“可执行步骤”放到 scripts/，把“可复用内容”放到 templates/，让技能既轻量又可执行。

使用 allowed-tools 限制工具访问（Restrict tool access）

通过 allowed-tools 限制技能激活时可用工具：

---
name: safe-file-reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern

当技能激活时，Claude 仅能使用指定工具（无需再次请求权限）。适用：只读技能、有限范围技能、安全敏感场景。未指定时遵循默认权限模型。

`allowed-tools` 仅在 Claude Code 支持。

我们的理解与说明

• allowed-tools 是“最小权限原则”的实现。对只读/分析类技能尤为重要，能降低非预期改动风险。
  

查看可用技能（View available Skills）

技能来源：

• 个人：~/.claude/skills/
• 项目：.claude/skills/
• 插件：随已安装插件捆绑

查看所有技能：直接询问 Claude。

What Skills are available?

或

List all available Skills

也可通过文件系统查看具体技能。

我们的理解与说明

• 在团队环境中，建议约定“技能命名与目录结构”，并提供技能清单页面，降低发现与复用门槛。

测试技能（Test a Skill）

创建技能后，用与描述匹配的问题进行测试。

示例：如果描述提到“PDF 文件”：

Can you help me extract text from this PDF?

Claude 会在匹配时自动使用技能，无需显式调用。

我们的理解与说明

• 使用“触发词”进行回归，验证技能是否按预期激活；在边界场景（近似词、复合意图）下检查召回与精确度。

调试技能（Debug a Skill）

若技能未被使用，检查：

让描述更具体（Make description specific）

模糊：

description: Helps with documents

具体：

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.

验证文件路径（Verify file path）

个人技能：~/.claude/skills/skill-name/SKILL.md
项目技能：.claude/skills/skill-name/SKILL.md

检查 YAML 语法（Check YAML syntax）

确保 frontmatter 正确（开闭 ---，无制表符，缩进正确）。

查看错误（View errors）

使用调试模式运行 Claude Code：

claude --debug

我们的理解与说明

• 调试流程本质是“发现—定位—修复”：优先从描述匹配、路径位置、YAML 语法三项排查；必要时增加日志与断点（脚本层）。
  

团队共享技能（Share Skills with your team）

推荐通过插件分发技能：

1. 在插件的 skills/ 目录放置技能
2. 发布到插件市场
3. 团队成员安装插件后自动可用

也可以在项目仓库直接共享：

步骤1：添加技能到项目

mkdir -p .claude/skills/team-skill
# Create SKILL.md

步骤2：提交到 git

git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push

步骤3：团队成员拉取后即可使用

git pull
claude  # Skills are now available

我们的理解与说明

• 插件适合大规模分发与版本管理；项目技能适合团队内部协作与快速演进。建议统一版本策略与变更日志。
  

更新技能（Update a Skill）

直接编辑 SKILL.md：

# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md

重启 Claude Code 后生效。

我们的理解与说明

• 对重要变更维护版本历史与变更说明，便于团队理解与回滚；尽量使用语义化版本。

移除技能（Remove a Skill）

删除技能目录：

# Personal
rm -rf ~/.claude/skills/my-skill

# Project
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"

我们的理解与说明

• 移除前先评估依赖关系与替代方案；在项目内保留“兼容迁移期”。

最佳实践（Best practices）

专注单一能力（Keep Skills focused）

一个技能只做一件事：

更好：

• “PDF form filling”
• “Excel data analysis”
• “Git commit messages”

不佳：

• “Document processing”（过宽，应拆分）
• “Data tools”（过宽，应按数据类型或操作拆分）

写清触发描述（Write clear descriptions）

描述中包含触发词与场景：

清晰：

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

模糊：

description: For files

团队内测试（Test with your team）

评估技能激活、说明清晰度、示例与边界是否充分。

版本记录（Document Skill versions）

在 SKILL.md 记录版本历史，便于追踪变更：

# My Skill

## Version History
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added new features
- v1.0.0 (2025-09-01): Initial release

我们的理解与说明

• 专注、清晰、可测试、可回滚，是技能工程化的四大支柱。

常见问题与排查（Troubleshooting）

技能未激活（Claude doesn’t use my Skill）

• 现象：提问相关但未触发技能
• 检查：描述是否具体（包含功能与场景）

模糊：

description: Helps with data

具体：

description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.

YAML 语法与路径（Is the YAML valid? Is the file path correct?）

• 验证 frontmatter 开闭与缩进；检查个人/项目技能路径是否正确。

# View frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Check for common issues
# - Missing opening or closing ---
# - Tabs instead of spaces
# - Unquoted strings with special characters

# Personal Skills
ls ~/.claude/skills/*/SKILL.md

# Project Skills
ls .claude/skills/*/SKILL.md

依赖与权限（Skill has errors）

• 依赖是否可用、脚本是否可执行、路径是否正确（使用正斜杠）。

chmod +x .claude/skills/my-skill/scripts/*.py

多技能冲突（Multiple Skills conflict）

• 通过更具体的描述区分触发领域与场景，避免混淆。

示例（Examples）

简单技能（单文件）

commit-helper/
└── SKILL.md

---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

带工具权限的技能

code-reviewer/
└── SKILL.md

---
name: code-reviewer
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist

1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage

## Instructions

1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Provide detailed feedback on code quality

多文件技能

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---

# PDF Processing

## Quick start

Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements

Packages must be installed in your environment:
```bash
pip install pypdf pdfplumber
```

在描述中列出所需包。需要先在环境中安装这些包，Claude 才能使用它们。

Claude 仅在需要时加载其他文件。

后续步骤（Next steps）

写出 Claude 能有效使用的技能 了解技能在 Claude 产品中的工作方式 在 Agent SDK 中以 TypeScript/Python 使用技能 创建你的第一个技能