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 本质上是文件，手动保存非常简单：

创建目录 ：在 ~/.dsh/skills/ 下创建一个以你的技能名命名的文件夹，例如 screenshot-doc-gen。
bash 复制代码
```
mkdir -p ~/.dsh/skills/screenshot-doc-gen
```
创建并写入文件 ：在该文件夹内创建 SKILL.md 文件，将上面写好的完整内容（包含 YAML 头和 Markdown 正文）粘贴进去并保存。
bash 复制代码
```
# 在 Git Bash 或 PowerShell 中
notepad ~/.dsh/skills/screenshot-doc-gen/SKILL.md
```
验证生效 ：保存后，无需重启 DSH 服务（支持热加载）。你可以直接新开一个会话，问 Agent"你有哪些可用的 Skill？ "来确认它是否被发现。之后，当你的请求匹配到 description 中描述的场景时，Agent 就会自动加载并执行它了。

4. 总结

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