10 分钟，我用 Skills 做了个 AI 摘要神器，写文章快 10 倍！

🚩 2026 年 「术」系列实战文档 X 篇原创计划 第 6 篇 Agent Skills 最佳实战「2026」系列 第 5 篇

大家好，欢迎来到 术哥无界 ShugeX ｜ 运维有术。 我是术哥，一名专注于 AI编程、AI智能体、Agent Skills、MCP、云原生、Milvus 向量数据库的技术实践者与开源布道者！ Talk is cheap, let's explore。无界探索，有术而行。

📝 本文摘要

本文是「Agent Skills 最佳实战」系列第 03 篇，手把手教你创建一个实用的 Agent Skills，实现文章自动摘要功能。你将学会 Skill 的基本结构、用户交互设计、文件操作，以及如何通过动态注入和子 Agent 实现高级功能。跟着教程走，10 分钟就能做出自己的第一个 Skill。

📖 系列回顾，在前两篇文章中：

• Agent Skills 最佳实战：EP01 初识 Skill
• Agent Skills 最佳实战：EP02 渐进式加载与多文件组织

我们了解了 Agent Skills 的基本概念和使用方法。但你可能会想：能不能让 Claude 学会一些我自己定义的技能？比如按照我的工作流程处理文件，或者用我习惯的方式生成文档？

答案是：当然可以。这就是 Skills 的作用。

为什么需要自定义 Skills？

想象这样的场景：你每天要阅读大量技术文章，需要快速提取核心要点。虽然可以每次都让 Claude 帮你总结，但你得反复说明格式要求、详细程度、保存位置等等。重复这个过程十次之后，你会想：能不能让 Claude 记住这个流程？

Skills 就是解决这个问题的。它让你可以把一套完整的工作流程教给 Claude，之后只需要一个命令就能执行。

更重要的是，Skills 遵循 Agent Skills 开放标准，这意味着你写的 Skill 不仅能在 Claude Code 中使用，还能在其他支持这个标准的 AI 工具中使用。一次编写，到处运行。

Skills 是什么？

简单来说，Skill 就是一个包含 SKILL.md 文件的文件夹。这个文件告诉 Claude：

• 这个 Skill 叫什么名字
• 什么时候应该使用它
• 具体怎么执行任务

Claude 启动时会扫描所有 Skills，读取它们的名称和描述（大约 100 tokens）。当你需要某个功能时，Claude 会判断哪个 Skill 最合适，然后加载完整的指令（建议 < 5000 tokens）来执行任务。

这种渐进式披露的设计很聪明：不用的时候不占用上下文，需要的时候才加载。这样即使你有几十个 Skills，也不会影响性能。

实战项目：创建文章摘要 Skill

别慌，我们不会一上来就讲一堆理论。让我们直接动手做一个实用的 Skill：文章摘要总结器。

需求分析

我们要做的这个 Skill 需要：

1. 询问用户要总结哪篇文章
2. 询问用户想要多详细的摘要（简短/中等/详细）
3. 读取文章内容
4. 生成结构化摘要
5. 保存到文件

这个需求涵盖了 Skill 的核心技能：用户交互、文件操作、内容处理。学会这个，你就能举一反三做出更多 Skills。

第一步：创建文件结构

首先，在你的项目目录下创建 Skill 文件夹：

mkdir -p .claude/skills/article-summarizer
cd .claude/skills/article-summarizer

为什么放在 .claude/skills/ 下？因为这是项目级 Skills 的标准位置。如果你想让这个 Skill 在所有项目中都能用，可以放在 ~/.claude/skills/ 下。

创建基本结构：

touch SKILL.md
mkdir -p scripts references

完整的目录结构是这样的：

article-summarizer/
├── SKILL.md          # 核心文件：指令 + 元数据
├── scripts/          # 可选：辅助脚本
└── references/       # 可选：参考文档和示例

结构图

第二步：编写 SKILL.md

这是最关键的一步。打开 SKILL.md，我们从头开始写。

2.1 定义元数据

文件开头是 YAML frontmatter，定义 Skill 的基本信息：

---
name: article-summarizer
description: 总结文章内容，生成结构化摘要。当用户需要快速理解长文章或生成文章摘要时使用。
argument-hint: [article-path]
allowed-tools: Read Write AskUserQuestion
model: inherit
---

让我解释一下每个字段：

• name：Skill 的唯一标识符，用户通过 /article-summarizer 调用
• description：告诉 Claude 什么时候应该使用这个 Skill。写得越清楚，Claude 越能准确判断
• argument-hint：提示用户可以传递什么参数，这里是文章路径
• allowed-tools：限制这个 Skill 只能使用指定的工具，提高安全性
• model：使用哪个模型，inherit 表示继承当前会话的模型设置

重点提示：description 是 Claude 判断是否使用这个 Skill 的关键。别写成"一个总结文章的工具"这种废话，要写清楚使用场景。

2.2 编写工作流程

frontmatter 下面是 Markdown 格式的指令。我们要把整个工作流程写清楚：

# 文章摘要总结器

## 你的任务

当用户需要总结文章时，按照以下流程执行。

## 第一步：收集信息

如果用户没有提供文章路径，使用 AskUserQuestion 工具询问：

**问题 1：选择文章**
- 使用 Glob 工具列出当前目录下的所有 Markdown 文件
- 将文件列表作为选项展示给用户
- 让用户选择要总结的文章

**问题 2：选择详细程度**
- 问题："您希望摘要的详细程度？"
- 选项：
  - "简短（3-5 个要点）"
  - "中等（包含主要论点和支持细节）"
  - "详细（完整的结构化摘要）"

## 第二步：读取文章

使用 Read 工具读取文章内容：
1. 检查文件是否存在
2. 读取完整内容
3. 识别文章结构（标题、章节等）

如果文章超过 10000 字，提醒用户可能需要较长时间处理。

## 第三步：生成摘要

根据用户选择的详细程度生成摘要：

### 简短摘要
- 核心主题（1 句话）
- 3-5 个关键要点（每个要点 1 句话）
- 主要结论（1 句话）

### 中等摘要
- 文章概述（1 段）
- 主要论点（3-5 个，每个带 1-2 句支持细节）
- 关键数据和引用
- 结论和影响（1 段）

### 详细摘要
- 完整的结构化大纲
- 每个章节的详细总结（保留逻辑结构）
- 重要引用和数据（标注出处）
- 作者观点分析
- 结论和启示

## 第四步：格式化输出

使用以下 Markdown 格式：

\`\`\`markdown
# 文章摘要：{文章标题}

**原文**：{文章路径}
**生成时间**：{时间戳}
**摘要类型**：{简短/中等/详细}

## 核心主题

{一句话概括文章主题}

## 关键要点

1. {要点 1}
2. {要点 2}
3. {要点 3}
...

## 详细内容

{根据摘要类型展开，保持清晰的层级结构}

## 结论

{总结性陈述，提炼文章的核心价值}
\`\`\`

## 第五步：保存摘要

使用 Write 工具将摘要保存到：
- 位置：原文件同目录
- 文件名：`{原文件名}-summary.md`
- 编码：UTF-8

保存后告诉用户文件路径。

## 注意事项

- **保持客观**：不添加个人观点，忠实反映原文内容
- **保留关键信息**：重要的数据、引用、术语必须保留
- **结构清晰**：使用标题、列表、加粗等格式提高可读性
- **技术文章特殊处理**：保留关键术语的原文，必要时添加简短解释
- **错误处理**：如果文件不存在或无法读取，给出清晰的错误提示

完整的 SKILL.md 就是这样。看起来有点长？别担心，Claude 只在需要时才加载这些内容。而且写得越详细，Claude 执行得越准确。

流程图

第三步：测试 Skill

保存文件后，重启 Claude Code（或者运行 /reload-skills 如果支持的话）。

测试方式 1：直接调用

/article-summarizer docs/my-article.md

测试方式 2：自然语言触发

帮我总结一下这篇文章的核心内容

如果你的 description 写得好，Claude 会自动判断应该使用这个 Skill。

测试方式 3：交互式使用

/article-summarizer

然后回答 Claude 的问题。这是最完整的测试，可以验证用户交互是否正常工作。

第四步：调试和优化

第一次运行可能不会完美。我当时也踩过坑，这里分享几个调试技巧：

问题 1：Claude 不使用我的 Skill

检查 description 是否清楚描述了使用场景。我一开始写的是"总结文章的工具"，太模糊了。改成当用户需要快速理解长文章或生成文章摘要时使用之后就好了。

问题 2：AskUserQuestion 没有触发

确保你在指令中明确写了"使用 AskUserQuestion 工具询问"。Claude 不会自己猜你想要交互。

问题 3：生成的摘要格式不对

在指令中提供具体的格式示例。我发现给出完整的 Markdown 模板比描述格式要求有效得多。

问题 4：处理长文章时超时

在指令中添加"如果文章超过 10000 字，提醒用户可能需要较长时间"。或者考虑使用子 Agent（下面会讲）。

对比图

进阶技巧

基础功能做好了，我们来看看一些高级玩法。

技巧 1：动态上下文注入

假设你想让 Skill 自动获取当前目录下的所有 Markdown 文件，而不是每次手动列出。可以使用 !\command`` 语法：

---
name:article-summarizer-v2
description:增强版文章摘要工具
context:fork
agent:Explore
---

# 文章摘要总结器 v2

## 可用文章

当前目录下的Markdown文件：

!\`find.-name"*.md"-typef|head-20\`

## 你的任务

从上面的文件列表中，询问用户要总结哪一篇...

这个 !\find ...`` 会在 Skill 加载时立即执行，输出会替换到指令中。Claude 看到的是已经填充好的文件列表。

注意：这个功能很强大，但也要小心。确保命令是安全的，不要执行可能有副作用的操作。

技巧 2：在子 Agent 中运行

如果你的 Skill 需要做大量分析工作，可以让它在独立的子 Agent 中运行：

---
name:deep-article-analysis
description:深度分析文章内容，提取主题、论点、论据结构
context:fork
agent:Explore
allowed-tools:ReadGrepGlob
---

# 深度文章分析器

你是一个专门分析文章结构的助手。你的任务是：

1.使用Grep工具搜索关键模式
2.识别文章的论证结构
3.提取主题和子主题
4.分析论据的类型和强度
5.生成结构化的分析报告

...

添加 context: fork 后，这个 Skill 会在新的上下文中运行，不会占用主对话的上下文窗口。分析完成后，结果会总结并返回到主对话。

这对于需要大量探索和分析的任务特别有用。

技巧 3：使用 Hooks 增强功能

Hooks 让你可以在 Skill 执行的特定时间点插入自定义逻辑。比如，在保存文件前自动运行格式化：

---
name:article-summarizer-pro
description:专业版文章摘要工具，自动格式化输出
hooks:
PostToolUse:
    -matcher:"Write"
      hooks:
        -type:command
          command:"./scripts/format-markdown.sh"
---

这样每次 Skill 使用 Write 工具保存文件后，都会自动运行 format-markdown.sh 脚本进行格式化。

你可以用 Hooks 做很多事情：

• 保存前的安全检查
• 执行后的通知
• 自动备份
• 日志记录

最佳实践

做了几个 Skills 之后，我总结了一些经验：

1. Description 要写清楚使用场景

不要写"一个 XXX 工具"，要写"当用户需要 XXX 时使用"。Claude 需要知道什么时候用你的 Skill。

差的例子：

description: 总结文章的工具

好的例子：

description: 当用户需要快速理解长文章、提取核心要点、或生成结构化摘要时使用。适合技术文档、博客文章、研究报告等文本内容。

2. 指令要具体，不要模糊

别说"生成一个好的摘要"，要说"生成包含核心主题、3-5 个关键要点、详细内容和结论的结构化摘要"。

提供具体的格式模板比描述格式要求有效得多。

3. 错误处理要完善

在指令中明确说明各种错误情况的处理方式：

• 文件不存在怎么办
• 文件太大怎么办
• 格式不支持怎么办

不要让 Claude 自己猜。

4. 合理使用 allowed-tools

限制 Skill 只能使用必要的工具，这样更安全，也能让 Claude 更专注。

如果你的 Skill 只需要读写文件，就不要给它 Bash 权限。

5. 提供示例

在 references/ 目录下放一些示例文件，在 SKILL.md 中引用它们。这能帮助 Claude 更好地理解你的期望。

6. 保持简洁

虽然指令要详细，但也不要写成小说。建议控制在 500 行以内。如果超过了，考虑拆分成多个 Skills。

7. 版本控制

把 Skills 放到 Git 仓库中，这样可以：

• 跟踪变更历史
• 在团队中共享
• 回滚到之前的版本

8. 测试不同场景

不要只测试理想情况。试试：

• 空文件
• 超大文件
• 格式错误的文件
• 不存在的路径

稳住，这些边界情况才是真正考验 Skill 质量的地方。

扩展方向

掌握了基础之后，你可以往很多方向扩展：

多格式支持

扩展 Skill 支持 PDF、Word、网页等格式。可以在 scripts/ 目录下放转换脚本，用动态注入调用。

批量处理

支持一次总结整个目录的文章。可以用循环或者并行处理。

自定义模板

让用户可以定义自己的摘要模板。可以在 assets/ 目录下放模板文件，在指令中引用。

集成外部服务

通过 Bash 工具调用外部 API，比如：

• 发送到笔记应用（Notion、Obsidian）
• 生成思维导图
• 翻译成其他语言

智能分析

添加更多分析功能：

• 关键词提取
• 主题分类
• 情感分析
• 相似文章推荐

总结

创建 Claude Code Skill 其实不难，核心就是：

1. 创建 SKILL.md 文件
2. 写清楚元数据（name、description）
3. 用 Markdown 写详细的指令
4. 测试和优化

我们通过"文章摘要总结器"这个实战项目，学会了：

• Skill 的基本结构
• 用户交互（AskUserQuestion）
• 文件操作（Read、Write）
• 动态上下文注入
• 子 Agent 使用
• Hooks 集成

这些技能足够你创建各种实用的 Skills 了。

最重要的是：别怕试错。我第一个 Skill 也是改了好几版才满意的。多试试，看看 Claude 的反应，根据实际效果调整指令。

如果你和我一样懒，不想每次都重复同样的操作，那就把它做成 Skill。一次投入，长期受益。

现在，轮到你了。想想你日常工作中有哪些重复性任务，试着把它们做成 Skills 吧。

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待。

扫码关注，获取更多 AI 工具的实战经验和最佳实践。不错过每一篇干货