企业官网建设流程全解析

📝本文首发于 栏轩·阁

欢迎访问阅读原文，获取更好的阅读体验。

一、前言：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和description；name必须 kebab-case（mySkill会直接失效）；
• 支持两种存放格式：目录 bundle（<root>/<skill名>/SKILL.md，可带 scripts/assets 资源）或扁平文件（<root>/<skill名>.md）；
• ⚠️ 只扫描一层，不支持嵌套目录。

存放目录与优先级

skill 没有"安装"动作，放进扫描目录即被发现。按优先级：

个人常用 skill 放~/.dsh/skills/；项目专用放项目目录——注意项目级 skill 只在那个项目下的会话可见（解析跟随 cwd）。

使用方式

• 模型自动调用：会话开始注入一份 skill 目录（<available_skills>，列出 name + description），请求匹配时模型调skill工具加载并执行——你正常对话即可；
• 手动触发：输入框输/skill名，完整内容直接注入对话；也是disable-model-invocation: true的 skill 唯一入口。

三、创建自己的 skill：过程与坑

过程（三步）

1. 写文件：按上面结构写SKILL.md，正文写清操作规范（最好附反例）；
2. 放目录：拷到~/.dsh/skills/<skill名>/SKILL.md（用户级）或项目.dsh/skills/；
3. 验证：新会话问"你有哪些可用 skill"，或直接/skill名试一次。

坑：skill 会被"静默丢弃"

我第一次建 skill 时翻了个大车：文件放好后，新会话没有目录、/skill名无反应、但skill工具明明在工具列表里——没有任何报错。

排查过程：

1. 解压会话日志（zstd 分帧，逐个解压搜索），确认从未注入<available_skills>——工具在、发现列表空；

2. 直接调skill工具加载，返回unknown or no longer available——确认是发现层问题；

3. 用 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, ..."

保存后目录自动刷新，新会话立即可用。

避坑清单

1. frontmatter 值含冒号+空格、括号、逗号、长英文时，务必加引号；
2. skill 被丢弃是静默的（目录空 + 工具报 unknown），遇到先怀疑 frontmatter；
3. name用 kebab-case，别用驼峰；
4. 目录只扫一层，别建嵌套；
5. description尽量简短（模型靠它判断调用时机），复杂说明放正文。

四、总结

skill 是 DSH 里成本最低、收益最直接的自定义能力：一个文件就是一个可复用技能，放对目录即生效，支持自动/手动两种调用。唯一要注意的是 frontmatter 的 YAML 陷阱——它会导致 skill 被静默丢弃且毫无提示，这也是希望 DSH 后续版本能改进的地方（至少把解析警告暴露到界面上）。