claude code 的 skill 用法以及skill 的高级特性-平芜编程栈

skill说明

AgentSkill（智能体技能）是给 AI 智能体（Agent）定义的可复用、可约束、可执行的能力单元；agent skill 最核心能力在于它按需加载的能力，这种才操作能省下大量的tokens数,也就是用到了才会去加载整个skill的Markdown Body（正文）部分；那么问题就来了， agent 如何知道该使用哪个 skill 呢？这就要说到skill.md 文件的两块主要内容了

Metadata (元数据)
markdown body（正文内容）

当我们在agent工具上将问题发给大模型时，agent 会将所有 skill 的元数据都打包一起发给大模型，由大模型去判断该用哪个 skill，如果匹配上就会告诉agent，然后agent 再将markdownbody 部分发给大模型；这样就实现了按需加载能力；

以下这张图片就很好地表示了用户和大模型的交互过程；

创建自定义 skill

SKILL.md 文件必须严格遵循 YAML Frontmatter（元数据） + Markdown Body（正文）的结构。

1、YAML Frontmatter（头部元数据）

这是文件的最顶部，用 — 包裹。它是 AI 在决定是否调用该技能时唯一会读取的部分，因此至关重要。

字段	是否必需	描述与规范
`name`	必需	技能的唯一标识符。通常使用小写字母和连字符（如`pdf-form-filler`）。
`description`	必需	核心中的核心。用 1-2 句话描述技能的功能、适用场景和触发条件。AI 仅凭此判断是否加载技能。
`version`	可选	版本号（如`1.0.0`），用于管理迭代。
`author`	可选	作者或团队名称。
`allowed-tools`	可选	定义技能可自动使用的工具列表（如`Bash`，`Read`），无需用户每次确认。

YAML 示例：

--- name: meeting-auditor description: 用于分析商务会议录音文本，提取关键决策，并根据合规手册审计预算风险。当用户要求“检查会议记录合规性”或“总结会议并审计”时触发。 version: 1.0.0 ---

2、 Markdown Body（正文指令）

这是技能被触发后，AI 才会读取的详细内容。它指导 AI 如何一步步完成任务。

🎯 需要重点描述的方面（正文内容）#
在 Markdown 正文中，你需要从以下几个方面来构建 AI 的“思维链”和“行动指南”

2.1. 角色定义 (Role Definition)

明确告诉 AI 它现在的身份。

描述方面：赋予 AI 一个具体的专家人设。

示例：“你是一名严谨的财务审计员”或“你是一名资深的 Python 代码审查专家”。

2.2. 核心指令与步骤 (Instructions & Steps)

这是文档的主体，必须使用祈使句（命令式语气），清晰、分步骤地描述操作流程。

描述方面：
任务拆解：将复杂任务分解为步骤 1、2、3。
逻辑判断：告诉 AI 在不同情况下该如何选择（例如：“如果 PDF 有密码，先调用解密脚本；如果没有，直接读取”）。
工具调用：明确指示何时运行 scripts/ 中的脚本或查阅 references/ 中的文档。

2.3. 输出规范 (Output Format)

规定 AI 最终呈现给用户的内容格式。

描述方面：
结构：例如“必须包含：摘要、风险点、建议措施三个部分”。
风格：例如“使用表格展示数据对比”或“代码块必须包含注释”。

2.4. 示例 (Examples)

提供“少样本学习”（Few-Shot Prompting）的案例，帮助 AI 理解意图。

描述方面：
输入/输出对：展示一个用户提问的例子，以及你期望的标准回答格式。
触发词示例：明确列出哪些用户语句会触发此技能（如“帮我打包这个项目”）。

2.5. 资源引用 (References &Assets)

指导 AI 如何使用技能包内的外部文件。

描述方面：
何时读取：例如“在执行审计前，必须先阅读 references/compliance_rules.md”。
如何使用：例如“使用 assets/template.pptx 作为生成报告的模板”。

SKLL.md 模版

--- name: [技能标识名] description: [一句话描述功能 + 触发场景 + 核心价值] version: 1.0.0 --- # [技能名称] ## 角色定义 你是一名 [具体角色]，擅长 [核心能力]。 ## 核心指令 请严格按照以下步骤执行任务： 1. **分析意图**：[步骤说明] 2. **查阅资料**：如果需要，读取 `references/[文件名]` 获取详细信息。 3. **执行操作**：运行 `scripts/[脚本名]` 处理数据。 4. **输出结果**：按照下方的输出格式要求生成回答。 ## 输出格式 - 必须包含：[要素 A]、[要素 B] - 风格：[专业/幽默/简洁] ## 示例 **用户输入**：[示例提问] **你的回答**：[示例回答] ## 错误处理 如果遇到 [某种错误]，请 [执行某种操作]。

skill 基本用法

首先在用户目录下的~/.claude/skills目录下新建一个梳理的目录，然后再新建一个SKLL.md 文件

SKLL.md 文件内容如下

--- name: 梳理 description: 用于梳理文章或文字内容、段落、内容等,当用户要求 "梳理" 时触发 version: 1.0.0 --- # 梳理 ## 角色定义 你是一个文章梳理的工程师，擅长将长篇大论的文字梳理为一段简单易懂且简短的文字，让人一目了然； ## 输出格式 - 仅输出梳理后的内容 ## 示例 **用户输入**：小明非常爱吃青菜，因为这样能有助于身体发育和健康成长 **用户输出**：小明爱吃菜，可以长高高且健康

然后打开claude，输入/skills命令，就可以看到刚刚添加的skill了

接着我们输入一个提示，让其触发刚刚添加的 skill

请帮我梳理这段文章：过去20年最佳的投资对象就是闹钟，任何新兴市场投资在长线来看都跑不过闹钟货币和市场地位的上升空间。 因为闹钟的上升空间是无限的，最多速度慢一点，需要用一点美元资产对冲波动。迪拜这种很快就触顶了。

通过结果可以看到，成功触发了名为梳理的skill

Reference条件触发的“补充资料包”

基础用法虽然省Token，但如果任务需求变复杂，skill.md文件可能会变得臃肿。

比如我们希望会议总结助手不仅能总结内容，还能在涉及花钱时标注财务合规性、涉及合同时提示法务风险——如果把所有财务规定、法律条文都写进skill.md，哪怕是简单的早会总结，也要加载一堆用不上的内容，浪费资源。

这时候就需要Reference：它是“条件触发的补充资料”，只有满足特定条件才会被加载。

首先修改下SKILL.md，加入统计提醒，加完后如下

--- name: 梳理 description: 用于梳理文章或文字内容、段落、内容等,当用户要求 "梳理" 时触发 version: 1.0.0 --- # 梳理 ## 角色定义 你是一个文章梳理的工程师，擅长将长篇大论的文字梳理为一段简单易懂且简短的文字，让人一目了然； ## 输出格式 - 仅输出梳理后的内容 ## 梳理规则 - 文字必须简短、通俗、易懂 - 统计提醒：仅在提到“总结”时触发，需读取`./references/文章总结助手.md`进行总结 ## 示例 **用户输入**：小明非常爱吃青菜，因为这样能有助于身体发育和健康成长 **用户输出**：小明爱吃菜，可以长高高且健康

然后在新建一个references文件夹，里面新建一个文章总结助手.md，内容如下

# 文章总结助手 ## 总结规则 - 文章字数 - 文章关键字 - 文章标题 注意：每项只能分别使用一句话来表示， 不要分成多条； ## 触发方式 当用户内容包含“总结、梳理”时自动激活 ## 示例 输入： AI叙事现在很复杂，不排除一种可能是美国AI完蛋了但中国AI巨幅崛起 输出： 文章字数：34 文章关键字：AI、美国 文章标题：美国AI完蛋中国崛起

建好后目录如下

现在尝试下会不会触发 reference, 打开claude code，输入以下提示词

帮我用技能梳理这篇文章：2026年，“Skills”成为AI圈热词。其中，GitHub狂揽30K Stars的“Superpowers”备受瞩目，它通过系统化工作流让AI从“美工”进化为“全能架构师”。本文将实战演示如何在302.AI客户端安装使 用Superpowers，并配合全新“任务板”功能，展示如何高效完成从需求梳理、架构设计到迭代优化的全流程。这种“方法论”与“工具”的结 合，标志着AI编程已从“玩具”进化为真正的生产力工具。最后请对这篇文章进行总结

按下回车后，过了2秒，可以看到已经触发了梳理的 skill，并且也成功触发了文章总结助手的 reference，问我们是否需要读取这个文件，我们选择 yes

最后可以看到，claude 已经按照我们的要求将文章进行总结出来了；

Script （运行脚本）

Script 是claude code 高级用法之一，顾名思义就是去运行用户指定的脚步，需要给它界定清楚是读还是运行，如果是运行，就算你的脚步中有上万行代码，它也不会去读取，这样就能够节省大量的token；

多说无益，我们来试验一下吧；还是刚才的梳理 skill,加上统计规则

--- name: 梳理 description: 用于梳理文章或文字内容、段落、内容等,当用户要求 "梳理" 时触发 version: 1.0.0 --- # 梳理 ## 角色定义 你是一个文章梳理的工程师，擅长将长篇大论的文字梳理为一段简单易懂且简短的文字，让人一目了然； ## 输出格式 - 仅输出梳理后的内容 ## 梳理规则 - 文字必须简短、通俗、易懂 - 统计提醒：仅在提到“总结”时触发，需读取`./references/文章总结助手.md`进行总结 ## 统计规则 如果用户提到 “统计”时，你必须运行 count.py 脚本进行统计，脚本使用方法： `<p>python count.py “梳理内容”</p>```markup ## 示例 **用户输入**：小明非常爱吃青菜，因为这样能有助于身体发育和健康成长 **用户输出**：小明爱吃菜，可以长高高且健康

然后在当前目录新增一个文件 count.py，内容如下：

import sys # 获取所有参数（排除脚本自身） args = sys.argv[1:] if not args: print("未传入任何参数") else: # 拼接所有参数 all_text = ' '.join(args) # 统计总字符数 total = len(all_text) print("参数内容：", all_text) print("总字符数：", total)

最后在claude code 试验一下，输入

帮我用技能梳理这篇文章：2026年，“Skills”成为AI圈热词。其中，GitHub狂揽30K Stars的“Superpowers”备受瞩目，它通过系统化工作流让AI从“美工”进化为“全能架构师”。本文将实战演示如何在302.AI客户端安装 使用Superpowers，并配合全新“任务板”功能，展示如何高效完成从需求梳理、架构设计到迭代优化的全流程。这种“方法论”与“工具”的结合，标志着AI编程已从“玩具”进化为真正的生产力工具。最后请对这篇文章进行统计一键获取完整项目代码
1

没有意外，触发且统计成功了