DeepSeek Harness Skill 技能：SKILL.md 格式与使用

工具给 agent 的是"手"，技能（Skill）给的是"知识"。一个 Skill 就是一份写给 agent 的操作手册：什么时候用、怎么用、注意事项——agent 遇到相关任务时自动调取。这是 DSH 里性价比最高的扩展方式，因为写技能不需要写代码。

Skill 是什么：一个文件夹里的 SKILL.md

最小形态就是一个 SKILL.md 文件，分两部分：

--- 
name: my-skill 
description: 在用户要求处理 CSV 数据时使用。 
--- 

# CSV 处理流程 

1. 先用 python 的 csv 模块读取文件 
2. ...

• frontmatter（顶部 YAML）：name（技能名）+ description（何时使用——这段最关键，决定 agent 会不会想起它）
• 正文：给 agent 的操作指引，纯 Markdown

技能从哪来：三个来源

来源	位置	场景
项目技能	项目目录里	跟着项目走，进 git
用户技能	$DSH_HOME/skills、~/.agents	个人/全局技能
运行时技能	插件内嵌	随插件分发（如 cordis 预设自带的两个开发技能）

DSH 会在会话中自动发现这些技能，agent 根据 description 判断"这个技能对我的任务有没有用"，需要时主动加载全文。

技能的调用策略：给模型用还是给人用

每个技能可以声明两种调用方式：

• modelInvocable：agent 可以在任务中自动调用（默认）
• userInvocable：用户可以手动触发

两者可组合——一个技能既能被 agent 自动想起，也能让你手动点名。

写一个好技能的三个要点

1. description 决定一切。agent 靠它做"要不要加载"的判断。写清楚触发场景（"当用户要求 X 时"），而不是抽象描述（"一个有用的技能"）
2. 正文写流程，不写废话。像给新同事的 SOP：步骤、命令、坑
3. 短。每次加载都消耗上下文，聚焦"怎么做对"，砍掉原理科普

官方 cordis 预设自带的技能就是好范例：editing-cordis-compositions 的 description 是"When creating, changing, or validating a Cordis composition..."——直接写清触发条件。

Skill vs 插件 vs AGENTS.md：别搞混

	Skill	插件	AGENTS.md
内容	操作手册	代码（新能力/新工具）	长期规则
何时用	任务相关时按需加载	挂载即生效	每个会话都注入
会写代码吗	不需要	需要	不需要

一句话：AGENTS.md 是"永远要遵守的规矩"，Skill 是"用到才翻的手册"，插件是"装上新能力"。

常见问题

问题	解答
写了技能 agent 不用？	检查 description 是否写清触发场景；确认技能目录被扫描到
技能放哪最合适？	项目相关的放项目里（跟团队走）；个人通用的放用户目录
技能能互相调用吗？	技能是纯文本指引，agent 加载后按内容行事，可以引用其他技能名

接下来读什么

• 写一个自定义技能的完整教程 → 编写 Skill：自定义技能教程
• 工具与技能的配合 → 工具清单：内置工具与执行流水线
• 规则与技能的分工 → AGENTS.md：项目指令文件怎么写

---

← 上一篇：3.5 工具清单：内置工具与执行流水线 | 下一篇：4.1 子代理 Subagent：委派任务给子 Agent →
↑ 返回 教程总目录