张会挽's Blog

Skill 使用指南：从入门到自己编写一个 Skill

Posted on In

如果用 Claude Code 一段时间后，发现每次都在重复同一套流程、大纲或规范，那需要了解 Skill 这个功能。本文详细介绍 Skill 的概念、与 CLAUDE.md/MCP 等的区别，以及如何编写自己的 Skill。

Skill 是什么

一句话定义

在 Claude 生态里，**Skill = 一个可复用的”能力包”**：

  • 本质是一个文件夹，里面至少有一个 SKILL.md，写着”什么时候用、怎么用、具体步骤”等指令
  • Claude 会根据 description 等元数据自动判断要不要加载；也可以用 /skill-name 手动触发
  • Skill 里的内容只在需要时才加载，平时几乎不占上下文，比把大段规则写进 CLAUDE.md 更省 token

Skill 遵循 Agent Skills 开放标准，同一个 Skill 可以在 Claude Code、Claude.ai、其他兼容 Agent Skills 的工具里通用。

技术定义

在 Agent 开发中，Skill 是一套结构化的能力封装，让大模型能按需调用外部工具、代码或知识，完成具体任务。

其规范源于 Anthropic Agent Skills 协议，核心原则：

将「功能说明 + 输入输出定义 + 执行逻辑 + 参考资料」打包为标准文件夹，供智能体发现与执行。

一个 Skill 最少只需一个 SKILL.md 文件：

1
2
3
4
5
6
7
8
9
10
---
name: skill_name
description: 一句话说明功能
---

## 使用说明
- 功能：做什么
- 输入：需要什么参数
- 输出：返回什么结果
- 示例：调用代码片段

Skill = 标准化描述 + 可执行逻辑 + 上下文管理，是让大模型从”能聊”到”能做事”的关键组件。

Skill 和其他扩展的区别

特性 作用 何时用 例子
CLAUDE.md 每次会话都加载的”常识/规范” 项目规范、约定俗成的规则 用 pnpm、测试必须通过
Skill 可复用的知识 & 工作流，可手动或自动触发 重复流程、参考文档、多步骤任务 /deploy、API 规范 Skill
MCP 连接外部服务（数据库、Slack、浏览器等） 需要访问外部数据/操作时 查数据库、发 Slack 消息
Subagent 隔离上下文的”小助手”，跑完只返回摘要 读大量文件、耗时调研、并行任务 大仓库调研，长日志分析
Hook 纯脚本自动化（无 LLM），编辑后自动执行 可预期的自动化：lint、format、check 每次编辑后跑 ESLint
Plugin 打包 Skill/Hook/MCP 等的分发单元 跨项目复用、给团队/社区分享 企业品牌规范插件

简单理解：

  • CLAUDE.md = “这个项目的常识”
  • Skill = “可以按需加载的操作手册/职业技能”
  • MCP = “手和脚，去访问外部系统”
  • Plugin = “打包好的工具箱，可以装给别人用”

Skill 的存放位置

级别 路径 作用范围
个人 ~/.claude/skills/<skill-name>/SKILL.md 所有项目都能用
项目 .claude/skills/<skill-name>/SKILL.md 只在当前项目生效
插件 <plugin>/skills/<skill-name>/SKILL.md 安装该插件的项目可用，带命名空间
企业 通过托管配置统一下发 组织内所有人可用

同名 Skill 的优先级：企业 > 个人 > 项目。

另外，Claude Code 支持从嵌套目录自动发现 Skill，非常适合 monorepo：

  • 在 packages/frontend/ 下工作时，会加载 packages/frontend/.claude/skills/ 里的 Skill
  • 每个包可以有自己专属的 Skill

如何搜索和发现 Skill

ModelScope Skills 中心

进入魔搭社区 Skills 中心后，可以通过以下方式找到需要的技能：

关键词搜索

在搜索框输入功能描述，如”天气”、”代码执行”、”PDF 解析”，系统会匹配技能名称、描述和标签。

分类筛选

按左侧分类栏筛选，常见类别包括：

分类 说明
开发工具 代码生成、调试、部署
数据处理 格式转换、清洗、分析
内容创作 文案、绘图、视频
行业应用 医疗、法律、教育、金融
通用工具 搜索、计算、翻译

查看技能卡片

每个技能展示：

  • 名称
  • 简短描述
  • 作者
  • 标签
  • 基础数据

点击名称进入详情页，查看完整说明、输入输出定义和使用示例。

如何下载和使用 Skill

下载 Skill

方式一：命令行安装（推荐）

如果技能支持包管理安装，可直接执行：

1
2
3
4
5
# Node.js 环境
npx skills add https://modelscope.cn/skills/<skill-id>

# Bash 执行
curl -fsSL https://modelscope.cn/skills/install.sh | bash -s -- <skill-id>

<skill-id> 格式为 @作者/技能名，可在技能详情页顶部复制。

方式二：手动下载

  1. 在技能详情页点击”下载”按钮，获取 ZIP 包
  2. 解压到本地目录，如 ./skills/weather_query/
  3. 确保目录中包含 SKILL.md 文件

在常见软件中使用 Skill

核心思路

把 Skill 当作一个”插件”或”扩展包”：它包含功能说明、参数定义和执行逻辑，软件只需按规范加载，即可让 AI 调用该能力。

通用集成步骤

  1. 获取 Skill 包

    • 从魔搭社区下载 ZIP 包，或通过命令行安装
    • 确保本地包含 SKILL.md 及必要脚本/资源文件

  2. 放置到软件的技能目录

    • 大多数支持 Skill 的软件都有配置项指定技能加载路径（如 skills/、plugins/）
    • 将 Skill 文件夹放入该目录，或在配置文件中声明路径

  3. 启用并配置

    • 在软件配置中启用该技能
    • 如需密钥、端点等参数，按技能说明补充配置

  4. 在对话或工作流中调用

    • 通过自然语言触发（如”帮我查天气”），由软件自动匹配技能
    • 或通过命令/指令显式调用（如 /weather_query city=杭州）

常见软件类型的集成方式

软件类型 典型集成方式 示例
本地 AI 助手 配置 skills_dir 路径，重启加载 OpenClaw、CoPaw
IDE 插件 在插件设置中添加自定义技能目录 VS Code、Cursor
聊天机器人 通过 webhook 或插件机制接入技能执行逻辑 钉钉、飞书机器人
低代码平台 以”自定义工具”形式导入技能配置 Dify、Flowise
支持 MCP 的平台 通过 MCP Server 注册技能端点 Claude Desktop、其他 MCP 客户端

关键检查点

  • ✅ 软件是否支持加载外部技能/工具（查看文档关键词：skills、tools、plugins、extensions）
  • ✅ Skill 的 input_schema 是否与软件参数传递方式兼容
  • ✅ 执行环境是否满足技能依赖（如 Python 版本、网络权限）
  • ✅ 是否启用沙箱或权限控制，保障执行安全

在 ms-agent 中使用

1
2
3
4
5
6
7
8
9
10
11
from ms_agent.agent import create_agent_skill

agent = create_agent_skill(
    skills_dir="./skills/weather_query",  # 本地路径
    # 或引用社区技能
    # skills_dir="@author/skill-name",
    model="Qwen/Qwen3-235B-A22B-Instruct-2507"
)

result = agent.run("杭州今天天气怎么样？")
print(result)

验证技能是否生效

  • 调用 agent.list_skills() 查看已加载的技能列表
  • 使用 agent.test_skill("skill_name", **params) 单独测试某个技能
  • 查看日志输出，确认技能是否被正确触发

注意事项

  • 首次使用建议启用 use_sandbox=True，在隔离环境中执行脚本，避免安全风险
  • 部分技能依赖第三方 API，需自行配置密钥或网络权限
  • 使用前请阅读技能描述中的 input_schema，确保参数格式正确

一个最小 Skill 长什么样

创建步骤

1
2
3
4
# 1. 创建 Skill 目录
mkdir -p ~/.claude/skills/explain-code

# 2. 编写 SKILL.md

SKILL.md 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
name: explain-code
description: >
  用图表和类比解释代码。
  当需要解释代码工作原理、教学代码库，
  或者用户问"这段代码是怎么工作的"时使用。
---

解释代码时，始终包含：

1. **从类比开始**：把代码比作日常生活中的某个场景
2. **画一个图**：用 ASCII 字符展示流程、结构或关系
3. **逐步讲解执行路径**：逐行讲解代码
4. **指出边界情况**：说明可能会出现什么问题以及如何处理

现在可以：

  • 直接输入 /explain-code 手动触发
  • 或者自然地问：”这段代码是怎么工作的？” Claude 会自动加载

SKILL.md 结构详解

总体结构

1
2
3
4
5
6
7
8
---
name: my-skill
description: 这个技能做什么
disable-model-invocation: true
allowed-tools: Read Grep
---

这里是给 Claude 的具体指令...
  • 两个 --- 之间是 YAML frontmatter，控制 Skill 的行为
  • 下方是 Markdown 正文，给 Claude 的具体指令

Frontmatter 字段一览

字段 必填 说明
name 否 显示名称，省略则用目录名；小写字母+数字+-，最长64字符
description 推荐 什么时候用这个 Skill；Claude 用来判断是否自动加载；超过250字符会被截断
argument-hint 否 自动补全时的参数提示，如 [issue-number]、[filename] [format]
disable-model-invocation 否 true：禁止 Claude 自动加载；只能用 /name 手动触发
user-invocable 否 false：在 / 菜单里隐藏，用于”背景知识”型 Skill
allowed-tools 否 Skill 激活时，允许 Claude 免确认使用的工具列表
model 否 Skill 激活时使用的模型
effort 否 覆盖会话的 effort 级别：low / medium / high / max
context 否 设为 fork 可在隔离的子代理上下文中运行
paths 否 Glob 模式，限制 Skill 只在匹配这些路径时自动激活

常用字段使用建议

  1. description 一定要写好

    • 开头写最核心的使用场景，例如：”处理 .pptx 文件时使用这个技能…”
    • 避免写成长篇大论，会被截断

  2. 任务型 Skill：disable-model-invocation: true

    • 比如部署、发布、重构等”不想 Claude 自作主张触发”的流程

  3. 背景知识型 Skill：user-invocable: false

    • 比如内部规范、API 设计风格等，希望 Claude 自动参考，但不想在 / 菜单里看到

  4. 复杂 Skill：context: fork + 子代理

    • 需要读很多文件、跑很多命令，但又不想把主会话上下文撑爆

Skill 的两种内容类型

参考型（Reference）：给 Claude 增加知识

1
2
3
4
5
6
7
8
9
10
---
name: api-conventions
description: 本项目的 API 设计规范
---

编写 API 接口时：

- 使用 RESTful 命名规范
- 返回统一的错误格式
- 包含请求参数校验
  • 适合：规范、风格指南、领域知识、内部术语等
  • 通常不设 disable-model-invocation，让 Claude 自动参考

任务型（Task）：给 Claude 下发具体流程

1
2
3
4
5
6
7
8
9
10
11
12
---
name: deploy
description: 部署应用到生产环境
context: fork
disable-model-invocation: true
---

部署应用的流程：

1. 运行测试套件
2. 构建应用
3. 推送到部署目标
  • 适合：部署、提交、重构、发布日志生成等有明确步骤的流程
  • 建议加 disable-model-invocation: true，只允许手动 /deploy 触发

实战：写一个 Changelog 生成器 Skill

创建目录

1
2
mkdir -p ~/.claude/skills/changelog-generator
cd ~/.claude/skills/changelog-generator

SKILL.md 内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
---
name: changelog-generator
description: >
  从 git 提交历史自动生成面向用户的更新日志。
  用于需要发布说明、产品更新摘要、
  或应用商店提交更新日志的场景。
---

# 更新日志生成器

这个技能将技术性的 git 提交转换为面向用户的更新日志。

## 何时使用

- 准备新版本的发布说明
- 创建每周或每月的产品更新摘要
- 为应用商店提交编写更新日志
- 生成更新通知

## 技能功能

1. **扫描 Git 历史**：分析特定时间段或版本之间的提交
2. **分类整理**：将提交分组为新功能、改进、Bug 修复、破坏性变更
3. **技术转用户友好**：将开发者提交转换为用户语言
4. **专业格式化**：创建清晰、结构化的更新条目
5. **过滤噪音**：排除内部提交（重构、测试等）

## 示例

用户输入："生成最近一周的更新日志"

输出：

```markdown
# 更新 - 2024年3月10日

## ✨ 新功能
- **团队工作空间**：为不同项目创建独立工作空间，邀请团队成员，保持井井有条
- **键盘快捷键**：按 ? 查看所有可用快捷键，告别鼠标

## 🔧 改进
- **同步更快**：文件跨设备同步速度提升 2 倍
- **搜索增强**：搜索现在包含文件内容，不只是标题

## 🐛 问题修复
- 修复了大图无法上传的问题
- 解决了定时发帖时区混淆问题
- 修正了通知徽章计数

使用提示

  • 在 git 仓库根目录执行
  • 指定日期范围可生成更有针对性的日志
  • 可配合 CHANGELOG_STYLE.md 使用，保持格式一致
  • 发布前检查并调整生成的日志
  • 可以直接保存到 CHANGELOG.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

    ## 使用方式

    - 手动触发：`/changelog-generator`
    - 自然语言触发：
      - "帮我生成最近一周的更新日志"
      - "为 v2.5.0 写发布说明"

    # 进阶：带脚本和模板的复杂 Skill

    ## 推荐结构

    my-skill/
    ├── SKILL.md # 主指令（必须）
    ├── template.md # 模板文件，让 Claude 填空
    ├── examples/
    │ └── sample.md # 示例输出
    └── scripts/
    └── validate.sh # 可执行脚本
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

    在 `SKILL.md` 中引用：

    ```markdown
    ---
    name: my-report
    description: 生成每周状态报告
    ---

    # 周报生成器

    1. 读取 `template.md` 了解报告结构
    2. 根据本周 git 提交和 issue 更新填充各部分
    3. 运行 `scripts/validate.sh` 确保格式正确

内置变量

  • $ARGUMENTS：调用 Skill 时传入的所有参数
  • $0, $1, …：按索引访问参数
  • ${CLAUDE_SESSION_ID}：当前会话 ID
  • ${CLAUDE_SKILL_DIR}：Skill 所在目录，用于引用脚本/模板

带参数的 Skill

1
2
3
4
5
6
7
8
9
10
11
---
name: review-pr
description: 审查 Pull Request
argument-hint: [pull-request-url]
---

审查 $ARGUMENTS 的 Pull Request：

- 总结改动内容
- 列出潜在风险
- 提出改进建议

调用：

1
/review-pr https://github.com/owner/repo/pull/123

写好 Skill 的最佳实践

1. description 写成”触发条件 + 核心价值”

  • 好例子：处理 .pptx 文件时使用这个技能...
  • 坏例子：这是一个处理 PPT 的技能

2. 任务型 Skill 一定要加 disable-model-invocation: true

  • 避免部署/发布等高风险操作被 Claude 自动触发

3. 复杂 Skill 拆分成多个文件

  • 主指令放在 SKILL.md
  • 模板、示例、脚本分别放在子目录，用 ${CLAUDE_SKILL_DIR} 引用

4. Skill 职责单一

  • 一个 Skill 只解决一类问题
  • 不要把所有规范塞进一个”大杂烩” Skill

5. 给 Claude 清晰的”何时用/何时不用”

  • 在 description 和正文里明确边界
  • 例如：”当且仅当你需要生成面向用户的更新日志时才使用”

6. 多看别人的 Skill

什么时候该写 Skill

如果你发现：

  • 同一段流程，每次都要从 CLAUDE.md 拷出来改
  • 同一类任务，总是重复说”先这样，再那样，最后这样”
  • 有些长文档想让 Claude 参考，又不想每次占满上下文

那就是写 Skill 的好时机：

  1. 把流程/规范抽成一个 SKILL.md
  2. 用 description 告诉 Claude 什么时候用
  3. 复杂的话再加脚本/模板/示例

**Skill 就是给 AI 装上”职业手”**：同样的你，配上不同的 Skill，就能干完全不一样的活，而且越干越稳。

相关资源