Skill（技能）是 DSH（DeepSeek Harness）等通用 Agengt 最重要的行为定制机制之一，本质上是预定义的指令模板，告诉 Agent "应该以什么方式工作"。本教程以 DSH 为主体，通过实战案例讲解如何在 DSH、Claude Code、Codex 中创建、配置和使用 Skill，并重点对比三者 Skill 在项目级与全局级的配置方式，帮助你用 Skill 规范 Agent 的行为，提升学习和工作效率。
前置教程
如想快速开始学习本教程，你可能需要先完成以下前置教程：
- DeepSeek Harness 安装与使用教程，确保 DeepSeek Harness 已正确安装并可正常使用，本教程将以 DSH 为主体进行讲解。
- Claude Code安装及配置国内大模型完整教程，了解 Claude Code 的安装与配置，用于对比 Skill 的配置方式。
- Codex 安装与 DeepSeek v4 Flash 接入教程，了解 Codex 的安装与配置，用于对比 Skill 的配置方式。
- Skill概念详解，此内容详细介绍了 Skill 的基本概念及与其他相关概念的对比。
资源下载
-
Skill 示例合集 skills.zip 下载 — 包含 mermaid2img（Mermaid 转图片）、read-paper（多模态文档视觉识别转 md）、tutorial-reviewer（文档内容复核）、video-cover（视频封面制作）、video-upload（多平台视频上传），外加 ppt-master（演示文稿 PPTX 生成）、impeccable（前端界面设计）共 7 个脱敏 Skill。
-
Skill 迁移工具 a4api(v0.2.1) 下载地址，点击后自动进入下载。
1. Skill 的基本概念
在 DSH 中，Skill（技能） 是一组预定义的指令模板，在会话启动时注入到模型的系统提示中，作为行为指令的一部分。
- Skill 告诉 Agent "怎么做"——定义行为方式和输出规范
- Skill 运行在主线会话中，不创建独立的子进程
- Skill 的效果在调用后持续影响后续对话
DSH、Claude Code、Codex 三款 Agent 均支持 Skill 机制，工作原理一致，区别仅在于技能的存放目录与配置方式，详见 2.3 节。
关于 Skill 的概念详解你可以前往前置教程回顾：Skill概念详解。
2. Skill 的创建与配置
2.1 Skill 文件结构
一个完整的 Skill 文件可以包含以下组件：
.dsh/skills/
└── my-skill/
├── SKILL.md # 主指令文件（必需）
├── references/ # 参考资料目录（可选）
│ ├── template.yaml # 模板文件
│ └── examples.md # 示例参考
└── scripts/ # 辅助脚本（可选）
└── validate.sh # 验证脚本
my-skill 即为你的 Skill 名称。在 DSH 中，你可以通过
/my-skill/调用它；在 Claude Code、Codex 中同样通过/my-skill/调用，三者调用语法一致。
2.2 SKILL.md 文件格式
SKILL.md 文件由两部分组成：
第一部分：Frontmatter（元数据）
位于文件开头 --- 分隔的 YAML 块中：
---
name: skill-name # 技能名称（必填）
description: 简短描述技能用途 # 描述（必填）
disable-model-invocation: true # 仅用户可调用（可选，默认 false）
user-invocable: false # 仅 Agent 自动调用（可选，默认 true）
allowed-tools: Read, Grep, Glob # 限制工具访问（可选）
context: fork # 在隔离子代理中运行（可选）
agent: Explore # 隔离时使用的代理类型（可选）
---
第二部分：正文（指令内容）
Frontmatter 之后的内容就是 Skill 的指令正文，使用 Markdown 格式编写：
## 任务描述
当你收到 `$ARGUMENTS` 相关的任务时，按以下步骤执行：
### 步骤 1：分析需求
- 理解用户的具体需求
- 确定需要使用的工具
### 步骤 2：执行
- 按约定的规范和格式输出
- 使用参考模板（如果有）
### 输出格式
- 确保输出符合约定的格式标准
2.3 DSH、Claude Code、Codex 的项目级与全局级配置
Skill 的存放位置决定了它的作用范围：放在项目目录内的技能只对当前项目生效，随项目一起版本控制、便于团队共享；放在用户主目录内的技能对所有项目生效，适合个人常用技能常驻。
三款 Agent 的项目级与全局级技能目录对比如下：
| Agent | 项目级目录 | 全局级目录 | 说明 |
|---|---|---|---|
| DSH（DeepSeek Harness） | <项目根目录>/.dsh/skills/ |
~/.dsh/skills/ |
~/.dsh 即 DSH 的用户主目录（DSH_HOME），技能以"一切皆插件"方式加载 |
| Claude Code | <项目根目录>/.claude/skills/ |
~/.claude/skills/ |
Claude Code 官方技能目录规范 |
| Codex | <项目根目录>/.agents/skills/ |
~/.agents/skills/ |
本仓库 Codex 技能镜像约定的目录 |
DSH 的项目级与全局级配置
以安装 video-cover 技能为例，项目级安装只对当前工作区生效：
# 项目级：安装到当前项目（随项目版本控制）
mkdir -p .dsh/skills
cp -r skills/video-cover .dsh/skills/
全局级安装写入用户主目录 ~/.dsh/skills/，对所有工作区生效：
# 全局级：安装到用户主目录（所有项目共享）
mkdir -p ~/.dsh/skills
cp -r skills/video-cover ~/.dsh/skills/
Claude Code 的项目级与全局级配置
# 项目级
mkdir -p .claude/skills
cp -r skills/video-cover .claude/skills/
# 全局级
mkdir -p ~/.claude/skills
cp -r skills/video-cover ~/.claude/skills/
Codex 的项目级与全局级配置
# 项目级
mkdir -p .agents/skills
cp -r skills/video-cover .agents/skills/
# 全局级
mkdir -p ~/.agents/skills
cp -r skills/video-cover ~/.agents/skills/
同一份 SKILL.md 在三款 Agent 间通用，拷贝到对应目录即可生效；若 Skill 正文或脚本中引用了相对路径（如
.claude/skills/xxx/），拷贝到其他 Agent 目录后需同步调整路径前缀。
你也可以使用a4api工具实现skill的迁移，a4api会全局扫描所有可用skill，实现在不同agent之间和不同项目之间进行迁移：
2.4 调用控制组合（高级用法）
通过 disable-model-invocation 和 user-invocable 两个参数组合，可以精确控制 Skill 的调用方式：
disable-model-invocation |
user-invocable |
用户调用 | Agent 自动调用 | 适用场景 |
|---|---|---|---|---|
false（默认） |
true（默认） |
支持 | 支持 | 通用 Skill |
true |
true（默认） |
支持 | 不支持 | 有副作用的操作（部署、发送消息） |
false（默认） |
false |
不支持 | 支持 | 后台知识（编码规范、项目约定） |
true |
false |
不支持 | 不支持 | 无意义组合，不会触发 |
3. Skill 的调用方式
3.1 用户主动调用
在对话中直接输入 /skill-name 即可调用已注册的 Skill：
/code-review 审查 src/main.py 的代码
/api-doc 生成 user API 端点的文档
调用效果：
/code-review 审查 src/main.py 的代码
Skill "code-review" 已加载。（指令已注入到当前会话）
(Agent 按照 code-review Skill 定义的步骤和标准执行审查)
3.2 Agent 自动调用
当 Agent 判断当前任务与某个 Skill 的 description 匹配时，会自动加载该 Skill 的指令。以下情况会触发自动调用：
- 用户提出的问题与 Skill 描述高度相关
- 当前操作涉及 Skill 定义的领域
例如，如果有一个 python-style Skill 描述了 Python 编码规范，当用户让 Agent 编写 Python 代码时，该 Skill 会自动生效。
3.3 参数传递
向 Skill 传递参数有两种方式：
方式一：直接在命令后跟参数
/api-doc user/login 接口
参数 user/login 接口 会以 $ARGUMENTS 变量形式注入到 Skill 指令中。
方式二：在对话中提供上下文
/code-review
请审查以下代码：
def add(a, b):
return a + b
Skill 指令注入后，对话中的后续内容都会受其影响。
4. Skill 实战案例
本教程配套 5 个脱敏后的实战 Skill：mermaid2img、video-cover、read-paper、tutorial-reviewer、video-upload，可在上方 资源下载 区块通过网盘链接获取。下面逐一介绍安装与使用方法，默认安装到 DSH 的项目级目录 .dsh/skills/，如需全局生效添加至 ~/.dsh/skills/，其他 Agent 按 2.3 节 的目录对应拷贝。
示例技能已脱敏：脚本中的 API Key 已替换为占位符、本地绝对路径已泛化，读者按需替换为自己的配置。
4.1 mermaid2img — Mermaid 图表转图片
功能：扫描文档中的 mermaid 代码块，逐一转换为 PNG 图片，保存到 assets/ 目录，并用 Markdown 图片引用替换原代码块。
文件结构：
.dsh/skills/mermaid2img/
├── SKILL.md # 技能定义
├── README.md # 使用说明文档
└── scripts/ # 脚本目录
├── main.js # 主脚本，整合所有功能
├── validate-mermaid.js # 验证并清理 Mermaid 代码
├── find-diagram-placeholders.js # 查找 Mermaid 代码块
├── extract-diagram-info.js # 提取图表信息
├── create-assets-dir.js # 创建 assets 目录
└── replace-diagram-with-image.js # 替换代码块
安装：
mkdir -p .dsh/skills
cp -r skills/mermaid2img .dsh/skills/
调用：在对话中输入 /mermaid2img 文档.md，DSH 会自动加载该 Skill，扫描文档中的 Mermaid 代码块并转换为 PNG 图片。转换需要本机安装 Chrome 浏览器（教程示例通过 assets/puppeteer.json 配置 Chrome 路径）与 Mermaid CLI。
/mermaid2img mermaid2img-test.md
转换效果如下图所示：
安装后生效：Skill 安装完成后，在当前会话即可使用；如果 Agent 已在运行，重新启动后会话即可使用新安装的 Skill。
4.2 video-cover — 视频封面制作
功能：根据一段视频封面文案（或直接拖入文件），拆解出重点插槽，套用固定模板同时生成两张封面：1920×1080 通用横版 + 1440×1080 抖音横竖通用版（内容居中于 3:4 安全区，横竖裁剪都不丢失）。
文件结构：
.dsh/skills/video-cover/
├── SKILL.md # 技能定义
├── generate.mjs # 生成脚本（HTML 生成与 JPG 转换）
├── template.html # 1920×1080 通用横版模板
├── template-douyin.html # 1440×1080 抖音横竖通用版模板
├── themes.json # 主题配色配置（唯一事实来源）
├── cover.config.json # 封面文案示例配置
└── resources/
└── logo.png # 播放按钮 logo
安装：
mkdir -p .dsh/skills
cp -r skills/video-cover .dsh/skills/
调用：直接把文档 .md 文件拖入对话框并给出封面文案，或直接运行脚本：
/video-cover 主流Agent安装与使用：DSH 安装与接入 DeepSeek V4 Flash
对应的脚本命令：
node .dsh/skills/video-cover/generate.mjs cover.config.json \
--tutorial "教程.md"
# 预览确认后转图（任传一个 HTML 路径，两张都会转）
node .dsh/skills/video-cover/generate.mjs --jpg "<html绝对路径>"
封面输出到教程文件同级目录下的 video-cover/ 文件夹，生成 文档名.html/.jpg（通用横版）与 文档名-douyin.html/.jpg（抖音横竖通用版）。JPG 转换优先调用本机 Edge，其次 Chrome，无需额外依赖。
video-cover 生成的
文档名-douyin.jpg可配合 4.5 节 video-upload 技能的--cover-douyin参数作为抖音竖封面上传。
4.3 read-paper — 多模态视觉识别
功能：调用 MinerU 云端 API，将 PPT、Word、图片、PDF、HTML、xlsx 等异构文档识别为 Markdown 文本。图片类文件自动走 OCR 视觉识别，csv/txt 纯文本本地直读不消耗 API 配额。
文件结构：
.dsh/skills/read-paper/
├── SKILL.md # 技能定义
├── README.md # 环境与配置说明
├── config.json # 独立配置文件（API Key、模型映射、超时、输出目录）
└── scripts/
└── main.js # 核心脚本：MinerU API 调用 + 结果解压
安装：
mkdir -p .dsh/skills
cp -r skills/read-paper .dsh/skills/
配置 API Key：在 https://mineru.net/apiManage 获取 Key，替换 config.json 中的占位符（示例已脱敏）：
{
"apiBase": "https://mineru.net/api/v4",
"apiKey": "your-mineru-api-key"
}
调用：在对话中输入 /read-paper 文档.pptx，或直接运行脚本：
/read-paper 报告.pdf 演示.pptx docs/
node .dsh/skills/read-paper/scripts/main.js 报告.pdf
识别结果保存为与源文件同名的 .md 文件（默认与源文件同目录），供 Agent 直接阅读、总结、问答、改写。需要 Node.js 18+，无需安装任何 npm 依赖。
4.4 tutorial-reviewer — 文档内容复核
功能：对本地 Markdown 文件进行内容质量审查，覆盖五个维度：章节序号、概念与表述、笔误、内容引用（链接）、其他格式规范（emoji、代码块标注、页脚完整性等）。自动化脚本 + 人工审查结合，输出分级报告。
文件结构：
.dsh/skills/tutorial-reviewer/
├── SKILL.md # 技能定义
├── README.md # 使用说明
└── review.js # 审查脚本（章节编号、图片、结构、格式检查）
安装：
mkdir -p .dsh/skills
cp -r skills/tutorial-reviewer .dsh/skills/
脚本基于 Node.js 运行，需要 Node.js 18+（使用内置 fetch 发送请求），无需安装任何 npm 依赖。
调用：在对话中输入 /tutorial-reviewer 教程.md，或直接运行脚本：
/tutorial-reviewer DeepSeek Harness等Agent Skill安装与应用教程.md
# 快速模式（仅本地检查）
node .dsh/skills/tutorial-reviewer/review.js "教程.md" --skip-links
# 完整模式（含网络链接验证）
node .dsh/skills/tutorial-reviewer/review.js "教程.md"
# 输出报告到文件
node .dsh/skills/tutorial-reviewer/review.js "教程.md" --output 审查报告.txt
审查结果按错误、警告、信息三级汇报：错误必须修复（死链、章节编号错误、缺失文件），警告建议修复（内容匹配存疑、格式问题），信息可忽略。
4.5 video-upload — 视频多平台上传
功能：用 Playwright 驱动本机 Chrome，将本地视频自动上传到视频平台（目前支持 B站、抖音、小红书、微信视频号、微博）。上传页登录态通过持久化 profile 复用，首次运行 login 登录一次，之后上传免登录；支持 batch 批量任务顺序分发到多个平台。
文件结构：
.dsh/skills/video-upload/
├── SKILL.md # 技能定义
├── README.md # 环境与配置说明
├── package.json # 依赖（仅 playwright）
├── config.js # 平台配置：上传地址、登录地址、各字段选择器
└── uploader/
├── main.js # CLI 入口：login / upload / batch / dump 四个子命令
├── args.js # 极简命令行解析
├── browser.js # 持久化浏览器上下文（复用登录态）
├── collections.js # 合集名推导 + 模糊匹配
├── tutorial.js # 从教程 .md 推导标题/简介/标签
└── platforms/ # 各平台适配器（bilibili、douyin、xiaohongshu、weixin、weibo）
安装：
mkdir -p .dsh/skills
cp -r skills/video-upload .dsh/skills/
cd .dsh/skills/video-upload
npm install
调用：首次使用某平台前先登录，之后即可上传：
/video-upload login bilibili
/video-upload upload bilibili 视频.mp4 --title 标题 --desc 简介 --tags "教程,AI" --cover 封面.jpg
/video-upload upload douyin "D:\videos\演示.mp4" --tutorial "教程.md"
/video-upload batch 批量任务.json
--tutorial 参数可从教程 .md 自动推导标题、简介与标签（标签取页脚关键字并统一清洗）；--cover-douyin 指定抖音竖封面（可配合 4.2 节 video-cover 的产出）。默认停在发布确认页由用户手动发布，追加 --auto-publish 可全自动提交。
自动化上传属平台服务条款灰色地带，建议限速、发布前人工确认。平台改版导致选择器失效时，运行
dump子命令核对真实 DOM 并回填config.js即可修复。
4.6 ppt-master — 演示文稿生成
功能：路由驱动的 PPTX 生成工作流，能把"一段文字教程"一键转成 16:9 的 .pptx 演示文稿，或基于已有模板填充、美化。它与其他"单脚本" Skill 的不同之处在于：由一个主 Skill 统一掌控执行纪律与路由，再把具体流程委派给对应的路由规则文件。
四大路由：
| 路由 | 用途 |
|---|---|
Generate PPTX |
从文字生成 PPT（本教程所用） |
Create Template |
从空白模板创建 PPT 框架 |
Fill Native PPTX |
向已有 PPTX 模板填充内容 |
Enhance Native PPTX |
美化已完成的 PPTX |
核心能力：
- 设计系统：内置 12+ 主题（深色科技、浅色极简、莫兰迪等）、3 套字体族，通过
spec_lock.md锁定字体、颜色、留白等规范，保证风格统一。 - 原生导出：手写 SVG 页面经
svg_to_pptx.py导出为 PowerPoint 原生 DrawingML 对象（非位图），可二次编辑。 - 质量门禁：
svg_quality_checker.py在导出前自动检查画布越界、字号下限、色值格式、data-pptx-bounds等，不达标自动报出并指导修复。
实战：把本教程本身做成 PPT
下面以"把本文档《DeepSeek Harness 等 Agent Skill 安装与教程》转成 PPT"为目标，完整走一遍流程。
第 1 步：调用技能并下达指令
在会话中输入 /ppt-master，并按要求描述任务。ppt-master 会引导你填写 create_presentation_form.json，随后进入规划阶段：
[规划] 已读取项目设计规格：projects/DSH-Skill-PPT_ppt169_20260823/design_spec.md
[规划] 已读取设计规范锁定：projects/DSH-Skill-PPT_ppt169_20260823/spec_lock.md
[规划] 已生成项目 DSH-Skill-PPT_ppt169_20260823（14 页 | 16:9 | 深色科技风）
第 2 步：生成项目结构
Skill 在 projects/ 下创建工程目录，内容物清晰可追溯：
projects/DSH-Skill-PPT_ppt169_20260823/
├── design_spec.md # 设计契约：14 页内容大纲
├── spec_lock.md # 执行契约：字体/配色/版式/禁忌
├── scripts/ # 工具链脚本
├── svg_output/ # 每页手写 SVG（01 封面 ~ 14 结束）
└── exports/ # 最终导出目录
本例生成的 14 页包含：封面、Skill 是什么、目录结构、三大 Agent 对比、创建与配置、四大路由、多 Agent 安装、实战流程、质量门禁、最佳实践、避坑指南、资源下载、Q&A、结束页。
第 3 步：安装依赖并运行脚本
重型技能通常需要在会话内完成环境准备。ppt-master 使用 uv 创建虚拟环境并安装依赖（python-pptx、lxml、pillow、skia-pathops、uarfbuzz、XlsxWriter 等）。安装时若遇沙箱拦截，可改用虚拟环境方式：
# 创建虚拟环境（以系统已安装的 Python 3.14 为例）
uv venv --python 3.14 .venv
# 安装导出所需依赖
uv pip install python-pptx XlsxWriter skia-pathops uharfbuzz
# 执行导出
python .venv/Scripts/python.exe scripts/svg_to_pptx.py <项目路径>
第 4 步：运行质量门禁
导出前，Skill 会运行终态质检并输出报告：
python .venv/Scripts/python.exe scripts/svg_quality_checker.py --stage final --json
本例中 svg_quality_checker.py 曾报出两类问题并指导修复：部分 SVG 模块（<g>）缺少 data-pptx-bounds 边界声明、个别页面文本水平溢出。按提示补全边界、收紧文本后即可通过。
第 5 步：导出 PPTX
python .venv/Scripts/python.exe scripts/svg_to_pptx.py projects/DSH-Skill-PPT_ppt169_20260823
导出成功，产物位于 exports/ 下：
| 产物 | 说明 |
|---|---|
exports/DSH-Skill-PPT_20260823_171710.pptx |
14 页 16:9 PPT（原生 DrawingML，深色科技风） |
validation/svg_quality_report.json |
终态质检报告（0 error，质量门通过） |
4.7 impeccable — 前端界面设计
功能：前端界面设计专家，帮助用户设计、重构、打磨各类前端界面（网站、落地页、仪表盘、产品 UI、应用外壳、组件、表单、设置页、引导流程、空状态等）。它覆盖 UX 审查、视觉层级、信息架构、可访问性、响应式、主题系统、排版、间距、动画与微交互，适合"把平淡设计做得更大胆"或"把喧闹设计压得更克制"的场景，定位是产出高质量设计成品，而非仅提供规范约束。
适用模式（按目标界面自动选择）：
| 模式 | 用户目标 | 典型场景 |
|---|---|---|
| Persuade（说服） | 用户决策并采取行动 | 落地页、营销、活动、定价页 |
| Operate（操作） | 用户完成某项任务 | 应用 UI、仪表盘、编辑器、后台、设置、工具 |
| Read（阅读） | 用户理解某件事 | 文档、文章、指南、更新日志 |
| Experience（体验） | 用户沉浸于作品本身 | 作品集、画廊、展示页 |
常用命令：
| 命令类别 | 命令 | 用途 |
|---|---|---|
| 构建 | shape、init、document、extract |
设计规划、写入 PRODUCT.md、从代码生成 DESIGN.md、抽取可复用设计系统 |
| 评估 | critique、audit |
UX 启发式评分、可访问性/性能/响应式技术检查 |
| 打磨 | polish、bolder、quieter、distill、harden、onboard |
最终质量检查、强化/弱化设计、去繁就简、生产化、首次运行流程 |
| 增强 | animate、colorize、typeset、layout、delight、overdrive |
添加动画、配色、排版、布局、个性与记忆点 |
| 修复 | clarify、adapt、optimize |
优化文案与错误提示、适配多端、修复 UI 性能 |
| 迭代 | live |
浏览器内可视化选区、生成替代方案 |
使用方式：
在需要设计或改造前端界面时，输入 /impeccable。不带参数时，它会给出上下文感知的菜单供你选择；给出明确命令时（如 /impeccable audit 目标页面），则加载对应参考规则并执行。
使用建议：它强调"一次性充分交付"，在有限次数的检查与微调后停止打磨，避免无休止的自我 QA 消耗资源；设计时以用户的明确brief为准，不因个人偏好覆盖既定风格。
5. Skill 最佳实践
5.1 设计原则
| 原则 | 说明 |
|---|---|
| 单一职责 | 每个 Skill 只做一件事，一个 Skill 对应一个明确的行为规范 |
| 指令明确 | 使用具体的步骤和标准，避免模糊的描述 |
| 可验证 | Skill 执行结果应可判断是否符合预期 |
| 简洁 | 正文控制在 50 行以内，过长的指令会占用过多上下文 |
| 参数化 | 使用 $ARGUMENTS 接收输入，避免在 Skill 中硬编码 |
5.2 命名规范
- Skill 名称使用小写字母加连字符：
code-review、api-doc、data-analysis - 名称要能直观反映 Skill 的用途
- 避免与内置命令重名
5.3 常见误区
| 误区 | 正确做法 |
|---|---|
| 把 Skill 当 Agent 用，期望它并发执行 | Skill 在主线运行，并发应使用 Agent 或 Workflow |
| Skill 指令写得过于冗长 | 保持指令精炼，过长会消耗上下文窗口 |
| 在 Skill 中使用绝对路径引用资源 | 使用相对路径，确保项目迁移后仍可用 |
| 期望 Skill 跨对话持久生效 | Skill 只在当前对话有效，新对话重新加载 |
6. 常见问题与解答
Q1: Skill 文件修改后需要重启 Agent 吗？
不需要。Skill 文件在每次调用时重新加载，修改后直接在对话中再次调用 /skill-name 即可使用更新后的指令。
Q2: 一个项目可以创建多少个 Skill？
没有数量限制。但建议每个项目保持 3-5 个核心 Skill，过多的 Skill 会增加 Agent 自动匹配时的选择开销。
Q3: Skill 可以在多个项目间共享吗？
可以。有两种方式：
- 在全局目录（
~/.dsh/skills、~/.claude/skills、~/.agents/skills）中注册，所有项目共享 - 在不同项目的对应目录中分别注册（推荐，便于版本控制）
Q4: 同一个 Skill 可以在 DSH、Claude Code、Codex 之间通用吗？
可以。三者的 SKILL.md 格式与 /skill-name 调用语法一致，把技能目录拷贝到对应 Agent 的项目级或全局级目录即可。注意：若 Skill 正文或脚本内引用了安装路径（如 .claude/skills/xxx/），切换 Agent 后需同步调整路径前缀，否则脚本可能找不到自身资源。
举手提问