在大模型 Agent 工具链里,“能调用模型”和“能稳定完成一类任务”是两回事。把提示词、工具调用、输出格式、校验逻辑打包成一个可复用的 Skill,再通过 DeepSeek Harness 这类 Agent 框架统一加载、切换和分享,是目前比较常见的落地方式。很多开发者第一次接触 DeepSeek Harness 时,最大的困惑不是模型怎么接,而是 Skill 该怎么装、怎么建、怎么分享,以及 PPT Skill、UI 设计 Skill 这类现成能力到底放在哪个目录、为什么加载后不生效。
这篇文章围绕 DeepSeek Harness 的 Agent Skill 安装与应用展开,分四个层次:先理解 Skill 的定位,再完成框架安装,接着从零创建一个最小的 Skill,然后安装 PPT Skill 和 UI 设计 Skill 这类现成技能,最后讲清楚个人 Skill 如何组织、分享、排查报错。整篇内容按“理解概念 -> 环境准备 -> 最小实现 -> 现成技能安装 -> 验证排错 -> 最佳实践”的顺序推进,适合刚接触 Agent 开发、想用 Harness 整理个人技能库的开发者。读完以后,你可以按照同样的方法把日报生成、PPT 制作、UI 规范检查等能力变成可复用、可分享的 Skill。
1. 先搞清楚 DeepSeek Harness 里的 Skill 到底是什么
1.1 Agent Skill 解决什么问题
用一句通俗的话说,Skill 就是给 Agent 准备的“标准作业手册”。它不像普通提示词那样只写一段话,而是把任务描述、输入输出格式、参考规则、依赖工具、示例脚本都打包在一起,让 Agent 在接到类似任务时按照统一的流程执行。
技术定义上,Agent Skill 是包含元信息、指令文件、脚本资源和可选依赖的集合。它在 Agent 框架中作为一种可插拔能力单元存在。DeepSeek Harness 把这类单元放在固定目录或插件中心里,运行时按名称加载,再根据任务描述决定是否调用。
为什么需要 Skill?因为单次对话里写提示词只能解决“这一次”的问题。日报要每天生成,PPT 要反复按同一套规范制作,UI 评审要检查统一的间距、字号、颜色体系。这些任务如果每次都重新写提示词,效果不稳定,团队之间也无法复用。Skill 把“稳定做对一件事”所需的全部上下文固化下来,交给 Agent 执行时结果更可控,也更容易迭代。
容易误解的地方是:Skill 不等于一段长提示词。长提示词只是 Skill 的一部分。Skill 还可以携带校验脚本、模板文件、示例数据和处理逻辑,Agent 在执行时可以调用这些资源,而不是只靠模型“猜”。
1.2 Skill 与 Agent 的分工差异
很多刚接触 Harness 的人分不清 Skill 和 Agent。简单来说,Agent 是执行主体,Skill 是能力包。Agent 负责理解用户意图、决定调用哪个能力、控制多轮流程;Skill 负责告诉 Agent 某个具体任务“怎么做才算好”。
用项目里的类比:Agent 是项目经理,Skill 是项目规范文档。项目经理决定今天做哪件事,但具体按什么标准做、输出什么格式,由规范文档决定。一个 Agent 可以挂多个 Skill,同一个 Skill 也可以被多个 Agent 复用。
| 对比维度 | Agent | Skill |
|---|---|---|
| 定位 | 执行主体、流程控制 | 能力单元、任务规范 |
| 核心内容 | 模型配置、工具编排、记忆策略 | 指令、模板、脚本、规则 |
| 复用粒度 | 面向完整任务链 | 面向单一任务类型 |
| 典型例子 | 文档助手 Agent、编码 Agent | 日报 Skill、PPT Skill、UI 审查 Skill |
| 修改影响 | 影响整个执行流程 | 只影响对应任务 |
这里的核心判断是:不要把所有逻辑都堆在 Agent 配置里,也不要为了细分而把每个小操作都做成 Skill。任务边界清晰、输出标准化、会被重复使用的能力,才值得抽成 Skill。
1.3 Skill 与 MCP 的区别:一个管“会做”,一个管“能连”
搜索热词里经常出现“Agent Skill 和 MCP 有什么区别”,这确实是选型时必须想清楚的问题。
MCP(Model Context Protocol)解决的是 Agent 与外部工具、数据源之间的连接问题。它定义了一套标准协议,让 Agent 能调用 API、查询数据库、读写文件系统。Skill 解决的是任务执行质量的问题,它定义的是“面对某类任务该怎么思考、按什么格式输出”。
可以这样理解:MCP 是“手”,Skill 是“大脑里的操作手册”。MCP 让 Agent 能拿到外部数据,Skill 让 Agent 知道拿到数据后按什么标准处理。两者不是替代关系,而是配合关系。一个 PPT Skill 可能要依赖 MCP 读取本地模板文件夹,也可能要调用文件写入工具,但最终的页面结构、配色规范、排版节奏由 Skill 里的规则控制。
| 对比维度 | Agent Skill | MCP |
|---|---|---|
| 解决问题 | 任务怎么做得规范 | 外部能力怎么连进来 |
| 内容形式 | 指令、模板、脚本、规则 | 工具定义、协议、服务端点 |
| 作用阶段 | 任务规划与输出生成 | 工具调用与数据访问 |
| 常见用法 | 生成日报、制作 PPT、UI 评审 | 查数据库、调接口、读写文件 |
| 是否必须 | 追求稳定输出时建议使用 | 需要外部集成时使用 |
实际项目中,两者组合使用最常见。Skill 负责“把这件事做对”,MCP 负责“把相关数据拿过来”。
2. 安装 DeepSeek Harness:先跑通最小环境,再考虑插件
2.1 安装前的环境检查
在动手安装 DeepSeek Harness 之前,先确认基础环境。很多安装失败并不是工具本身的问题,而是 Node、包管理器或网络环境不满足要求。学习环境可以怎么快怎么来,但要先跑通最小环境,再逐步加插件。
以常见的安装方式为例,DeepSeek Harness 的安装过程通常需要以下条件:
| 依赖项 | 建议要求 | 检查命令 | 说明 |
|---|---|---|---|
| Node.js | 18 或更高版本 | node -v | 版本过低会导致依赖安装失败 |
| 包管理器 | pnpm 8 或更高版本 | pnpm -v | Harness 项目常用 pnpm 管理依赖 |
| Git | 最新稳定版 | git --version | 安装 Skill 时经常需要拉取仓库 |
| 磁盘空间 | 预留 5GB 以上 | 视系统而定 | 依赖包和模型缓存会占用空间 |
| 终端 | PowerShell / Bash | 无 | Windows 下推荐使用 PowerShell 或 Windows Terminal |
如果原始安装文档没有写明版本要求,落地前先确认官网或仓库 README 里的版本说明,不要直接照搬旧教程。版本不匹配时,最常见的表现是pnpm install报 ERESOLVE 错误,或者启动后页面空白。
这里有一个学习环境与生产环境的区别。学习环境只需要在本地启动一份实例,验证 Skill 能加载、能调用模型、能输出结果即可。生产环境则要考虑配置外置化、日志采集、权限隔离、多个 Skill 版本共存、回滚方案等问题,不能把学习环境的目录结构直接搬过去。
2.2 下载与安装步骤:常见问题的根因在这一步
安装 DeepSeek Harness 的常见路径有两种:直接下载桌面版安装包,或者通过 Git 拉取源码后自行构建。桌面版适合大多数用户,源码构建适合需要二次开发插件的人。
Git 方式的基本流程如下:
git clone <DeepSeek Harness 仓库地址> cd <仓库目录> pnpm install pnpm dsh web这里的dsh是 Harness 的命令行入口,dsh web用于启动 Web 工作区。不同版本命令可能不同,如果当前版本没有dsh命令,查看仓库的package.json中 scripts 部分确认启动方式。
安装卡住是搜索热词里出现频率最高的问题,尤其是“卡在 pnpm dsh web”。这个现象要分两层看:
第一层是pnpm install阶段卡住。根因通常是网络拉取依赖过慢、镜像源不稳定、或者 lockfile 与当前 pnpm 版本不兼容。处理方式建议按顺序检查:
pnpm config get registry如果 registry 指向国外默认源,可以切换到国内镜像源,再重新安装:
pnpm config set registry https://registry.npmmirror.com pnpm install第二层是dsh web启动后长时间停留在“启动中”状态。根因通常是首次启动需要初始化本地工作区目录、拉取插件列表或下载模型相关资源。可以先查看终端日志,确认是网络请求超时还是本地文件权限问题。
下载慢的问题,优先检查下载源是否走 CDN、当前网络到目标服务器的延迟是否过高、本地磁盘是否充足,而不是盲目重复执行安装命令。生产环境建议提前把依赖包和 Skill 资源准备好,离线安装,避免每次部署都重新拉取。
2.3 启动验证:安装完成不等于安装成功
安装完成的判断标准不是命令执行完,而是 Web 工作区能正常访问、Skill 列表能刷出来、模型配置能连通。
启动后先在浏览器打开工作区地址,通常是http://localhost:3000或终端提示的端口。然后检查三个点:
- 工作区页面是否正常渲染,控制台有没有红色报错。
- 左侧或设置中能否看到插件中心、Skill 列表入口。
- 能否配置模型并完成一次最简单的对话。
如果页面能打开但 Skill 列表为空,不要急着怀疑安装,先确认启动时是否加载了本地 skills 目录,以及该目录是否存在。这部分在创建 Skill 时很重要。
常见启动失败现象和初步定位方向如下:
| 现象 | 优先检查 | 可能原因 |
|---|---|---|
| 端口被占用 | `netstat -ano | findstr 3000` |
| 页面白屏 | 浏览器控制台 Network 面板 | 前端资源未构建完成 |
| 依赖安装报错 | pnpm install日志 | Node/pnpm 版本不匹配 |
| 插件中心加载失败 | 终端网络请求日志 | 插件列表接口无法访问 |
注意:安装阶段不要一次性装很多插件。先确认框架本身能启动,再逐个安装 Skill,出现问题时才能准确判断是框架问题还是 Skill 问题。
3. 创建第一个 Skill:目录、清单文件与最小示例
3.1 Skill 的目录结构
理解 Skill 的最佳方式是自己创建一个。先不追求复杂,只做一个“根据输入材料生成当日工作日报”的最小 Skill。这个 Skill 能覆盖 Skill 的三要素:元信息、指令、输出规范。
在 Harness 工作区中,Skill 通常放在个人 skills 目录下。具体路径因版本而异,常见结构如下:
skills/ └── daily-report/ ├── SKILL.md ├── scripts/ │ └── format_report.py ├── templates/ │ └── report_template.md └── examples/ └── example_input.json每个 Skill 一个目录,目录名使用小写连字符命名,例如daily-report、ppt-creator、ui-ux-pro-max。目录内必须有一个SKILL.md作为入口文件,其他脚本、模板、示例按需组织。
这里要注意命名规范。不要使用中文目录名,不要带空格,不要使用大写字母。目录名会成为 Skill 的唯一标识,后续命令行操作、分享打包都依赖这个名字。
3.2 SKILL.md 清单文件怎么写
SKILL.md是 Skill 的核心文件,作用有两个:一是给 Harness 提供元信息,二是给 Agent 提供执行指令。文件头部使用 YAML frontmatter 记录元信息,正文部分描述任务流程和输出规范。
一个最小可用的SKILL.md示例如下:
--- name: daily-report description: 根据当日工作输入生成结构化日报,适用于开发人员每日工作总结。 version: 0.1.0 author: your-name license: MIT tags: - report - daily - productivity dependencies: - python: 3.8+ ---正文部分需要写清楚任务的输入格式、处理步骤、输出格式和判断标准。不要让 Agent 自由发挥,而是给出明确的约束:
# 任务目标 根据用户提供的当日工作内容,生成一份结构清晰的日报。 # 输入 用户会提供以下信息: - 完成事项列表 - 遇到的问题 - 明日计划 # 处理步骤 1. 将完成事项按影响范围排序,优先展示对项目和用户影响最大的事项。 2. 遇到问题时补充解决方案,没有解决方案的标记为“待跟进”。 3. 明日计划只保留可执行项,禁止写模糊描述。 # 输出格式 严格使用 Markdown 输出,包含四个小节: - 今日完成 - 问题与对策 - 明日计划 - 风险提醒正文不要太短。Agent 需要理解“好”和“不好”的区别,只写一句“生成日报”没有约束力。描述越具体,输出越稳定。
3.3 最小可运行的 Skill 脚本
当 Skill 需要本地处理数据时,可以携带脚本。下面是一个用 Python 实现的日报格式化脚本,接收 JSON 输入,输出 Markdown 日报:
import json import sys def main(): data = json.load(sys.stdin) items = data.get("completed", []) problems = data.get("problems", []) plans = data.get("plans", []) print("# 今日日报") print("## 今日完成") for item in items: print(f"- {item}") print("## 问题与对策") for problem in problems: print(f"- 问题:{problem.get('desc', '')}") print(f" 对策:{problem.get('solution', '待跟进')}") print("## 明日计划") for plan in plans: print(f"- [ ] {plan}") if __name__ == "__main__": main()使用方式是把当日数据写入 JSON 文件,再通过管道交给脚本:
echo '{"completed": ["完成登录模块重构", "修复接口超时问题"], "problems": [{"desc": "缓存过期策略不明确", "solution": "加入过期时间配置"}], "plans": ["补充单元测试"]}' | python scripts/format_report.py输出如下:
# 今日日报 ## 今日完成 - 完成登录模块重构 - 修复接口超时问题 ## 问题与对策 - 问题:缓存过期策略不明确 对策:加入过期时间配置 ## 明日计划 - [ ] 补充单元测试脚本的价值在于把“校验和格式化”从模型能力中拆出来。模型负责理解输入、提取信息,脚本负责按固定逻辑输出。这样格式永远不会因为模型状态变化而漂移。
3.4 加载、验证与调试自己的 Skill
Skill 目录创建完成后,需要在 Harness 中刷新或重新加载 Skill 列表。常见 CLI 命令示例如下:
dsh skill list dsh skill reload daily-report如果你的版本没有dsh skill系列命令,在 Web 工作区的设置页找到“Skills”或“能力”标签页,手动刷新。加载成功后,用一句话触发测试:
请根据我提供的工作记录,生成今天的日报。验证输出时不要只看格式对不对,还要检查三点:
- 输入信息是否被正确提取,有没有遗漏关键事项。
- 问题是否有解决方案,没有方案的是否标记为待跟进。
- 输出是否严格遵循了 SKILL.md 中的结构要求。
如果输出不符合要求,优先修改SKILL.md正文,而不是改模型提示。Skill 的调试本质上是在调整规则边界,让 Agent 知道什么能做、什么不能做、按什么格式交付。
提醒:不要用“能跑通”作为 Skill 验收标准。Skill 是给别人和未来的自己复用的,输入边界、输出格式、异常情况都要在说明里写清楚。
4. 安装 PPT Skill 与 UI 设计 Skill:从下载到参数调优
4.1 PPT Skill 的典型能力和使用流程
搜索热词中频繁出现 “PPT skill” 和 “Hermes 编写 PPT skill”,说明 PPT 生成是目前需求量最大的 Skill 场景之一。PPT Skill 通常把一个完整幻灯片拆解为信息架构、页面文案、视觉风格、导出格式几个阶段,让 Agent 先规划结构再生成内容。
一个 PPT Skill 的典型执行流程如下:
- 用户输入主题、目标听众、页数和风格偏好。
- Skill 先输出大纲,等用户确认后再生成逐页内容。
- 每页包含标题、要点文案、配图建议或图表类型。
- 最终导出为 Markdown、HTML 或 PPTX 格式。
在安装时,要确认 Skill 支持哪种导出格式。有的 Skill 只输出结构化 Markdown,需要配合转换工具才能变成 PPTX;有的 Skill 直接生成 HTML 幻灯片。两者使用场景不同:Markdown 适合快速打草稿,HTML 适合视觉要求更高的场合。
安装后第一次使用,建议用一个信息完整的小题目测试,例如“为团队周会制作 5 页项目进度汇报 PPT”。不要一上来就生成 50 页的正式汇报,否则很难判断是 Skill 规则问题还是模型能力问题。
4.2 UI 设计 Skill:UI-UX-Pro-Max 为什么强调规范
UI 设计 Skill 和 PPT Skill 不同,它关注的不是页面有没有,而是页面是否符合一套明确的视觉规范。热词里提到的 “UI-UX-Pro-Max” 属于这类 Skill 的代表,定位是用于政府、企业级项目的界面设计规范。
这类 Skill 通常会内置:色彩体系、字号层级、间距规则、圆角与阴影规范、组件状态说明、无障碍对比度要求。它适合用来做两件事:
一是生成新的界面方案。Agent 按规范输出页面结构、配色、字号和组件说明,设计师或前端可以直接据此实现。
二是评审已有界面。把设计稿或代码片段交给 Skill,它会对照规则检查颜色对比度是否达标、交互状态是否完整、间距是否符合规范。
使用 UI 设计 Skill 时要特别注意它的目标受众设定。政府和企业级项目对稳重、可读性、合规性的要求远高于个人创意项目。安装后先确认默认参数中的“风格倾向”“主色色板”“字号单位”是否匹配当前项目,不要直接套默认值。
4.3 安装与启用流程
安装现成 Skill 的常见方式有两种。一种是从插件中心直接安装,另一种是从 Git 仓库拉取后放入本地 skills 目录。
方式一:从插件中心安装
dsh skill install ppt-creator dsh skill install ui-ux-pro-max方式二:手动拉取仓库放入 skills 目录
git clone https://example.com/skills/ui-ux-pro-max.git mkdir -p <harness-workspace>/skills cp -r ui-ux-pro-max <harness-workspace>/skills/手动安装时要特别注意目录层级。如果仓库克隆下来包含二级目录,需要把包含SKILL.md的那一层放到 skills 目录下,而不是把整个仓库文件直接堆进去。放错层级会导致 Harness 扫描不到 Skill。
安装完成后执行:
dsh skill list确认两个 Skill 都出现在列表中。如果列表中没有,检查目录名、SKILL.md是否在正确位置、文件编码是否为 UTF-8。
4.4 PPT 与 UI Skill 的关键参数
不同 Skill 的参数设计不同,但常见的配置维度可以整理成速查表,方便安装后快速对齐:
| 参数类型 | 常见参数 | 默认值示例 | 调大/调小的效果 |
|---|---|---|---|
| PPT 页数 | max_slides | 10 | 调大容易内容发散,调小信息密度过高 |
| PPT 风格 | style | business | 切换为 creative 时配色和排版会变化 |
| 输出格式 | output_format | markdown | 改为 pptx 时需要额外转换依赖 |
| UI 风格倾向 | design_style | enterprise | 改为 modern 后视觉更轻快 |
| 主色体系 | primary_color | #1664FF | 影响全部页面组件配色 |
| 字号单位 | font_scale | 1.0 | 调大适合大屏投放,调小适合移动端 |
| 对比度要求 | min_contrast_ratio | 4.5 | 调高更无障碍友好,但配色空间变小 |
参数不要一次全改。先保留默认值跑通一次,再逐个调整,观察输出差异。如果某个参数修改后输出反而变差,优先回滚该参数,而不是继续叠加其他修改。
这里要注意一个常见坑:PPT Skill 的style参数和output_format参数经常被混淆。style控制的是视觉风格,output_format控制的是交付格式。把style设成pptx并不会导出 PPTX 文件,两者是不同维度的配置。
5. 个人 Skill 的组织、分享与工作区管理
5.1 工作区、插件中心与个人 skills 目录的关系
DeepSeek Harness 中有三个容易混淆的概念:工作区(Workspace)、插件中心(Plugin Center)和个人 skills 目录。
工作区是 Harness 的运行时环境,包含当前项目的对话记录、Skill 加载状态、配置文件和附件。插件中心是获取现成 Skill 和插件的渠道。个人 skills 目录是本地存放自定义 Skill 的地方,通常位于工作区目录下,也可以手动指定其他路径。
三者的关系可以这样理解:插件中心是“商店”,个人 skills 目录是“本地仓库”,工作区是“货架”。从商店买来的 Skill、自己开发的 Skill,都要放到货架上才会被 Agent 看到。
归档对话这个问题在热词中出现过。归档功能通常在工作区的对话列表入口,归档后会话不再出现在主列表,但记录并不会删除。需要找回时到归档列表或历史记录中搜索。如果你的版本里找不到归档入口,检查是否为 Web 工作区版本,或查看设置中的存储路径。
5.2 组织个人 skills 的最佳实践
个人 Skill 多了以后,最怕的不是不会创建,而是找不到、分不清、改出问题。按以下方式组织可以明显降低维护成本。
推荐目录结构:
skills/ ├── report/ │ ├── daily-report/ │ └── weekly-report/ ├── presentation/ │ ├── ppt-creator/ │ └── ppt-review/ ├── design/ │ └── ui-ux-pro-max/ └── shared/ └── common-rules/同类 Skill 放进同一个父目录,用语义明确的父目录分组。shared目录放跨场景复用的规则,例如“面向政务项目的通用文案规范”。分组完成后,每次新增 Skill 先想清楚属于哪个域,避免重复创建功能相近的 Skill。
版本管理方面,建议每个 Skill 目录独立使用 Git 仓库。这样当你修改了ppt-creator的规则,不会影响daily-report的版本历史。Skill 内部升级时,修改SKILL.md中的version字段,并在变更记录里写清楚变化内容。
5.3 分享 Skill 的打包规范
个人 Skill 分享出去之前,要保证别人拿到后能安装、能运行、能理解。分享格式建议统一为一个压缩包,内部结构如下:
daily-report-v0.1.0.zip ├── SKILL.md ├── scripts/ │ └── format_report.py ├── templates/ │ └── report_template.md ├── examples/ │ └── example_input.json └── README.mdREADME 里至少写清楚:适用场景、输入要求、输出格式、依赖环境、示例用法、常见问题。不要假设别人和你使用完全相同的 Harness 版本,README 中要注明经过验证的版本范围。
打包前检查以下几点:
- 目录名与
SKILL.md中的name字段一致。 - 示例文件能独立运行,示例数据可复现。
- 依赖的脚本、模板、第三方库全部列出。
- 不包含本地绝对路径、个人密钥和内部敏感信息。
- README 中标注了作者、版本、授权协议。
分享后别人遇到的问题,本质上是你文档没写清楚。与其反复回答“怎么装”,不如把 README 写完整。这也是 Skill 和普通脚本分享最大的区别:Skill 分享的是“标准”,不只是“代码”。
6. 安装与使用中的常见报错、排查链路
6.1 安装阶段:卡在 pnpm、下载慢、页面打不开
安装阶段的问题集中在依赖安装和启动两个环节。建议按以下顺序排查:
先确认基础版本:
node -v pnpm -v git --version再确认依赖安装状态:
pnpm install --frozen-lockfile如果安装卡住,优先怀疑网络。更换镜像源后重新安装,同时观察是否出现具体的错误码,而不是无限等待。如果dsh web启动后一直没有反应,使用 Ctrl+C 中断,查看堆栈输出中最后一条日志,通常能定位到是请求超时还是文件写入失败。
端口占用也是常见问题。启动前先检查端口:
netstat -ano | findstr :3000找到占用进程后按需结束进程,或使用 Harness 配置修改监听端口。
热词中出现的“下载慢”“卡在安装”通常可以归纳为网络源不稳定、镜像源未配置、磁盘空间不足三类。建议把镜像源配置、磁盘清理、超时时间加大作为预防手段,而不是反复重试。
6.2 加载 Skill 阶段:列表里找不到、扫描不到
Skill 文件夹放好后,列表里找不到是最常见的问题。按这条链路排查:
- 检查目录位置是否正确。
SKILL.md所在目录必须位于 Harness 扫描路径下。 - 检查目录层级。如果
SKILL.md被嵌套在两级目录以下,Harness 可能识别不到。 - 检查文件名。
SKILL.md不能写成skill.md、Skill.md或其他变体。 - 检查文件编码。UTF-8 编码最稳妥,UTF-8 with BOM 可能导致 frontmatter 解析异常。
- 检查 YAML 语法。
name字段与目录名不一致,或缺少description字段,都可能导致加载失败。 - 查看终端日志。加载失败一般会输出具体 Skill 名称和错误原因。
手动安装的 Skill 最好先用dsh skill list验证,再进入 Web 工作区使用,避免二次排查。
6.3 运行 Skill 阶段:输出格式错、依赖缺失、结果不稳定
Skill 能加载,但运行结果不理想,问题通常出在指令描述或资源依赖上。
输出格式错乱:优先检查SKILL.md中的输出格式约束是否足够具体。只写“输出 Markdown”不够,要写清楚 Markdown 的结构,最好给出示例片段。如果 Skill 带有格式化脚本,确认脚本是否被正确调用。
依赖缺失:Skill 提示缺少 Python 包或 Node 模块时,进入 Skill 目录检查依赖声明。建议在SKILL.md或 README 中列出依赖清单,并在脚本中加入启动前的依赖检查。
结果不稳定:同样的输入,两次输出差异很大,说明规则约束不足。这时不要盲目加长提示词,而是把“必须做的事”和“禁止做的事”分别列出,并补充正反例。模型对“不要输出超长段落”的理解远不如“每个要点不超过 50 字”清晰。
6.4 常见问题速查表
把前面提到的典型问题汇总成一张排查表,方便遇到问题时快速定位:
| 问题现象 | 优先检查 | 常见原因 | 处理方式 |
|---|---|---|---|
安装卡在pnpm install | 镜像源配置 | 默认源访问慢 | 切换镜像源后重装 |
dsh web启动无响应 | 终端最后一条日志 | 初始化下载资源超时 | 加大超时时间或手动放置资源 |
| 端口被占用 | 端口监听状态 | 上次进程未退出 | 结束占用进程或改端口 |
| Skill 列表为空 | 目录层级 | Skill 目录位置不对 | 把SKILL.md放到扫描目录下 |
SKILL.md解析失败 | YAML frontmatter | 字段缺失或编码错误 | 检查字段和 UTF-8 编码 |
| Skill 能加载但输出乱 | 指令约束不足 | 输出规范不具体 | 补充格式约束和正反例 |
| 脚本运行报错 | 依赖环境 | 缺少 Python 包或 Node 模块 | 安装依赖并声明依赖清单 |
| 参数修改无效果 | 生效方式 | 需要重启或重新加载 | 确认是否需要 reload |
排查优先级永远是:输入是否正确 -> 路径和命名是否正确 -> 依赖版本是否匹配 -> 配置是否生效 -> 日志是否出现明确异常。不要一上来就怀疑框架有 bug。
7. 最佳实践与下一步方向
7.1 可复用的 Skill 发布前检查清单
每次新建或修改 Skill 后,按这份清单检查一遍,可以省掉大量后续沟通成本:
- 目录名和
name字段一致,命名使用小写连字符。 SKILL.md包含 name、description、version 三个必填字段。- description 描述清楚适用场景和输入要求,方便 Agent 自动判断是否调用。
- 正文包含输入格式、处理步骤、输出格式、禁止事项。
- 输出格式足够具体,配有示例片段。
- 脚本依赖已声明,脚本路径在 README 中说明。
- 示例输入可复现,示例输出与脚本逻辑一致。
- 不含绝对路径、个人密钥、内部敏感信息。
- README 写清适用版本、安装方式、常见问题。
- 版本号已更新,变更记录已补充。
7.2 什么场景该用 Skill、Agent 还是 MCP
选型时不要被新概念带偏。判断标准始终是:任务边界是否清晰、输出是否要标准化、是否需要外部数据连接。
任务边界清晰、输出需要标准化的能力,做成 Skill。例如日报、周报、PPT 大纲生成、UI 规范审查,这些都是高频、重复、输出结构固定的任务。
需要多步骤编排、带上下文记忆和分支判断的完整任务链,使用 Agent。例如“从需求文档提取信息 -> 排期 -> 生成任务 -> 写入项目管理工具”,这属于 Agent 编排,可以拆成多个 Skill,但整体流程由 Agent 控制。
需要访问外部数据源或调用第三方接口时,使用 MCP。例如查询数据库、调 CRM 接口、读取云存储文件。
实际落地最常见的组合是:Agent 编排流程,Skill 保证单任务质量,MCP 打通数据链路。三者不是三选一,而是不同层级的组合。
7.3 下一步可以扩展的方向
对新手来说,最值得做的练习不是安装更多 Skill,而是把日常重复工作拆成 Skill。可以从三个方向开始:
第一,把“日报”升级为“项目周报”,加入数据统计脚本,自动读取本周提交记录,生成风险提醒。第二,把 PPT Skill 与公司内部模板结合,内置品牌色、标准字号、固定排版规范,形成团队专用版本。第三,把 UI 设计 Skill 与前端代码审查结合,形成“设计规范检查 + 代码输出”的闭环。
再往后,就是把自己沉淀的 Skill 整理成个人技能库,按业务域分类、用 Git 管理版本、写清楚 README,在团队内部形成可复用的能力资产。
DeepSeek Harness 这类 Agent 框架的价值,不在于模型有多强,而在于它让“稳定做事”这件事变得可沉淀。你不需要每次重新写提示词,也不需要记住每个任务的细节,只要把标准固化到 Skill 里,Agent 就能按你的要求反复交付。对开发者来说,掌握 Skill 的创建、安装、分享和排错,就是掌握 Agent 工程化的基本盘。