最近在折腾 DeepSeek Harness 和 Agent Skill 的时候发现一个很普遍的现象很多同学把工具装好之后就卡在“ Skill 到底怎么创建”“它和插件、Agent、MCP 有什么区别”这一步。尤其是看到pnpm dsh web卡住、下载慢、插件中心不知道装哪一个这类问题网上资料又零散不成体系很容易劝退。这篇文章会把我的完整实操过程整理成一份可以直接照做的教程内容包括DeepSeek Harness 的安装方式、桌面端与 Docker 部署思路Skill、Agent、MCP 三者的区别与使用边界从零创建一个 PPT Skill让 Agent 自动生成可编辑的 .pptx 文件从零创建一个 UI 设计 Skill约束 Agent 输出规范的前端代码个人 Skills 的导出、分享和导入方法安装和使用过程中的高频报错与排查思路。不管你是第一次接触 Agent 工具还是已经在用其他 Skill 体系这篇文章都能帮你把“技能”这件事真正落地。1. 背景与核心概念1.1 DeepSeek Harness 是什么DeepSeek Harness 可以理解为一套围绕大模型搭建的 Agent 工作台。它把模型调用、上下文管理、工具调用、技能注册、会话归档等能力整合到一个可视化界面里你可以把它当成一个“给 AI 用的 IDE”。从常见的使用方式来看它具备几个典型能力工作区管理将不同项目、不同场景的会话拆开避免上下文互相污染插件扩展通过插件中心安装第三方能力类似 VS Code 的扩展市场Skill 技能体系把某一类任务所需的知识、流程、脚本封装成一个可复用的“技能包”对话归档将历史会话保存在本地方便后续检索和复盘视觉识别部分版本支持图片输入配合多模态模型完成截图分析、UI 走查等任务。这里要说明一下DeepSeek Harness 这类工具迭代非常快不同版本在界面名称、配置项、命令上会有差异。本文以常见社区版本的用法为例重点演示通用思路你安装的版本如果有个别出入以实际界面提示为准。1.2 Agent Skill 是什么Agent Skill 本质上是一个“预先封装好的能力包”。它不是一个跑在后台的独立程序而是一组规则、提示词、脚本和资源的集合告诉 Agent遇到什么任务时应该按什么步骤做、参考什么资料、调用什么工具、输出什么格式。举例来说你经常需要写日报。如果每次都临时让 Agent“帮我写一份日报”它可能每次的格式都不一样甚至会漏掉关键字段。但如果你给它注册一个daily-report技能技能内部写清楚“日报结构、填写规范、输出模板”那么 Agent 每次写日报都会遵循这套约定输出质量就稳定得多。Skill 的经典文件结构一般是一个目录里面至少包含一个SKILL.md文件。SKILL.md既描述了技能的用途也包含了 Agent 执行任务时需要遵循的完整指令。1.3 Skill、Agent、MCP 到底有什么区别这是新手最容易混淆的一组概念我用一个表格来对比概念本质类比典型用途Skill技能一组指令 示例 脚本的静态包装一本“上岗手册”规范 Agent 执行某类重复任务的步骤和输出格式Agent智能体具备推理、规划、工具调用能力的执行体一个“员工”自主拆解任务、决定调用什么工具、按顺序执行MCP一种连接模型与外部工具的协议一根“标准插线板”让 Agent 统一接入文件系统、数据库、HTTP API 等外部能力Skill 和 Agent 的关系是Agent 负责“动脑”Skill 负责“提供方法和约束”。一个 Agent 可以拥有多个 Skill在执行任务时根据任务类型选择对应技能。MCP 则更底层一些。它解决的是“Agent 如何标准地调用外部工具”的问题。Skill 里面也可以写“调用某个 MCP 工具”两者并不冲突。你可以这样理解MCP 是水管和接口Skill 是装修方案。有一个很典型的提问写日报到底用 Skill 还是 Agent如果日报格式固定、步骤固定那用 Skill 就够了如果写日报还需要自动拉取 Git 提交记录、统计工时、给不同领导生成不同版本那就需要 Agent 配合 Skill 和外部工具一起完成。实际项目中通常是“Agent Skill MCP”组合使用。2. 环境准备与安装2.1 安装前提在开始安装 DeepSeek Harness 之前先确认本地环境满足基本要求。下面是我的环境参考你的版本可以略有差异重点看思路操作系统Windows 11 / macOS 13 Node.js18 LTS 或更高版本 包管理器pnpm 8 Git任意较新版本为什么要强调 Node.js 和 pnpm因为 DeepSeek Harness 的很多安装命令都依赖它们比如常见的pnpm dsh web。如果你之前只装过 npm建议先全局安装 pnpmnpm install -g pnpm安装完成后用下面的命令确认版本node -v pnpm -v git --version如果你已经安装了桌面版安装包可以直接跳过下面两步从 2.4 节开始看配置。2.2 源码方式安装源码方式适合希望自定义扩展、参与插件开发的用户。整体流程是拉取代码、安装依赖、启动服务。# 1. 拉取项目代码仓库地址以实际为准 git clone deepseek-harness 仓库地址 cd deepseek-harness # 2. 安装依赖 pnpm install # 3. 启动 Web 端 pnpm dsh web执行完第 3 步后终端会输出一个本地访问地址通常是http://localhost:3000或类似端口。打开浏览器即可进入工作台。注意事项如果pnpm install非常慢先检查是不是没有配置镜像源后面的常见问题章节会给解决方案pnpm dsh web如果长时间卡住不动大概率是依赖没有安装完整而不是程序坏了。2.3 桌面端与 Docker 部署如果不希望折腾 Node.js 环境可以直接下载桌面版安装包。Windows 用户下载.exe安装包macOS 用户下载.dmg安装包安装过程和其他桌面软件没有区别。对于服务器部署或者想保持本地环境干净的同学可以用 Docker 方式。这里给一个通用示例# 构建镜像镜像名和 Dockerfile 以项目实际为准 docker build -t deepseek-harness . # 启动容器将宿主机端口映射到容器端口 docker run -d -p 3000:3000 deepseek-harnessDocker 方式的好处是隔离性好换机器也能快速复现同一套环境。如果你要把工作区数据持久化可以额外挂载数据目录docker run -d \ -p 3000:3000 \ -v $PWD/harness-data:/app/data \ deepseek-harness2.4 安装后的基础配置进入工作台后优先完成三件事配置模型服务选择你使用的模型 API 服务填写对应的 API Key 或 Base URL。DeepSeek Harness 的优势在于可以兼容多种模型服务主模型和视觉模型可以分开配置。创建第一个工作区工作区是一个隔离的项目环境建议一个项目一个工作区避免会话互相干扰。打开技能管理页查看自带的 Skill 列表确认技能加载是否正常。完成这几步环境就基本可用了。接下来我们重点解决“技能怎么创建”的问题。3. Skill 的核心原理与文件结构3.1 Skill 的目录结构虽然不同工具对 Skill 的格式定义略有差别但主流的 Agent Skill 规范是高度相似的。一个 Skill 通常就是一个独立目录结构如下daily-report/ ├── SKILL.md ├── scripts/ │ └── format_report.py ├── templates/ │ └── report_template.md └── assets/ └── logo.png各组成部分的职责SKILL.md技能的核心说明文件Agent 会优先读取它scripts/存放可执行脚本比如格式化数据、生成文件templates/存放输出模板比如日报模板、PPT 模板assets/存放图片、字体、样式等静态资源。3.2 SKILL.md 的编写要点SKILL.md是 Agent 理解技能的关键入口。它的质量直接决定了技能好不好用。一份合格的SKILL.md应该包含以下几块内容区块作用示例元信息声明技能名称、用途、版本name: ppt-creator触发条件说明什么场景下应该使用这个技能用户提到“做PPT”时执行步骤给出明确的、可操作的步骤先确认主题再生成大纲最后出文件输出规范说明最终输出格式和验收标准输出 .pptx 文件页数 10 页以内注意事项列出容易出错的地方不要编造数据图表数据必须来自用户输入我用 Markdown 格式写一个最简示例--- name: daily-report description: 生成标准格式的日报 version: 1.0.0 --- # 日报生成技能 ## 触发条件 用户说“写日报”“生成今日日报”时使用。 ## 执行步骤 1. 询问今日完成的工作事项。 2. 按“今日进展 / 遇到的问题 / 明日计划”三部分整理。 3. 输出 Markdown 日报并保存到 reports 目录。 ## 输出规范 - 文件命名YYYY-MM-DD-report.md - 每部分使用二级标题 - 问题部分必须给出解决方案或待确认人3.3 Skill 与插件的边界在插件中心里你可能会看到“插件”和“技能”两个入口。它们的边界在哪里插件更偏向于“系统集成能力”比如接入某个外部 API、增加一个可视化面板技能更偏向于“指导 Agent 完成任务的方法论”。很多场景下插件提供能力底座技能定义使用方式两者互补。建议优先使用插件中心里已经封装好的官方插件再根据实际需求创建自己的 Skill。4. 实战从零创建一个 PPT Skill光讲概念没有用下面我们实际创建一个 PPT 生成 Skill。这个 Skill 的目标是用户给出主题后Agent 能够自动生成结构完整的 PPT 大纲并调用 Python 脚本生成一个可编辑的.pptx文件。4.1 需求拆解在写代码之前先拆解任务Agent 需要向用户确认演示主题、受众、页数Agent 根据主题生成大纲 JSON调用python-pptx脚本读取 JSON 并生成.pptx文件输出文件路径和内容摘要。这里选择python-pptx是因为它是生成 PowerPoint 文件最成熟的 Python 库之一。请确保环境里有 Python 3.9并安装依赖pip install python-pptx4.2 创建 Skill 目录在你的技能存放目录下新建一个文件夹ppt-creator/ ├── SKILL.md └── scripts/ └── generate_ppt.py技能目录放到哪里不同工具的配置不一样。一般你可以在工作台的“技能管理”里找到技能根目录然后直接把ppt-creator文件夹放进去。如果找不到可以在配置文件中指定skillsDir路径。4.3 编写 SKILL.md文件路径ppt-creator/SKILL.md--- name: ppt-creator description: 根据用户主题生成演示文稿输出可编辑的 .pptx 文件 version: 1.0.0 triggers: - 做PPT - 生成演示文稿 - 制作幻灯片 --- # PPT 生成技能 ## 使用步骤 1. 确认演示主题、目标受众、页数要求。 2. 生成内容大纲结构必须包含封面、目录、正文章节、总结页。 3. 将大纲保存为 outline.json格式如下 json { title: 演示标题, subtitle: 副标题, sections: [ { title: 章节标题, points: [要点1, 要点2, 要点3] } ] }调用脚本生成 pptx 文件python scripts/generate_ppt.py outline.json output.pptx向用户报告生成的文件路径并简要说明大纲结构。输出规范必须生成.pptx文件不要只给 Markdown 大纲。正文每页要点控制在 3 到 5 条不要出现整段文字。不要编造数据和信息来源。这里有两点要特别注意 - 我在 SKILL.md 里直接嵌入了 JSON 格式示例这样 Agent 就不需要“猜测”大纲格式降低生成误差 - 我把脚本调用命令写得很明确Agent 可以直接执行不需要二次思考。 ### 4.4 编写 PowerPoint 生成脚本 文件路径ppt-creator/scripts/generate_ppt.py python # -*- coding: utf-8 -*- import json import sys from pptx import Presentation from pptx.util import Inches def create_presentation(json_path: str, output_path: str) - None: 根据大纲 JSON 生成 PPT 文件。 with open(json_path, r, encodingutf-8) as f: data json.load(f) prs Presentation() # 使用内置版式0 标题幻灯片1 标题和内容 title_layout prs.slide_layouts[0] content_layout prs.slide_layouts[1] # 封面页 slide prs.slides.add_slide(title_layout) slide.shapes.title.text data.get(title, 无标题) if data.get(subtitle): slide.placeholders[1].text data[subtitle] # 内容页 for section in data.get(sections, []): slide prs.slides.add_slide(content_layout) slide.shapes.title.text section.get(title, 未命名章节) body slide.placeholders[1].text_frame points section.get(points, []) for i, point in enumerate(points): if i 0: body.text point else: p body.add_paragraph() p.text point prs.save(output_path) print(PPT 已生成: output_path) if __name__ __main__: if len(sys.argv) ! 3: print(用法: python generate_ppt.py 大纲.json 输出.pptx) sys.exit(1) create_presentation(sys.argv[1], sys.argv[2])这段脚本的逻辑很直接读取 JSON 大纲第一页用“标题幻灯片”版式后续每个章节用“标题和内容”版式每条要点作为一个段落写入内容占位符。4.5 测试与验证先在本机手动测试脚本确认环境没问题python scripts/generate_ppt.py outline.json test.pptx预期输出PPT 已生成: test.pptx然后在工作台里新建一个会话输入一句话请用 ppt-creator 技能生成一份“2025 年团队规划”的PPT受众是部门管理层8页左右。Agent 应该会先询问或确认信息然后生成大纲再调用脚本。最终你在工作区里能看到生成的.pptx文件。如果 Agent 没有调用技能优先检查SKILL.md里的触发词是否覆盖了用户问法或者确认技能是否已经加载到当前工作区。5. 实战创建一个 UI 设计 Skill第二个例子选 UI 设计 Skill是因为“让 AI 写界面”很容易失控输出风格不一致、颜色乱用、不考虑响应式。UI 设计 Skill 的核心价值就是给 Agent 一套“设计约束”。5.1 Skill 定位这个 Skill 的目标是用户描述一个页面需求后Agent 输出一个完整的 HTML 文件页面样式遵循预设的设计令牌Design Tokens、移动端优先、保证可访问性。目录结构如下ui-designer/ ├── SKILL.md └── templates/ └── page_template.html5.2 编写 SKILL.md文件路径ui-designer/SKILL.md--- name: ui-designer description: 根据需求生成遵循设计规范的 Web 页面代码 version: 1.0.0 triggers: - 设计页面 - 写前端 - 生成界面 --- # UI 设计技能 ## 设计约束 1. 使用设计令牌定义颜色、间距、圆角、字体禁止在组件中硬编码颜色值。 2. 移动端优先使用弹性布局和 Grid 实现响应式。 3. 输出单个完整的 HTML 文件CSS 写在 style 标签中。 4. 所有可交互元素必须支持键盘操作颜色对比度不低于 WCAG AA 标准。 5. 中文文案保持简洁按钮文字使用动词开头例如“提交表单”“导出数据”。 ## 标准设计令牌 css :root { --color-primary: #4F46E5; --color-primary-hover: #4338CA; --color-bg: #F9FAFB; --color-surface: #FFFFFF; --color-text: #111827; --color-text-secondary: #6B7280; --color-border: #E5E7EB; --color-danger: #DC2626; --spacing-xs: 4px; --spacing-sm: 8px; --spacing-md: 16px; --spacing-lg: 24px; --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --font-family: -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; }输出步骤确认页面用途、目标用户、主要操作。在回答中先列出页面区块结构。再输出完整 HTML 文件。最后用 2 到 3 句话说明设计决策。检查清单[ ] 是否使用设计令牌[ ] 是否能在 360px 宽度下正常显示[ ] 是否有 hover 和 focus 状态[ ] 是否包含语义化标签header、nav、main、footer这个 Skill 的精髓在于**把设计规范以检查清单的形式固化下来**。Agent 在输出完代码后会逐项自查这比单纯写“设计好看一点”有效得多。 ### 5.3 模板文件 文件路径ui-designer/templates/page_template.html html !DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title页面标题/title style :root { --color-primary: #4F46E5; --color-bg: #F9FAFB; --color-surface: #FFFFFF; --color-text: #111827; --spacing-md: 16px; --radius-md: 8px; } * { box-sizing: border-box; } body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; background: var(--color-bg); color: var(--color-text); } .container { max-width: 480px; margin: 0 auto; padding: var(--spacing-md); } .card { background: var(--color-surface); border-radius: var(--radius-md); padding: var(--spacing-md); margin-bottom: var(--spacing-md); } button { width: 100%; padding: 12px; border: none; border-radius: var(--radius-md); background: var(--color-primary); color: #fff; font-size: 16px; cursor: pointer; } button:hover { opacity: 0.9; } button:focus-visible { outline: 2px solid #111827; outline-offset: 2px; } media (min-width: 768px) { .container { max-width: 720px; } } /style /head body main classcontainer section classcard h1页面标题/h1 p页面描述文案。/p button typebutton主要操作/button /section /main /body /html模板文件的作用是给 Agent 一个“起点”它可以在模板基础上扩展而不是每次从零开始写样式。5.4 使用效果参考在工作台里输入用 ui-designer 技能设计一个“登录页面”包含用户名、密码、登录按钮和忘记密码链接。Agent 会先列出区块结构再输出完整 HTML并根据检查清单自查。这里的关键不是代码本身有多炫而是输出结果稳定、风格统一后续交给其他工程师维护也更容易。6. 个人 Skills 的分享与导入做完两个技能下一步就是分享。个人 Skills 的分享方式主要有三种6.1 直接复制目录最简单的方式直接把技能目录压缩成 zip发给同事。对方解压后放到自己的技能根目录即可。zip -r ppt-creator.zip ppt-creator/6.2 使用 Git 仓库管理推荐把个人 Skills 统一放在一个 Git 仓库里方便版本管理。例如my-skills/ ├── README.md ├── ppt-creator/ ├── ui-designer/ └── daily-report/在README.md中写清楚每个技能的用途和依赖# 个人技能仓库 ## ppt-creator - 用途生成 .pptx 演示文稿 - 依赖python-pptx - 安装将 ppt-creator 目录复制到技能根目录其他人克隆仓库后将对应目录复制到自己的工作台技能目录中就能直接使用。6.3 通过插件中心或市场分发如果你的工具提供了插件中心可以考虑把技能打包成符合平台规范的插件上传。这种方式适合分发范围较广的技能。不同平台的打包规范略有差异上传前先阅读对应平台的开发者文档。在分享技能时有几个原则不要内置敏感信息比如 API Key、数据库连接串脚本依赖要在SKILL.md中写清楚最好在技能内附带requirements.txt给技能写上版本号方便使用者识别版本差异。7. 常见问题与排查思路下面整理安装和使用 DeepSeek Harness、Agent Skill 时的高频问题。问题现象常见原因解决思路pnpm dsh web卡住不动依赖安装不完整或网络原因删除 node_modules 重装或配置镜像源下载依赖速度极慢默认源访问慢配置 npmmirror 镜像Windows 上安装失败权限不足或执行策略限制以管理员身份运行 PowerShell调整执行策略Agent 不调用已创建的 Skill触发词不匹配或技能未加载检查 SKILL.md 触发词确认技能目录已识别生成的 PPT 打不开python-pptx 版本问题升级 python-pptx 到最新版视觉识别功能不可用未配置多模态模型在设置中为视觉任务单独配置视觉模型找不到归档对话数据目录配置不同在工作区数据目录中查找 JSON/Markdown 归档文件部分安装流程卡在 modlens 组件网络原因或组件下载失败先跳过该组件主流程完成后单独重试下面挑几个典型问题展开说明。7.1 安装卡在pnpm dsh web这个报错非常典型很多人的第一反应是觉得程序坏了其实大部分原因是依赖没有下载完整。排查步骤如下先回到项目目录删除node_modulesrm -rf node_modules确认 pnpm 镜像源pnpm config get registry如果返回的不是国内镜像可以临时设置pnpm config set registry https://registry.npmmirror.com重新安装依赖pnpm install pnpm dsh web如果仍然卡住把终端切到英文环境再看报错信息。很多中文环境下编码问题会掩盖真实错误。7.2 安装时提示需要 modlens 组件部分版本在安装或启动时会请求安装 modlens 组件它通常用于模型输出观测或链路评估。如果长时间卡在这一步可以先取消或跳过该步骤等主程序启动后再单独处理。不同版本的提示文案不同以你的安装程序实际提示为准。7.3 Agent 不识别技能创建了技能但 Agent 就是不调用这时候优先检查三点技能目录是否在正确的根目录下SKILL.md中是否有明确的触发词会话是否加载了该技能。很多工具的技能加载不是即时的需要重新启动工作台或点击“刷新技能”按钮。如果还不生效试试在会话中直接点名技能名称例如“使用 ppt-creator 技能”。7.4 视觉识别不可用视觉识别依赖多模态模型。如果你的主模型是纯文本模型图片识别自然不可用。解决办法是在配置中单独指定一个支持视觉的模型作为视觉模型。此外图片路径必须是 Agent 可以访问的本地路径或可访问的 URL。8. 最佳实践与工程建议8.1 Skill 的命名与职责划分每个 Skill 只做一件事做深做透。命名遵循“动词-对象”的规则例如ppt-creator、daily-report、ui-designer。不要创建一个“万能技能”职责越多指令越复杂Agent 反而越容易执行偏差。8.2 指令要可验证在SKILL.md里尽量加入“检查清单”和“验收标准”。例如 PPT 技能要求“必须生成 .pptx 文件”UI 技能要求“颜色必须来自设计令牌”。这些约束让 Agent 的输出可以被自动验证出现问题时也能快速定位。8.3 版本控制与依赖管理Skills 本质上是代码资产建议纳入 Git 管理。每次修改SKILL.md或脚本后更新版本号并在变更记录中说明改动内容。如果技能依赖 Python 包或 Node 包要在技能目录中附上依赖清单ppt-creator/requirements.txtpython-pptx0.6.218.4 安全边界技能中可能包含脚本这意味着 Agent 会基于技能内容执行代码。安全方面要特别注意不在技能中硬编码任何密钥脚本不做危险操作比如删除文件、修改系统配置如果技能需要访问网络或数据库明确限制访问范围遵循最小权限原则从外部导入技能时先审查SKILL.md和脚本内容再加载到工作台。8.5 日志与可观测性使用技能时遇到问题优先查看工作台的日志输出。Agent 在执行技能时会记录调用了哪个文件、执行了什么命令、输出是什么。养成“先看日志再猜原因”的习惯排查效率会高很多。9. 总结与下一步学习路线这篇文章从概念到实战完整走了一遍 DeepSeek Harness 和 Agent Skill 的使用流程。核心收获可以归纳为四点理解了 Skill、Agent、MCP 三者的区别Skill 提供方法Agent 负责执行MCP 打通外部工具掌握了 Skill 的基本目录结构知道SKILL.md是技能的核心入口通过ppt-creator和ui-designer两个实战案例学会了把重复任务封装成技能了解到个人 Skills 可以通过目录复制、Git 仓库、插件中心三种方式分享。下一步如果想继续深入可以往这几个方向走尝试为自己的日常高频任务创建技能比如周报、会议纪要、代码审查记录学习 MCP 协议把你常用的内部系统通过 MCP 接入 Agent研究插件开发把 Skill 升级成带可视化面板的完整插件优化技能提示词用更多真实案例测试逐步收敛触发条件和输出格式。技术在快速变化但“把重复劳动固化下来”的思路不会过时。建议你先从今天这两个实战案例开始动手建一个属于你自己的技能仓库遇到问题随时翻翻本文的排查表。如果你在创建 Skill 或安装过程中有其他报错欢迎在评论区带上终端日志一起讨论。 DeepSeek Harness与Agent Skill实战：从概念到技能创建指南
最近在折腾 DeepSeek Harness 和 Agent Skill 的时候发现一个很普遍的现象很多同学把工具装好之后就卡在“ Skill 到底怎么创建”“它和插件、Agent、MCP 有什么区别”这一步。尤其是看到pnpm dsh web卡住、下载慢、插件中心不知道装哪一个这类问题网上资料又零散不成体系很容易劝退。这篇文章会把我的完整实操过程整理成一份可以直接照做的教程内容包括DeepSeek Harness 的安装方式、桌面端与 Docker 部署思路Skill、Agent、MCP 三者的区别与使用边界从零创建一个 PPT Skill让 Agent 自动生成可编辑的 .pptx 文件从零创建一个 UI 设计 Skill约束 Agent 输出规范的前端代码个人 Skills 的导出、分享和导入方法安装和使用过程中的高频报错与排查思路。不管你是第一次接触 Agent 工具还是已经在用其他 Skill 体系这篇文章都能帮你把“技能”这件事真正落地。1. 背景与核心概念1.1 DeepSeek Harness 是什么DeepSeek Harness 可以理解为一套围绕大模型搭建的 Agent 工作台。它把模型调用、上下文管理、工具调用、技能注册、会话归档等能力整合到一个可视化界面里你可以把它当成一个“给 AI 用的 IDE”。从常见的使用方式来看它具备几个典型能力工作区管理将不同项目、不同场景的会话拆开避免上下文互相污染插件扩展通过插件中心安装第三方能力类似 VS Code 的扩展市场Skill 技能体系把某一类任务所需的知识、流程、脚本封装成一个可复用的“技能包”对话归档将历史会话保存在本地方便后续检索和复盘视觉识别部分版本支持图片输入配合多模态模型完成截图分析、UI 走查等任务。这里要说明一下DeepSeek Harness 这类工具迭代非常快不同版本在界面名称、配置项、命令上会有差异。本文以常见社区版本的用法为例重点演示通用思路你安装的版本如果有个别出入以实际界面提示为准。1.2 Agent Skill 是什么Agent Skill 本质上是一个“预先封装好的能力包”。它不是一个跑在后台的独立程序而是一组规则、提示词、脚本和资源的集合告诉 Agent遇到什么任务时应该按什么步骤做、参考什么资料、调用什么工具、输出什么格式。举例来说你经常需要写日报。如果每次都临时让 Agent“帮我写一份日报”它可能每次的格式都不一样甚至会漏掉关键字段。但如果你给它注册一个daily-report技能技能内部写清楚“日报结构、填写规范、输出模板”那么 Agent 每次写日报都会遵循这套约定输出质量就稳定得多。Skill 的经典文件结构一般是一个目录里面至少包含一个SKILL.md文件。SKILL.md既描述了技能的用途也包含了 Agent 执行任务时需要遵循的完整指令。1.3 Skill、Agent、MCP 到底有什么区别这是新手最容易混淆的一组概念我用一个表格来对比概念本质类比典型用途Skill技能一组指令 示例 脚本的静态包装一本“上岗手册”规范 Agent 执行某类重复任务的步骤和输出格式Agent智能体具备推理、规划、工具调用能力的执行体一个“员工”自主拆解任务、决定调用什么工具、按顺序执行MCP一种连接模型与外部工具的协议一根“标准插线板”让 Agent 统一接入文件系统、数据库、HTTP API 等外部能力Skill 和 Agent 的关系是Agent 负责“动脑”Skill 负责“提供方法和约束”。一个 Agent 可以拥有多个 Skill在执行任务时根据任务类型选择对应技能。MCP 则更底层一些。它解决的是“Agent 如何标准地调用外部工具”的问题。Skill 里面也可以写“调用某个 MCP 工具”两者并不冲突。你可以这样理解MCP 是水管和接口Skill 是装修方案。有一个很典型的提问写日报到底用 Skill 还是 Agent如果日报格式固定、步骤固定那用 Skill 就够了如果写日报还需要自动拉取 Git 提交记录、统计工时、给不同领导生成不同版本那就需要 Agent 配合 Skill 和外部工具一起完成。实际项目中通常是“Agent Skill MCP”组合使用。2. 环境准备与安装2.1 安装前提在开始安装 DeepSeek Harness 之前先确认本地环境满足基本要求。下面是我的环境参考你的版本可以略有差异重点看思路操作系统Windows 11 / macOS 13 Node.js18 LTS 或更高版本 包管理器pnpm 8 Git任意较新版本为什么要强调 Node.js 和 pnpm因为 DeepSeek Harness 的很多安装命令都依赖它们比如常见的pnpm dsh web。如果你之前只装过 npm建议先全局安装 pnpmnpm install -g pnpm安装完成后用下面的命令确认版本node -v pnpm -v git --version如果你已经安装了桌面版安装包可以直接跳过下面两步从 2.4 节开始看配置。2.2 源码方式安装源码方式适合希望自定义扩展、参与插件开发的用户。整体流程是拉取代码、安装依赖、启动服务。# 1. 拉取项目代码仓库地址以实际为准 git clone deepseek-harness 仓库地址 cd deepseek-harness # 2. 安装依赖 pnpm install # 3. 启动 Web 端 pnpm dsh web执行完第 3 步后终端会输出一个本地访问地址通常是http://localhost:3000或类似端口。打开浏览器即可进入工作台。注意事项如果pnpm install非常慢先检查是不是没有配置镜像源后面的常见问题章节会给解决方案pnpm dsh web如果长时间卡住不动大概率是依赖没有安装完整而不是程序坏了。2.3 桌面端与 Docker 部署如果不希望折腾 Node.js 环境可以直接下载桌面版安装包。Windows 用户下载.exe安装包macOS 用户下载.dmg安装包安装过程和其他桌面软件没有区别。对于服务器部署或者想保持本地环境干净的同学可以用 Docker 方式。这里给一个通用示例# 构建镜像镜像名和 Dockerfile 以项目实际为准 docker build -t deepseek-harness . # 启动容器将宿主机端口映射到容器端口 docker run -d -p 3000:3000 deepseek-harnessDocker 方式的好处是隔离性好换机器也能快速复现同一套环境。如果你要把工作区数据持久化可以额外挂载数据目录docker run -d \ -p 3000:3000 \ -v $PWD/harness-data:/app/data \ deepseek-harness2.4 安装后的基础配置进入工作台后优先完成三件事配置模型服务选择你使用的模型 API 服务填写对应的 API Key 或 Base URL。DeepSeek Harness 的优势在于可以兼容多种模型服务主模型和视觉模型可以分开配置。创建第一个工作区工作区是一个隔离的项目环境建议一个项目一个工作区避免会话互相干扰。打开技能管理页查看自带的 Skill 列表确认技能加载是否正常。完成这几步环境就基本可用了。接下来我们重点解决“技能怎么创建”的问题。3. Skill 的核心原理与文件结构3.1 Skill 的目录结构虽然不同工具对 Skill 的格式定义略有差别但主流的 Agent Skill 规范是高度相似的。一个 Skill 通常就是一个独立目录结构如下daily-report/ ├── SKILL.md ├── scripts/ │ └── format_report.py ├── templates/ │ └── report_template.md └── assets/ └── logo.png各组成部分的职责SKILL.md技能的核心说明文件Agent 会优先读取它scripts/存放可执行脚本比如格式化数据、生成文件templates/存放输出模板比如日报模板、PPT 模板assets/存放图片、字体、样式等静态资源。3.2 SKILL.md 的编写要点SKILL.md是 Agent 理解技能的关键入口。它的质量直接决定了技能好不好用。一份合格的SKILL.md应该包含以下几块内容区块作用示例元信息声明技能名称、用途、版本name: ppt-creator触发条件说明什么场景下应该使用这个技能用户提到“做PPT”时执行步骤给出明确的、可操作的步骤先确认主题再生成大纲最后出文件输出规范说明最终输出格式和验收标准输出 .pptx 文件页数 10 页以内注意事项列出容易出错的地方不要编造数据图表数据必须来自用户输入我用 Markdown 格式写一个最简示例--- name: daily-report description: 生成标准格式的日报 version: 1.0.0 --- # 日报生成技能 ## 触发条件 用户说“写日报”“生成今日日报”时使用。 ## 执行步骤 1. 询问今日完成的工作事项。 2. 按“今日进展 / 遇到的问题 / 明日计划”三部分整理。 3. 输出 Markdown 日报并保存到 reports 目录。 ## 输出规范 - 文件命名YYYY-MM-DD-report.md - 每部分使用二级标题 - 问题部分必须给出解决方案或待确认人3.3 Skill 与插件的边界在插件中心里你可能会看到“插件”和“技能”两个入口。它们的边界在哪里插件更偏向于“系统集成能力”比如接入某个外部 API、增加一个可视化面板技能更偏向于“指导 Agent 完成任务的方法论”。很多场景下插件提供能力底座技能定义使用方式两者互补。建议优先使用插件中心里已经封装好的官方插件再根据实际需求创建自己的 Skill。4. 实战从零创建一个 PPT Skill光讲概念没有用下面我们实际创建一个 PPT 生成 Skill。这个 Skill 的目标是用户给出主题后Agent 能够自动生成结构完整的 PPT 大纲并调用 Python 脚本生成一个可编辑的.pptx文件。4.1 需求拆解在写代码之前先拆解任务Agent 需要向用户确认演示主题、受众、页数Agent 根据主题生成大纲 JSON调用python-pptx脚本读取 JSON 并生成.pptx文件输出文件路径和内容摘要。这里选择python-pptx是因为它是生成 PowerPoint 文件最成熟的 Python 库之一。请确保环境里有 Python 3.9并安装依赖pip install python-pptx4.2 创建 Skill 目录在你的技能存放目录下新建一个文件夹ppt-creator/ ├── SKILL.md └── scripts/ └── generate_ppt.py技能目录放到哪里不同工具的配置不一样。一般你可以在工作台的“技能管理”里找到技能根目录然后直接把ppt-creator文件夹放进去。如果找不到可以在配置文件中指定skillsDir路径。4.3 编写 SKILL.md文件路径ppt-creator/SKILL.md--- name: ppt-creator description: 根据用户主题生成演示文稿输出可编辑的 .pptx 文件 version: 1.0.0 triggers: - 做PPT - 生成演示文稿 - 制作幻灯片 --- # PPT 生成技能 ## 使用步骤 1. 确认演示主题、目标受众、页数要求。 2. 生成内容大纲结构必须包含封面、目录、正文章节、总结页。 3. 将大纲保存为 outline.json格式如下 json { title: 演示标题, subtitle: 副标题, sections: [ { title: 章节标题, points: [要点1, 要点2, 要点3] } ] }调用脚本生成 pptx 文件python scripts/generate_ppt.py outline.json output.pptx向用户报告生成的文件路径并简要说明大纲结构。输出规范必须生成.pptx文件不要只给 Markdown 大纲。正文每页要点控制在 3 到 5 条不要出现整段文字。不要编造数据和信息来源。这里有两点要特别注意 - 我在 SKILL.md 里直接嵌入了 JSON 格式示例这样 Agent 就不需要“猜测”大纲格式降低生成误差 - 我把脚本调用命令写得很明确Agent 可以直接执行不需要二次思考。 ### 4.4 编写 PowerPoint 生成脚本 文件路径ppt-creator/scripts/generate_ppt.py python # -*- coding: utf-8 -*- import json import sys from pptx import Presentation from pptx.util import Inches def create_presentation(json_path: str, output_path: str) - None: 根据大纲 JSON 生成 PPT 文件。 with open(json_path, r, encodingutf-8) as f: data json.load(f) prs Presentation() # 使用内置版式0 标题幻灯片1 标题和内容 title_layout prs.slide_layouts[0] content_layout prs.slide_layouts[1] # 封面页 slide prs.slides.add_slide(title_layout) slide.shapes.title.text data.get(title, 无标题) if data.get(subtitle): slide.placeholders[1].text data[subtitle] # 内容页 for section in data.get(sections, []): slide prs.slides.add_slide(content_layout) slide.shapes.title.text section.get(title, 未命名章节) body slide.placeholders[1].text_frame points section.get(points, []) for i, point in enumerate(points): if i 0: body.text point else: p body.add_paragraph() p.text point prs.save(output_path) print(PPT 已生成: output_path) if __name__ __main__: if len(sys.argv) ! 3: print(用法: python generate_ppt.py 大纲.json 输出.pptx) sys.exit(1) create_presentation(sys.argv[1], sys.argv[2])这段脚本的逻辑很直接读取 JSON 大纲第一页用“标题幻灯片”版式后续每个章节用“标题和内容”版式每条要点作为一个段落写入内容占位符。4.5 测试与验证先在本机手动测试脚本确认环境没问题python scripts/generate_ppt.py outline.json test.pptx预期输出PPT 已生成: test.pptx然后在工作台里新建一个会话输入一句话请用 ppt-creator 技能生成一份“2025 年团队规划”的PPT受众是部门管理层8页左右。Agent 应该会先询问或确认信息然后生成大纲再调用脚本。最终你在工作区里能看到生成的.pptx文件。如果 Agent 没有调用技能优先检查SKILL.md里的触发词是否覆盖了用户问法或者确认技能是否已经加载到当前工作区。5. 实战创建一个 UI 设计 Skill第二个例子选 UI 设计 Skill是因为“让 AI 写界面”很容易失控输出风格不一致、颜色乱用、不考虑响应式。UI 设计 Skill 的核心价值就是给 Agent 一套“设计约束”。5.1 Skill 定位这个 Skill 的目标是用户描述一个页面需求后Agent 输出一个完整的 HTML 文件页面样式遵循预设的设计令牌Design Tokens、移动端优先、保证可访问性。目录结构如下ui-designer/ ├── SKILL.md └── templates/ └── page_template.html5.2 编写 SKILL.md文件路径ui-designer/SKILL.md--- name: ui-designer description: 根据需求生成遵循设计规范的 Web 页面代码 version: 1.0.0 triggers: - 设计页面 - 写前端 - 生成界面 --- # UI 设计技能 ## 设计约束 1. 使用设计令牌定义颜色、间距、圆角、字体禁止在组件中硬编码颜色值。 2. 移动端优先使用弹性布局和 Grid 实现响应式。 3. 输出单个完整的 HTML 文件CSS 写在 style 标签中。 4. 所有可交互元素必须支持键盘操作颜色对比度不低于 WCAG AA 标准。 5. 中文文案保持简洁按钮文字使用动词开头例如“提交表单”“导出数据”。 ## 标准设计令牌 css :root { --color-primary: #4F46E5; --color-primary-hover: #4338CA; --color-bg: #F9FAFB; --color-surface: #FFFFFF; --color-text: #111827; --color-text-secondary: #6B7280; --color-border: #E5E7EB; --color-danger: #DC2626; --spacing-xs: 4px; --spacing-sm: 8px; --spacing-md: 16px; --spacing-lg: 24px; --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --font-family: -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; }输出步骤确认页面用途、目标用户、主要操作。在回答中先列出页面区块结构。再输出完整 HTML 文件。最后用 2 到 3 句话说明设计决策。检查清单[ ] 是否使用设计令牌[ ] 是否能在 360px 宽度下正常显示[ ] 是否有 hover 和 focus 状态[ ] 是否包含语义化标签header、nav、main、footer这个 Skill 的精髓在于**把设计规范以检查清单的形式固化下来**。Agent 在输出完代码后会逐项自查这比单纯写“设计好看一点”有效得多。 ### 5.3 模板文件 文件路径ui-designer/templates/page_template.html html !DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title页面标题/title style :root { --color-primary: #4F46E5; --color-bg: #F9FAFB; --color-surface: #FFFFFF; --color-text: #111827; --spacing-md: 16px; --radius-md: 8px; } * { box-sizing: border-box; } body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; background: var(--color-bg); color: var(--color-text); } .container { max-width: 480px; margin: 0 auto; padding: var(--spacing-md); } .card { background: var(--color-surface); border-radius: var(--radius-md); padding: var(--spacing-md); margin-bottom: var(--spacing-md); } button { width: 100%; padding: 12px; border: none; border-radius: var(--radius-md); background: var(--color-primary); color: #fff; font-size: 16px; cursor: pointer; } button:hover { opacity: 0.9; } button:focus-visible { outline: 2px solid #111827; outline-offset: 2px; } media (min-width: 768px) { .container { max-width: 720px; } } /style /head body main classcontainer section classcard h1页面标题/h1 p页面描述文案。/p button typebutton主要操作/button /section /main /body /html模板文件的作用是给 Agent 一个“起点”它可以在模板基础上扩展而不是每次从零开始写样式。5.4 使用效果参考在工作台里输入用 ui-designer 技能设计一个“登录页面”包含用户名、密码、登录按钮和忘记密码链接。Agent 会先列出区块结构再输出完整 HTML并根据检查清单自查。这里的关键不是代码本身有多炫而是输出结果稳定、风格统一后续交给其他工程师维护也更容易。6. 个人 Skills 的分享与导入做完两个技能下一步就是分享。个人 Skills 的分享方式主要有三种6.1 直接复制目录最简单的方式直接把技能目录压缩成 zip发给同事。对方解压后放到自己的技能根目录即可。zip -r ppt-creator.zip ppt-creator/6.2 使用 Git 仓库管理推荐把个人 Skills 统一放在一个 Git 仓库里方便版本管理。例如my-skills/ ├── README.md ├── ppt-creator/ ├── ui-designer/ └── daily-report/在README.md中写清楚每个技能的用途和依赖# 个人技能仓库 ## ppt-creator - 用途生成 .pptx 演示文稿 - 依赖python-pptx - 安装将 ppt-creator 目录复制到技能根目录其他人克隆仓库后将对应目录复制到自己的工作台技能目录中就能直接使用。6.3 通过插件中心或市场分发如果你的工具提供了插件中心可以考虑把技能打包成符合平台规范的插件上传。这种方式适合分发范围较广的技能。不同平台的打包规范略有差异上传前先阅读对应平台的开发者文档。在分享技能时有几个原则不要内置敏感信息比如 API Key、数据库连接串脚本依赖要在SKILL.md中写清楚最好在技能内附带requirements.txt给技能写上版本号方便使用者识别版本差异。7. 常见问题与排查思路下面整理安装和使用 DeepSeek Harness、Agent Skill 时的高频问题。问题现象常见原因解决思路pnpm dsh web卡住不动依赖安装不完整或网络原因删除 node_modules 重装或配置镜像源下载依赖速度极慢默认源访问慢配置 npmmirror 镜像Windows 上安装失败权限不足或执行策略限制以管理员身份运行 PowerShell调整执行策略Agent 不调用已创建的 Skill触发词不匹配或技能未加载检查 SKILL.md 触发词确认技能目录已识别生成的 PPT 打不开python-pptx 版本问题升级 python-pptx 到最新版视觉识别功能不可用未配置多模态模型在设置中为视觉任务单独配置视觉模型找不到归档对话数据目录配置不同在工作区数据目录中查找 JSON/Markdown 归档文件部分安装流程卡在 modlens 组件网络原因或组件下载失败先跳过该组件主流程完成后单独重试下面挑几个典型问题展开说明。7.1 安装卡在pnpm dsh web这个报错非常典型很多人的第一反应是觉得程序坏了其实大部分原因是依赖没有下载完整。排查步骤如下先回到项目目录删除node_modulesrm -rf node_modules确认 pnpm 镜像源pnpm config get registry如果返回的不是国内镜像可以临时设置pnpm config set registry https://registry.npmmirror.com重新安装依赖pnpm install pnpm dsh web如果仍然卡住把终端切到英文环境再看报错信息。很多中文环境下编码问题会掩盖真实错误。7.2 安装时提示需要 modlens 组件部分版本在安装或启动时会请求安装 modlens 组件它通常用于模型输出观测或链路评估。如果长时间卡在这一步可以先取消或跳过该步骤等主程序启动后再单独处理。不同版本的提示文案不同以你的安装程序实际提示为准。7.3 Agent 不识别技能创建了技能但 Agent 就是不调用这时候优先检查三点技能目录是否在正确的根目录下SKILL.md中是否有明确的触发词会话是否加载了该技能。很多工具的技能加载不是即时的需要重新启动工作台或点击“刷新技能”按钮。如果还不生效试试在会话中直接点名技能名称例如“使用 ppt-creator 技能”。7.4 视觉识别不可用视觉识别依赖多模态模型。如果你的主模型是纯文本模型图片识别自然不可用。解决办法是在配置中单独指定一个支持视觉的模型作为视觉模型。此外图片路径必须是 Agent 可以访问的本地路径或可访问的 URL。8. 最佳实践与工程建议8.1 Skill 的命名与职责划分每个 Skill 只做一件事做深做透。命名遵循“动词-对象”的规则例如ppt-creator、daily-report、ui-designer。不要创建一个“万能技能”职责越多指令越复杂Agent 反而越容易执行偏差。8.2 指令要可验证在SKILL.md里尽量加入“检查清单”和“验收标准”。例如 PPT 技能要求“必须生成 .pptx 文件”UI 技能要求“颜色必须来自设计令牌”。这些约束让 Agent 的输出可以被自动验证出现问题时也能快速定位。8.3 版本控制与依赖管理Skills 本质上是代码资产建议纳入 Git 管理。每次修改SKILL.md或脚本后更新版本号并在变更记录中说明改动内容。如果技能依赖 Python 包或 Node 包要在技能目录中附上依赖清单ppt-creator/requirements.txtpython-pptx0.6.218.4 安全边界技能中可能包含脚本这意味着 Agent 会基于技能内容执行代码。安全方面要特别注意不在技能中硬编码任何密钥脚本不做危险操作比如删除文件、修改系统配置如果技能需要访问网络或数据库明确限制访问范围遵循最小权限原则从外部导入技能时先审查SKILL.md和脚本内容再加载到工作台。8.5 日志与可观测性使用技能时遇到问题优先查看工作台的日志输出。Agent 在执行技能时会记录调用了哪个文件、执行了什么命令、输出是什么。养成“先看日志再猜原因”的习惯排查效率会高很多。9. 总结与下一步学习路线这篇文章从概念到实战完整走了一遍 DeepSeek Harness 和 Agent Skill 的使用流程。核心收获可以归纳为四点理解了 Skill、Agent、MCP 三者的区别Skill 提供方法Agent 负责执行MCP 打通外部工具掌握了 Skill 的基本目录结构知道SKILL.md是技能的核心入口通过ppt-creator和ui-designer两个实战案例学会了把重复任务封装成技能了解到个人 Skills 可以通过目录复制、Git 仓库、插件中心三种方式分享。下一步如果想继续深入可以往这几个方向走尝试为自己的日常高频任务创建技能比如周报、会议纪要、代码审查记录学习 MCP 协议把你常用的内部系统通过 MCP 接入 Agent研究插件开发把 Skill 升级成带可视化面板的完整插件优化技能提示词用更多真实案例测试逐步收敛触发条件和输出格式。技术在快速变化但“把重复劳动固化下来”的思路不会过时。建议你先从今天这两个实战案例开始动手建一个属于你自己的技能仓库遇到问题随时翻翻本文的排查表。如果你在创建 Skill 或安装过程中有其他报错欢迎在评论区带上终端日志一起讨论。