skill-authoring

Exact captured content · path skills/skill-authoring/SKILL.md · sha256 b44530cb4b949f4b… · revision 8459ae5049a2addbc04c5f976110406bedfed68e

Download the exact captured file

---
name: skill-authoring
description: 用户要新建、导入或修改一份技能(把一类事的固定做法存下来,以后照着做)时用:怎么写、怎么查重、存在哪里、怎么确认能被用上。用户说「存成技能」「建个技能」「以后都这么做」「把这段导入成技能」「改一下某个技能」「做个模板」时也用。
---

# 写技能(skill-authoring)

把一类事的固定做法写成一份技能,存进会话工作区的技能目录,让它出现在「/」菜单里,以后遇到同类事能被读出来照着做。

## 入口

- 用户明确要「建一个技能」「把这套做法存下来」「把这段导入成技能」「改一下某个技能」时,走这里。只是聊做法、问能不能做,先回答,不要自己存。
- 技能写的是一类事以后怎么做,不是一次性的事实或偏好(「我不吃香菜」是记忆,不是技能)。
- 一份技能就是工作区里 `.dsh/skills/<名字>/SKILL.md` 这份 Markdown;长资料放 `references/`,能跑的脚本放 `scripts/`(附 `manifest.json`)。写它用的是普通写文件能力,没有单独的「存技能」按钮。

## 步骤

1. **先查重**:看当前工作区 `.dsh/skills/` 下已有哪些目录;能敲「/」就看菜单里有没有同类技能;有就打开那份 `SKILL.md`,在它基础上改,别为同一类事再起一份。
2. **定名字**:`name` 用小写英文、数字、连字符,说清是哪类事(如 `order-coffee`);**目录名要和 `name` 一模一样**。
3. **写正文**:整份是一个文档——头部 frontmatter(`name` + `description`),正文写清从哪开始、一步步怎么做、哪里容易走偏、办成什么算办成、什么时候停下交给用户。正文固定五节:`## 入口 / ## 步骤 / ## 容易出错的地方 / ## 怎样算办成 / ## 什么时候停下交给用户`。
4. **变化的写成参数**:人名、金额、地址、要发的文字写成 `<参数>` 或「用户指定的联系人」,不写死。
5. **拆长内容和脚本**:长表格、长清单放 `references/` 下的单独文件,正文用相对路径引用;能跑的脚本放 `scripts/`,并在 `scripts/manifest.json` 登记(`file` / `runnable` / `needs`)。
6. **存盘**:把 `SKILL.md`(及 `references/`、`scripts/`)写进 `.dsh/skills/<名字>/`。
7. **验证**:让用户敲「/」看菜单里出现 `/名字`;或用技能读工具按名字能读回正文。看不到就按下面「容易出错」查。

## 容易出错的地方

- **手机上看不到技能**:先确认文件真落在会话**当前工作区**的 `.dsh/skills/` 下(不是别的目录),且目录名与 `name` 一致。技能是按「会话工作目录」装配的,换个工作区就是另一份。
- **搜不到 / 用户说法没命中**:手机「/」菜单只显示 `name` 和 `description`,`aliases`、`display`、`terms` 这些字段到不了手机。所有能让用户对上的说法必须写进 `description`,别只写在 aliases 里。
- **随包发布不生效**:`.dsh/` 在本仓被 git 忽略,插件只把声明过的目录打进发布包。想让技能随插件发到**所有用户**,得放进插件声明的发布目录、并从那里装配,不能只丢在本地 `.dsh/skills`。
- **正文成了答辩稿**:不写中间试错、被放弃的方案、改稿痕迹;只写最终怎么做的。反引号只包工具名,App 名和按钮文字不用反引号。
- **把一次性信息当技能**:具体某次的人名、单号、口令不写进技能;不写密码、验证码、卡号和别人的私人信息。
- **一长到底**:模型自己会的不用写,只写这类事特有的做法和坑;太长就拆 `references/`。

## 怎样算办成

- 目标技能落到 `.dsh/skills/<名字>/SKILL.md`,且 `name` 与目录名一致。
- 该会话敲「/」能看到 `/名字`(说明宿主 `skills.list` 收进去了);能按名字读回正文和它的 `references` 与 `scripts`。
- 回答里说的技能名、是新建还是改的,和实际文件一致。

## 什么时候停下交给用户

- 要跨工作区共享(放全局技能根而不是当前工作区)——先问用户放哪。
- 要改名或删除——做不了就明说,请用户在技能目录里处理;换名字就按新名字另存,再请用户删旧的。
- 要写入密码、密钥、他人隐私——不写,告诉用户这类信息不进技能。
- 验证看不到技能、又查不出原因——如实说没存成 / 没装配上,不要声称已经建好。