本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。一、前言skill 能干什么skill 是 DSH 里给 AI 预装技能的机制一个 Markdown 文件就能教会模型一套固定的做事规范——比如按琉璃风格写页面“写规范 commit message”“整理 Obsidian 笔记”。之后只要对话匹配到它模型就会自动加载并按规范执行不用每次重复交代。它有三个特点决定了它很实用一个文件就是一个技能创建零成本随时改、随时生效热加载不用重启两种触发方式模型自动发现调用或你手动/skill名强制注入可精细控制可以设置模型不可见、只能手动调或模型可见、手动不可调。二、skill 是什么结构、存放目录、使用方式结构一个带元数据的 Markdown 文件skill 本质是YAML frontmatter Markdown 正文。frontmatter 告诉系统这个技能叫什么、干什么、什么时候用--- name: my-skill # 必填kebab-case小写连字符 description: 一句话说明这个 skill 做什么模型靠它决定何时调用 whenToUse: 可选补充使用时机 disable-model-invocation: false # true 则模型目录里隐藏 user-invocable: true # false 则 /命令 里隐藏 --- # 正文给模型的具体操作指令必填只有name和descriptionname必须 kebab-casemySkill会直接失效支持两种存放格式目录 bundleroot/skill名/SKILL.md可带 scripts/assets 资源或扁平文件root/skill名.md⚠️ 只扫描一层不支持嵌套目录。存放目录与优先级skill 没有安装动作放进扫描目录即被发现。按优先级优先级位置说明100项目根/.dsh/skills/项目级项目根 最近的.git祖先200项目根/.agents/skills/项目级通用 agent 目录300customSkillDirs配置的目录自定义400~/.dsh/skills/用户级任何会话都可见500~/.agents/skills/用户级个人常用 skill 放~/.dsh/skills/项目专用放项目目录——注意项目级 skill 只在那个项目下的会话可见解析跟随 cwd。使用方式模型自动调用会话开始注入一份 skill 目录available_skills列出 name description请求匹配时模型调skill工具加载并执行——你正常对话即可手动触发输入框输/skill名完整内容直接注入对话也是disable-model-invocation: true的 skill 唯一入口。三、创建自己的 skill过程与坑过程三步写文件按上面结构写SKILL.md正文写清操作规范最好附反例放目录拷到~/.dsh/skills/skill名/SKILL.md用户级或项目.dsh/skills/验证新会话问你有哪些可用 skill或直接/skill名试一次。坑skill 会被静默丢弃我第一次建 skill 时翻了个大车文件放好后新会话没有目录、/skill名无反应、但skill工具明明在工具列表里——没有任何报错。排查过程解压会话日志zstd 分帧逐个解压搜索确认从未注入available_skills——工具在、发现列表空直接调skill工具加载返回unknown or no longer available——确认是发现层问题用 YAML 解析器直接解析 SKILL.md报错Nested mappings are not allowed in compact mappings at line 3, column 14根因我的description里写了design: semantic、CSS variables, ...——冒号空格在 YAML 里是映射分隔符frontmatter 整个解析失败。而 skill-filesystem 对解析失败的条目只记警告、静默丢弃于是目录空、工具报 unknown毫无提示。修复给含特殊字符的字段加引号description:HTML/CSS style guide for modern, gradient-rich, glassmorphism (琉璃/毛玻璃) design: semantic markup, ...whenToUse:When the user asks to write HTML/CSS, ...保存后目录自动刷新新会话立即可用。避坑清单frontmatter 值含冒号空格、括号、逗号、长英文时务必加引号skill 被丢弃是静默的目录空 工具报 unknown遇到先怀疑 frontmattername用 kebab-case别用驼峰目录只扫一层别建嵌套description尽量简短模型靠它判断调用时机复杂说明放正文。四、总结skill 是 DSH 里成本最低、收益最直接的自定义能力一个文件就是一个可复用技能放对目录即生效支持自动/手动两种调用。唯一要注意的是 frontmatter 的 YAML 陷阱——它会导致 skill 被静默丢弃且毫无提示这也是希望 DSH 后续版本能改进的地方至少把解析警告暴露到界面上。