DSH-SKILL基础

编写 Skill 的核心就是创建一个 SKILL.md 文件,它本质上是一份写给 AI 的"操作手册",完全不需要编写代码。

1. Skill 的组成:结构比"角色"更重要

DSH 的 Skill 在文件结构上,更强调清晰的 元数据(Frontmatter) 和 操作步骤(正文)。

1. 元数据(YAML Frontmatter)

文件开头的 YAML 区域,用于告诉系统"这个技能是什么,何时使用"。

yaml 复制代码
---
name: screenshot-doc-gen  # 必填:技能名,必须是小写字母和连字符
description: 当用户要求生成桌面自动化截图文档时使用。 # 必填:决定 Agent 是否会"想起"加载它,最关键
whenToUse: 当任务涉及"截图文档生成"、"桌面自动化截图"时使用 # 可选:补充触发条件
---

关键点 :name 必须使用 kebab-case(如 my-skill),description 是 Agent 决定是否调用该技能的核心依据,务必写清楚具体的触发场景。

2. 正文(Markdown Body)

这是给 Agent 的具体操作指南,建议按照你的思路来组织,让指令更清晰:

  • 输入 (Input):明确告诉 Agent 需要什么信息。例如,"用户的原始请求文本"。
  • 执行 (Execution) :这是核心部分,像写 SOP 一样列出编号步骤 。每一步都明确指定要使用的工具 (比如 mcp__screenshot-tool__capture),并规定好失败重试的逻辑。
  • 输出 (Output) :严格定义最终返回的格式。例如,要求返回纯 JSON,并规定好字段结构,不要包含任何额外解释。这能极大方便你后续在 Spring Boot 中解析。

一个包含你业务逻辑的正文示例:

markdown 复制代码
## 输入
用户提供的任务描述(prompt)。

## 执行
1. **执行截图与落盘**:调用 `mcp__screenshot-tool__capture` 工具,将用户的任务描述作为参数传入。
2. **校验与重试**:检查生成的 result.json 中 `files` 数组是否非空。
   - 若为空或文件不存在,重新执行步骤1,最多重试2次。
   - 每次重试前,在回复中记录上次失败原因。
   - 重试2次后仍失败,直接返回 `{"files": [], "status": "failed"}`。
3. **校验并交付路径**:对 `files` 中的每个路径,确认文件存在且可读。将不可读的文件从数组中移除。

## 输出
最终回复必须是**纯 JSON 格式**,不要包裹 Markdown 代码块,不要加任何解释文字。格式如下:
{"files": ["绝对路径1", "绝对路径2"], "status": "success" | "partial" | "failed"}

2. Skill 存放位置:决定生效范围

Skill 的存放位置决定了它的生效范围,系统会按优先级扫描以下目录:

优先级 位置 说明
100 <项目根>/.dsh/skills/ 项目级,只对当前项目生效,适合团队共享
200 <项目根>/.agents/skills/ 项目级(通用 Agent 目录)
300 customSkillDirs 配置的目录 自定义目录
400 ~/.dsh/skills/ 用户级 ,对你所有项目生效(推荐个人开发使用)
500 ~/.agents/skills/ 用户级(通用 Agent 目录)

对于你的个人开发场景,建议将 Skill 放在 ~/.dsh/skills/ 下,这样在任何项目中都能调用。存放时,支持目录式 (<name>/SKILL.md)或扁平文件 (<name>.md)两种格式。

3. 如何手动保存 Skill

由于 Skill 本质上是文件,手动保存非常简单:

  1. 创建目录 :在 ~/.dsh/skills/ 下创建一个以你的技能名命名的文件夹,例如 screenshot-doc-gen。

    bash 复制代码
    mkdir -p ~/.dsh/skills/screenshot-doc-gen
  2. 创建并写入文件 :在该文件夹内创建 SKILL.md 文件,将上面写好的完整内容(包含 YAML 头和 Markdown 正文)粘贴进去并保存。

    bash 复制代码
    # 在 Git Bash 或 PowerShell 中
    notepad ~/.dsh/skills/screenshot-doc-gen/SKILL.md
  3. 验证生效 :保存后,无需重启 DSH 服务(支持热加载)。你可以直接新开一个会话,问 Agent"你有哪些可用的 Skill? "来确认它是否被发现。之后,当你的请求匹配到 description 中描述的场景时,Agent 就会自动加载并执行它了。

4. 总结

你现在的任务很清晰:创建一个 ~/.dsh/skills/screenshot-doc-gen/SKILL.md 文件,把上面的结构框架和你的业务逻辑填进去 。写好之后,新开一个 DSH 会话让它列出技能,看看你的 screenshot-doc-gen 是否在列表里,这是最快的验证方式。

相关推荐
feixing_fx32 分钟前
第一个 JS 程序:在浏览器控制台和 Node 中分别运行
开发语言·前端·javascript·前端框架·ecmascript
feixing_fx2 小时前
变量与声明:let、const、var 的选择边界
开发语言·前端·javascript·前端框架
程序员大阳2 小时前
副队长Vue3教程(8)--列表渲染 v-for
javascript·vue3·v-for·列表渲染
feixing_fx6 小时前
JavaScript 是什么:从浏览器脚本到通用编程语言
开发语言·前端·javascript·前端框架·ecmascript
小y的笔记6 小时前
JavaScript URL 状态同步
前端·javascript
泯泷10 小时前
Vercel AI SDK 6 完整教程系列 - 第一部分:基础入门篇
前端·javascript
程序员大阳11 小时前
副队长Vue3教程(5)--事件绑定 v-on
前端·javascript·vue.js·vue3·事件绑定·v-on
泯泷12 小时前
Vercel AI SDK 6 完整教程系列 - 第二部分:结构化数据与工具调用
前端·javascript
云起SAAS14 小时前
手机靓号选号商城H5源码 完整前后台可直接运行
前端·javascript·后端
code2cat14 小时前
JavaScript编程篇之异步请求:切换到待办,为什么又显示了全部任务
前端·javascript