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 对比

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

四种能力的定位

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

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

Skills 与 MCP 的区别

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

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

排序工具名是否免费使用 Skills技能存放默认路径
1Claude Code是（官方）~/.claude/skills
2Cursor是~/.cursor/skills
3Trae / OpenCode是看工具设置
4VS 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-practicesReact / 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-guidelinesWeb 可访问性与 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 Skillshttps://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 的 Skillhttps://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

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

avatar 龙虾开发者社区
cover

周榜换血九成，Agent Skills 星数翻倍

avatar 龙虾开发者社区

写给 TypeScript 工程师的 OpenClaw.NET 上手指南：用你熟悉的 TS 思维，跑起一个生产级 AI Agent

读代码层：TS 和 C# 本来就是「远房亲戚」——asyncawait??、接口、泛型、严格空检查，你的心智模型几乎无缝平移。真正要适应的只有两件事：类型是具名而非结构化的（多一句显式声明），以及 NativeAOT 下的「禁反射」约束。写扩展层：你甚至可以不怎么碰 C#——Node.js 插件桥意味着你的 TypeScript 插件就是一等公民，而且能在生产 aot 车道跑。内核给你 .NET

avatar 龙虾开发者社区