Agent Skills 完全学习指南

Skills（技能）用于为 AI 智能体添加专业技能和知识，把"某类事情应该怎么专业做"封装成一个可复用、可自动触发的能力模块。大模型负责"想和说"，Skills 负责"做"。

目录

第 1 章 Skills 是什么

Skills（技能） 翻译过来就是"技能"，用于为 AI 智能体添加专业技能和知识。就像人一样，你会做饭、会开车、会写 PPT——这些都是你的技能；智能体（Agent）也一样，它也需要有技能才能帮你干活。

  • Skills 就是智能体的技能：大模型负责"想和说"，Skills 负责"做"。
  • 普通 AI 与 AI 智能体的核心区别：智能体不只是思考者，更是行动者。

Skills 的本质，是教 AI 按固定流程做事的操作说明书。一旦写好，就能像函数一样反复调用。我们可以把 Skills 看成：把"某类事情应该怎么专业做"这件事，封装成一个可复用、可自动触发的能力模块。

一个有用的类比：

智能体的大模型 = 大脑（负责理解、决策、说话）
Skills       = 手和脚（负责动手干活）

Skills 以 Markdown 文件形式存在，本身不执行功能，而是通过按需、渐进式加载，实现高效且可复用的经验传递。

第 2 章 为什么需要 Skills

AI 智能体虽然具备强大的通用能力，但在处理特定领域的任务时，往往缺乏必要的上下文和专业知识。例如：

  • 一个 AI 代理可能不知道你的公司使用什么样的代码规范；
  • 不了解特定 API 的使用方法；
  • 不清楚某个业务流程的具体步骤。

Skills 的核心思想是：将人类的专业知识封装成技能包，让 AI 代理在需要时自动加载和使用。

Agent Skills 能带来什么

能力 说明
领域专业知识 将特定领域的知识（如法律审查流程、数据分析管道）封装为可复用的指令和资源
可重复的工作流 将多步骤任务变成一致、可审计的标准流程
跨产品复用 编写一次 Skill，在任意支持 Agent Skills 格式的工具中使用

没有 Skill 时的常见问题

在没有 Skill 的情况下，Agent 可能：

  • 反复问同样的澄清问题；
  • 错过团队特定的命名规范；
  • 忘记重要的边界情况。

有了 Skill，这些经验可以直接写进文件里，Agent 每次都会遵循。

没有 Skills 时 vs 有 Skills 时

助手 A（普通对话 AI）：

  • 一问一答，被动响应；
  • 你问"季度报告怎么写"，它只会给到一份通用模板；
  • 不会打开表格、不会自主查询数据、更无法整理文件、对接发送；
  • 本质只是一本会说话的线上百科，只给答案，不做执行。

助手 B（AI 智能体 + Skills）：

  • 指令直达，全自动闭环落地；
  • 你只需要一句话：“整理本季度销售数据，生成报告并发送给张总”；
  • 它便能自主完成全流程：调取文件、读取原始数据、自动生成图表、撰写完整报告、一键发送邮件；
  • 全程无需手动操作，坐等结果即可。

第 3 章 智能体（Agent）与 Skills 的关系

AI 智能体是能感知、推理、行动的 AI 系统，不只会聊天，还能执行任务。

  • Skills 是告诉智能体如何完成某类任务的说明书（Markdown 文件）；
  • Skills 的价值 让任务执行变得准确、稳定、可复用。

智能体的三个核心能力

能力 说明 例子
感知 接收输入，理解上下文 读取你上传的文件、理解你的需求
推理 制定计划，决定做什么 判断"先读文件，再生成报告，最后发邮件"
行动 调用工具，执行步骤 真正打开文件、写内容、发出去

Agent Skills 解决了什么

普通 AI 代理（如 Claude 或 DeepSeek）很聪明，但缺少特定上下文时容易出错。Agent Skills 解决这些问题：

  • 自动触发：AI 根据任务自动加载相关技能，无需手动输入长提示；
  • 可复用 & 可共享：一次创建，全团队或社区使用，支持 Git 版本控制；
  • 高效利用上下文：采用渐进式披露（progressive disclosure），只加载需要的部分，避免上下文窗口溢出；
  • 跨平台：同一个 Skill 可以在 Claude、VS Code Copilot、Cursor 等工具中使用。

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548

第 4 章 Skills 与 Prompt / MCP / 记忆 的区别

理解 Skills 的边界，最关键的是把它和 普通 Prompt、Rule/记忆、MCP/Tools 区分开。

Skills 与传统 Prompt 对比

对比项 普通 Prompt Skills 机制
每次都要重新描述 是 否（只描述一次）
上下文长度占用 每次全量塞入 渐进式加载（只在触发时才读完整内容）
一致性 依赖每次 prompt 质量 高（固定 SOP + 模板）
复用性 手动复制粘贴 自动匹配 / slash 命令 / 项目共享
维护方式 改一次 prompt 就要重新发 修改 SKILL.md 文件，全局/项目生效

四种能力的定位

把 AI 想象成一个刚毕业的聪明但没经验的实习生：

  • 普通 Prompt = 你每次都要从头教他怎么做事（今天教一遍，明天还得重新教）；
  • Rule / 记忆 = 你给他贴一张"公司行为守则"在工位上（一直生效，但只能管态度和格式）；
  • MCP / Tools = 你给他电脑装了一堆软件和 API（他能调用外部工具，但不知道什么时候该用、怎么组合用）；
  • Skills = 你直接给他一整套"岗位培训大礼包"（PDF+流程图+SOP+话术模板+常用脚本），告诉他：“当老板让你做这类事情时，就按这个文件夹里的方法来做”。

Skills 与 MCP 的区别

Skills MCP
核心 知识复用 能力扩展
内容 经验、最佳实践、工作流程 连接 API、数据库、外部工具
创建门槛 基于简单 Markdown 文件，任何人都可以创建 需要编码能力和服务器端配置
加载方式 渐进式加载，Token 使用效率高 启动时加载全部工具定义
部署 无需服务器或后端设置 更高的 Token 消耗与复杂度
适用 Web / Desktop / CLI 对外部系统集成能力强

目前能用 Skills 的主流客户端：

排序 工具名 是否免费使用 Skills 技能存放默认路径
1 Claude Code 是（官方） ~/.claude/skills
2 Cursor 是 ~/.cursor/skills
3 Trae / OpenCode 是 看工具设置
4 VS Code + 插件 部分支持 插件设置里配置
5 扣子/其他国内平台 部分支持 平台自带技能市场

第 5 章 Skill 的核心结构（目录 + SKILL.md）

Skills 的核心就是：一个文件夹 + 一个 SKILL.md 文件。

SKILL.md 文件包含：

  • 元数据（至少要有名称和描述）；
  • 告诉 AI 如何完成某一特定任务的指令。

一个 Skill 本质上就是一个 Markdown 文件（文件名固定为 SKILL.md）：

my-skill/
└── SKILL.md   （唯一必需）

SKILL.md 基本模板

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：
- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容
- 扫描版 PDF 需配合 OCR 工具

## 填写表单
- 读取 PDF 表单字段
- 按输入数据填充并生成新文件

最小必填示例

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

含可选字段示例

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

复杂 Skill 的目录结构

如果你需要参考资料、示例、执行脚本，可以使用更复杂的目录结构：

my-skill/
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

⚠️ 强制目录规范：所有技能根文件夹必须命名为小写 skills；每一个独立技能必须单独新建一个子文件夹隔离；SKILL.md 必须放在技能独立子文件夹内。文件夹名只能是小写字母、数字和连字符，不能带大写、空格、特殊符号。

第 6 章 SKILL.md 格式详解（YAML frontmatter 字段）

整个 SKILL.md 分为上下两部分：用 --- 包裹的 YAML frontmatter（头部配置），以及下方的 Markdown 正文（执行说明）。

字段说明

字段 必需 说明
name 是 Skill 名称，最长 64 字符，只能使用小写字母、数字和 -，且不能以 - 开头或结尾
description 是 功能与使用场景说明，最长 1024 字符，不能为空
license 否 许可证名称或指向随 Skill 附带的许可证文件
compatibility 否 环境与依赖说明（产品、系统包、网络权限等），最长 500 字符
metadata 否 自定义键值对，用于扩展元数据（如作者、版本号）
allowed-tools 否 允许使用的工具列表（空格分隔，实验性功能）

name 字段规则

  • 必须采用 kebab-case 格式（小写字母 + 连字符）；
  • 纯英文无中文，作为技能唯一机器识别标识；
  • 会被 / 命令引用，是系统识别 Skill 的关键字段；
  • 建议与上层技能文件夹名称完全一致（Claude 等工具要求一致）。

description 字段规则（最关键）

description 是 Agent 匹配触发的核心依据。它决定 AI 什么时候该调用这个 Skill。

  • ❌ 错误示范：“这个技能用于处理文件相关操作”（等于没说，AI 无法判断何时触发）
  • ✅ 正确示范：“处理 .docx 文件的创建、编辑、读取、格式操作。触发场景：用户提到 Word 文档、.docx 文件、创建文档、编辑文档、添加目录、插入图片到文档时使用。”

进阶推荐字段（提升触发率）

---
name: code-comment-expert
description: >-
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

trigger_keywords:
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

version: 1.0
author: yourname
---

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548

第 7 章 Skills 触发机制（渐进式披露）

技能用渐进式加载来高效管理上下文，这也是 Skills 区别于"把所有文档塞进系统提示词"的关键设计。

三层加载流程

  1. 发现（Discovery）：启动时，AI 只加载每个技能的 name 和 description，只保留最基本的识别信息；
  2. 激活（Activation）：当任务匹配某个技能的描述时，AI 才把完整的 SKILL.md 指令读入上下文；
  3. 执行（Execution）：AI 按照指令执行，按需加载参考文件或运行代码。
Level 0: skills_list()    → [{name, description, category}, ...]   （会话启动加载，约 3,000 tokens）
                                ↓ 只有需要用某个技能时，才继续
Level 1: skill_view(name) → 完整 SKILL.md 内容 + 元数据
                                ↓ 只有需要参考文档时，才继续
Level 2: skill_view(name, path) → 技能内的特定 references/ 文件

实际意义

  • 你安装了 50 个技能，但本次会话只用了 1 个——只有那 1 个的完整内容会占用 Token；
  • Level 0 的技能列表（约 3,000 tokens）在每次会话启动时固定加载，让 Agent 知道有哪些技能可用；
  • 其余内容在 Agent 判断需要时才加载，不用不花；
  • 渐进式披露保证技能数量可以无限增长，而每次会话的 Token 成本基本恒定。

注意：SKILL.md 的正文（body）不参与触发判断。Claude 只有在决定使用某个 Skill 之后，才会读取正文内容。所以 description 写得越具体，触发越准确。

第 8 章 创建第一个 Skill（Claude Code 实战）

让我们从一个最简单的 Skill 开始，感受它带来的便利。

步骤一：创建 Skill 目录

Skills 存放在 ~/.claude/skills/（个人全局）或项目目录下的 .claude/skills/（项目专用）。本章节在项目目录下测试，先创建目录：

mkdir claude-test
cd claude-test
mkdir -p .claude/skills/python-naming-standard

步骤二：编写配置文件 SKILL.md

在目录下创建 SKILL.md，这是 Skill 的大脑，告诉 Claude 什么时候用它。

---
name: python-naming-standard
description: 当用户要求重构、审查或编写 Python 代码时，请参考此规范。
---

## 指令
1. 所有的内部辅助函数必须以 `_internal_` 前缀命名。
2. 如果发现不符合此规则的代码，请自动提出修改建议。
3. 在执行 `claude commit` 前，必须检查此规范。

## 参考示例
- 正确：`def _internal_calculate_risk():`
- 错误：`def _calculate_risk():`

字段要求：

  • name：必须仅使用小写字母、数字和连字符（最多 64 个字符）；
  • description：Skill 的简要描述及其使用时机（最多 1024 个字符）。

步骤三：测试

在项目目录执行 claude 启动 Claude Code，输入任务：

帮我写一个计算用户折扣的函数

Claude 会扫描已安装的 Skills，发现请求涉及 “Python 代码编写”，匹配了 python-naming-standard，并根据 SKILL.md 要求生成：

def _internal_get_discount(user_score):
    # 计算逻辑...
    return discount

添加资源文件（可选）

在同一文件夹添加：

  • examples/：存放示例文件；
  • references/：存放参考文档；
  • scripts/：存放可执行脚本（例如 Python 处理 PDF）。

然后在 SKILL.md 中引用：

查看示例 commit：./examples/good-commit.txt
运行脚本：使用工具执行 ./scripts/process.py

第 9 章 多平台与进阶文件结构

Claude Code 的优先级加载顺序

Claude Code 按以下顺序查找并加载 Skill（越具体的位置优先级越高）：

级别 路径 生效范围
企业级 通过管理控制台配置（managed settings） 组织内所有用户
个人级 ~/.claude/skills/<skill-name>/SKILL.md 你所有项目
项目级 .claude/skills/<skill-name>/SKILL.md 仅当前项目
插件级 <plugin>/skills/<skill-name>/SKILL.md 启用该插件的环境

优先级铁律：项目级 Skills > 全局级 Skills。当两个技能 name 相同时，高优先级会直接覆盖低优先级，不会合并内容；无重名冲突时，全局规则 + 项目规则会同时并行生效。

最简结构

~/.claude/skills/
  └── code-comment-expert/        # 技能文件夹名
      └── SKILL.md                # 唯一必填文件（必须全大写 + .md 小写）

进阶文件结构（技能超过 500–800 行时推荐）

~/.claude/skills/react-component-review/
  ├── SKILL.md                  # 核心指令 + 元数据（建议控制在 400 行内）
  ├── templates/                # 常用模板（Claude 按需读取）
  │   ├── functional.tsx.md
  │   └── class-component.md
  ├── examples/                 # 优秀/反例（给 Claude 看标准）
  │   ├── good.md
  │   └── anti-pattern.md
  ├── references/               # 规范、规则、禁用词表
  │   ├── hooks-rules.md
  │   └── naming-convention.md
  └── scripts/                  # 可执行脚本（需开启 code execution）
      ├── validate-props.py
      └── check-cycle-deps.sh

在 SKILL.md 中引用方式示例：

需要给出标准函数组件时，参考 templates/functional.tsx.md 的结构。
如果违反 Hooks 规则，对照 references/hooks-rules.md 第 3–5 条说明。
如需校验 propTypes，可执行 scripts/validate-props.py "{代码片段}"。

Claude 看到路径引用后，会按需加载对应文件，而不是一次性全部塞入上下文，极大节省 token。

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548

第 10 章 Hermes Agent Skills 详解

Hermes Agent 的技能（Skills）系统让智能体"记住了怎么做事"。Skills 是 Hermes Agent 的程序化记忆，允许智能体从经验中创建可重用的工作流程，并在未来的会话中复用。

技能 vs 记忆

对比维度 技能（Skills） 记忆（Memory）
内容类型 操作流程、工作方法 环境事实、用户偏好
加载时机 按需，用到时才加载 每次会话自动注入
文件大小 可以很大（几百行） 应保持精简（关键事实）
Token 消耗 未加载时零消耗 每次会话固定消耗
创建者 你、Agent 或从 Hub 安装 Agent 根据对话自动创建
典型示例 如何部署到 Kubernetes 用户住在上海，偏好简洁回复

经验法则：如果你会把它写进参考文档，它就是技能；如果你会把它贴在便利贴上，它就是记忆。

技能目录结构

所有技能都存放在 ~/.hermes/skills/ 目录——这是唯一的数据源。

~/.hermes/skills/
├── mlops/                     # 分类目录
│   ├── axolotl/
│   │   ├── SKILL.md           # 主指令文件（必须）
│   │   ├── references/        # 补充文档（按需加载）
│   │   ├── templates/         # 输出模板
│   │   ├── scripts/           # 辅助脚本
│   │   └── assets/            # 附属资源
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/            # Agent 自动创建的技能
│       ├── SKILL.md
│       └── references/
├── .hub/                      # Skills Hub 状态
│   ├── lock.json
│   ├── quarantine/            # 安全隔离区
│   └── audit.log
└── .bundled_manifest          # 记录内置技能版本

每个技能目录的必须文件只有 SKILL.md，其余子目录都是可选的。

触发方式

斜杠命令直接调用：每个已安装的技能都自动成为一个斜杠命令。

/ascii-art 生成一个写着 "Hello World" 的横幅
/plan 设计一个待办事项应用的 REST API
/github-pr-workflow 为认证模块重构创建一个 PR

自然语言触发：Hermes 会通过 skill_view 工具自动加载。

帮我在 arXiv 上搜索关于 diffusion model 的最新论文

/learn 命令：一键从源生成技能

/learn 是将你已知的东西——或一堆参考资料——快速转化为可复用技能的捷径，无需手写 SKILL.md。

# 从本地 SDK 或文档目录学习
/learn ~/projects/acme-sdk 中的 REST 客户端，重点关注认证和分页
# 从在线文档页面学习
/learn https://docs.example.com/api/quickstart
# 从你刚刚完成的工作流程学习
/learn 我刚才部署 staging 服务器的步骤

Agent 自动创建技能

Hermes 最独特的部分：当完成一个复杂任务（通常涉及 5 步以上工具调用）后，Hermes 可能主动提议把工作流程保存为技能。默认情况下 Agent 可以自由创建和修改技能；开启 write_approval: true 后，每次创建或修改技能会先请求确认。

# 文件路径：~/.hermes/config.yaml
skills:
  write_approval: true   # 默认 false

技能包（Skill Bundle）：组合加载

技能包是将多个技能组合在一个斜杠命令下的 YAML 文件。运行 /<bundle-name> 时，包中列出的所有技能同时加载。

# 文件路径：~/.hermes/skill-bundles/backend-dev.yaml
name: backend-dev
description: 后端功能开发——代码审查、测试、PR 工作流
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow

条件激活：智能显隐机制

技能可以根据当前会话中可用的工具自动显示或隐藏。

metadata:
  hermes:
    fallback_for_toolsets: [web]     # 当 web 工具集不可用时才显示
    requires_toolsets: [terminal]    # 只有 terminal 工具集可用时才显示

安全注意事项

  • 写入审批门控：技能文件无签名溯源信息，无法区分 Agent 自己写的和手动放入目录的。write_approval: true 会让所有技能写入操作暂存为待审批状态；
  • 安全扫描：技能内容在加载前会经过威胁扫描，检测提示词注入、后门安装指令等恶意模式，匹配到威胁模式的内容会被替换为 [BLOCKED: ...] 占位符；
  • 从 Hub 安装时注意：官方内置技能（official/ 前缀）风险低；社区技能安装前用 hermes skills inspect 预览内容；.hub/quarantine/ 中的技能不建议安装。
# 安装前预览技能内容，不执行安装
hermes skills inspect https://example.com/SKILL.md

第 11 章 Skills 编写最佳实践

写 Skill 不是写说明书，是给 AI 写"肌肉记忆"。核心原则：三个"克制"。

克制一：克制写废话

上下文窗口是公共资源，Skill 会和系统提示词、对话历史、其他 Skill 争抢 token。默认假设：AI 已经够聪明了。

  • ❌ 错误示范：大量铺陈背景知识、解释概念含义、重复说明工具用法；
  • ✅ 正确做法：直接给步骤、给示例、给边界条件。

写之前问自己：这段解释 AI 真的需要吗？能不能用一句话替代三段话？

克制二：克制追求"全面"

不要试图把一个 Skill 做成全能工具箱。一个 Skill 做一件事，做透。

  • ❌ 错误示范：office全能助手，同时覆盖 Word/Excel/PPT/PDF；
  • ✅ 正确做法：docx处理、xlsx处理、pdf处理 分成三个 Skill。

功能边界清晰 → 触发准确 → 表现稳定。

克制三：克制越界设计

Skill 的职责是"告诉 AI 怎么做"，不是"替 AI 做决定"或"提供运行环境"。

  • ❌ 不要在 Skill 里写用户文档（那是给人类看的，不是给 AI 的）；
  • ❌ 不要塞 CHANGELOG、README、INSTALL GUIDE 等元数据文件；
  • ❌ 不要在 Skill 里写 AI 应该动态判断的逻辑。

description 编写技巧

description 是整个 Skill 的灵魂，决定 AI 什么时候该调用它。写清楚：

  1. 这个 Skill 做什么；
  2. 哪些用户请求会触发它；
  3. 触发时有哪些前置条件。

一个完整的 SKILL.md 正文建议包含这些标准章节：

  • When to Use（触发条件 + 反向条件）
  • Procedure / Instructions（分步骤的工作流）
  • Pitfalls（已知失败模式与解决方法）
  • Verification（如何验证结果正确）
  • Examples（2–3 个输入/输出示例，few-shot 学习极其有效）

第 12 章 常用 Skills 推荐与资源市场

推荐 Skills

Skill 核心作用 安装命令
find-skills (vercel-labs) 技能搜索与推荐中心 npx skills add vercel-labs/skills
vercel-react-best-practices React / Next 性能优化规范 npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
frontend-design (anthropics) 高质量 UI 设计能力 npx skills add anthropics/skills --skill frontend-design
web-design-guidelines Web 可访问性与 UX 规范 npx skills add vercel-labs/agent-skills --skill web-design-guidelines
pdf (anthropics) PDF 生成与解析能力 npx skills add anthropics/skills --skill pdf
code-review-expert 专业级代码审查能力 npx skills add sanyuan0704/code-review-expert
skill-creator 自定义 Skill 构建能力 npx skills add anthropics/skills --skill skill-creator
agent-browser 浏览器自动化控制 npx skills add vercel-labs/agent-browser
brainstorming (superpowers) 结构化思考与规划能力 npx skills add obra/superpowers --skill brainstorming

资源与社区

资源说明 链接
Skill 聚合入口 https://skills.sh/
Skills 市场（中文界面） https://skillsmp.com/zh
腾讯家的 Skills 市场 https://skillhub.tencent.com/
Agent Skills 官方标准站点 https://agentskills.io
Anthropic 官方工程文章 https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
VS Code Copilot Agent Skills 文档 https://code.visualstudio.com/docs/copilot/customization/agent-skills
Anthropic 官方 Skills GitHub 仓库 https://github.com/anthropics/skills
自动生成 Skill 的 Skill（官方示例） https://github.com/anthropics/skills/tree/main/skills/skill-creator

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548

第 13 章 扩展：从零设计一个完整 Skill 实战

以下为基于前文内容的实战扩展。我们以"技术文章转公众号"技能为例，走完从场景到完整 SKILL.md 的全过程。

13.1 场景定义

目标：用户丢一篇技术文章（Markdown / 链接），自动完成"总结 → 翻译（如需）→ 改成公众号风格 → 加标题 → 输出 Markdown"。

13.2 编写 description（最关键的一步）

description: >-
  将技术文章转换为微信公众号风格的可读内容。
  触发场景：用户提到"转公众号""改成公众号风格""公众号排版""技术文章转推文"，
  或提供文章链接/Markdown 并要求适合微信公众号发布。

13.3 完整 SKILL.md 示例

---
name: tech-article-to-wechat
description: >-
  将技术文章转换为微信公众号风格的可读内容。
  触发场景：用户提到"转公众号""改成公众号风格""公众号排版"，或提供文章并要求适合微信发布。
license: MIT
metadata:
  author: your-org
  version: "1.0"
---

# 技术文章转公众号

## When to Use
- 用户想把一篇技术文章发到微信公众号
- 用户提供了 Markdown / 链接，要求"公众号风格""推文排版"
- 不用于：纯翻译、纯摘要（无公众号排版需求）

## Procedure
1. 读取源文章，提取核心观点与代码块。
2. 重写为口语化、带小标题、有"钩子开头"的公众号结构。
3. 为每个代码块加语言标注并保持缩进。
4. 生成 3 个候选标题（悬念型 / 数字型 / 痛点型）。
5. 输出完整 Markdown，并附"封面图建议文案"。

## Pitfalls
- 不要删除代码块，否则失去技术价值。
- 避免标题党过度，保持信息准确。
- 微信不支持部分 Markdown 语法（如表格有时需转图片），需提示用户。

## Verification
- 检查是否包含：钩子开头、3 个候选标题、代码块保留、封面建议。
- 让用户确认风格后再定稿。

## Examples
输入：把这篇《Agent Skills 入门》改成公众号推文。
输出：包含"你还在每次手把手教 AI 做事吗？"开头 + 3 个标题 + 保留所有代码 + 封面建议。

13.4 目录结构与测试

.claude/skills/tech-article-to-wechat/
├── SKILL.md
└── references/
    └── wechat-style-guide.md   # 公众号排版规范（按需加载）

测试触发：在 Claude Code 中输入"把这篇 Agent Skills 文章改成公众号推文"，验证是否自动匹配并遵循流程。

第 14 章 扩展：Skills 调试、安全与团队协作

14.1 不触发 / 误触发排查清单

现象 可能原因 解决
技能完全不触发 description 太模糊 写清功能 + 触发场景 + 关键词，加 trigger_keywords
技能误触发 description 覆盖太广 收窄描述，增加反向条件（When NOT to use）
触发但执行混乱 正文步骤不原子 把复杂任务拆成编号原子步骤
上下文溢出 SKILL.md 过大 拆分到 references/，按需加载

14.2 提升触发率的技巧

  • description 用"功能 + 场景 + 关键词"三要素；
  • 增加 trigger_keywords 列表（Claude Code 等支持），覆盖口语化表达；
  • 在正文加 ## When to Use 与反向条件，帮助模型判断边界。

14.3 安全边界

  • 提示词注入：Skill 内容可能包含恶意指令。安装社区 Skill 前用 inspect 预览；
  • 写入审批：开启 write_approval，审核 Agent 自动创建的技能；
  • 隔离区：可疑技能会被放入 quarantine/，不要安装；
  • 签名溯源：技能文件无签名，无法区分来源，团队环境务必走审核流程。

14.4 团队协作与版本管理

  • Git 管理：把 .claude/skills/ 或 .hermes/skills/ 纳入团队仓库，提交即版本化；
  • 共享目录：Hermes 支持 external_dirs 扫描共享技能目录（如 /home/shared/team-skills）；
  • 审核流程：新人提交 Skill → PR → 审查 name/description/步骤 → 合并；
  • 本地优先：同名技能本地版本覆盖外部版本，避免误改共享库。
# ~/.hermes/config.yaml 外部技能目录
skills:
  external_dirs:
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

14.5 跨平台兼容策略

  • name 严格用 kebab-case，避免任何平台特有字符；
  • 核心字段（name/description）所有平台通用；
  • 平台特有字段（如 Hermes 的 metadata.hermes.*）放到可选 metadata，不破坏基础可读性；
  • 复杂逻辑用 references/ 承载，主文件保持精简。

第 15 章 扩展：Skills 质量评估与治理清单

15.1 一个好 Skill 的 10 条标准

  1. name 符合 kebab-case，且等于文件夹名；
  2. description 含"功能 + 场景 + 关键词"，能独立判断触发；
  3. 单一职责，不做全能工具箱；
  4. 正文有 When to Use 与反向条件；
  5. 步骤原子化、可操作、有顺序；
  6. 至少 2–3 个 Examples（few-shot）；
  7. 有 Pitfalls 与 Verification；
  8. 大文件已拆分到 references/，主文件 ≤ 400 行；
  9. 无废话、无用户文档、无 CHANGELOG/README 噪音；
  10. 可被自然语言或 /命令 稳定触发。

15.2 编写自查清单（Checklist）

  • name 仅含小写字母、数字、连字符，≤64 字符
  • description ≤1024 字符，写清触发场景
  • 文件夹名 = name
  • 只有一个 SKILL.md 在技能根目录
  • 步骤用编号列表，原子可操作
  • 有示例输入/输出
  • 有 Pitfalls 与 Verification
  • 大内容已移到 references/
  • 测试过自然语言触发与 /命令触发

15.3 反模式（Anti-patterns）

  • ❌ 把 SKILL.md 直接丢在 skills 根目录（必须放在子文件夹）；
  • ❌ 多个规则写在同一个技能文件夹；
  • ❌ 文件夹带大写、空格、特殊符号；
  • ❌ 在 Skill 里写用户文档 / CHANGELOG / README；
  • ❌ description 写"处理文件相关操作"这种无效描述；
  • ❌ 一个 Skill 覆盖 Word/Excel/PPT/PDF 全能。

15.4 进阶能力简介

  • Skill Bundle：用 YAML 把多个技能组合成一个斜杠命令（Hermes）；
  • 条件激活：用 requires_toolsets / fallback_for_toolsets 让技能按环境自动显隐；
  • Blueprint 定时任务：在 Skill 中声明 Cron 调度，变成可共享的自动化蓝图（Hermes）；
  • /learn：把已有知识或参考资料一键转为规范 Skill，无需手写。

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548

附录 A 常用命令速查

Claude Code

# 个人全局技能目录
mkdir -p ~/.claude/skills/<skill-name>
# 项目级技能目录
mkdir -p .claude/skills/<skill-name>
# 启动并测试
claude

Hermes Agent

hermes skills list                      # 列出所有技能
hermes skills search <关键词>           # 搜索本地和 Hub 技能
hermes skills install official/<类别>/<名称>   # 安装官方可选技能
hermes skills install https://...SKILL.md      # 从 URL 安装
hermes skills inspect <id>              # 预览（安装前检查）
hermes skills check                     # 检查更新
hermes skills update                    # 更新所有技能
hermes skills uninstall <name>          # 卸载 Hub 技能
hermes bundles create <name> --skill <s1> --skill <s2> -d "描述"  # 创建技能包
/learn <来源描述或 URL>                 # 从来源生成技能
/suggestions                            # 查看 Agent 的自动化建议

附录 B 官方与社区资源

资源说明 链接
菜鸟教程 Skills 教程 https://www.runoob.com/skills/skills-tutorial.html
菜鸟教程 Agent Skills 详解 https://www.runoob.com/ai-agent/skills-agent.html
菜鸟教程 Hermes Skills https://www.runoob.com/hermes-agent/hermes-agent-skills.html
Skills 基本结构 https://www.runoob.com/skills/skills-structure.html
Skill 聚合入口 https://skills.sh/
Skills 市场（中文） https://skillsmp.com/zh
腾讯 Skills 市场 https://skillhub.tencent.com/
Agent Skills 官方标准 https://agentskills.io
Anthropic 官方 Skills 仓库 https://github.com/anthropics/skills
自动生成 Skill 的 Skill https://github.com/anthropics/skills/tree/main/skills/skill-creator

📚 参考资源

  • 编程资源：https://pan.quark.cn/s/7f7c83756948
  • 更多资源：https://pan.quark.cn/s/bda57957c548
# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

大模型安全实战】智能体安全的攻防二元性：同一种能力，为什么既是防线也是攻击面？（第4期）

avatar 龙虾开发者社区
cover

SparkSQL 之 Hive On Spark 原理分析

avatar 龙虾开发者社区

RL训练Agentic模型实现并行多轮上下文检索：匹配前沿模型且快10倍

基于RL的Agentic检索模型正在成为AI Agent效率革命的关键驱动力。并行化：从串行单次调用转向多轮高并行调用自编辑：模型在检索过程中主动裁剪不相关信息迭代优化：检索器与Agent在RL训练中双向迭代当Agentic检索的速度提升10倍以上、成本大幅下降，AI系统将能在数秒内完成以往需要数分钟的复杂信息收集——这是Agent从“对话助手”走向“行动执行者”的关键一步。参考文献：, ACL

avatar 龙虾开发者社区