SKILL.md 与 frontmatter

适用版本：StablEdge 0.4.4 及以上

每个 Skill 目录的根上都要有一个 SKILL.md。它由两部分组成：开头用 --- 包住的 YAML frontmatter，以及后面的 Markdown 正文。

---
name: release-notes
description: "整理版本更新说明时使用：按新增、优化、修复三段归类提交记录。触发词：更新说明、发版说明、changelog。"
---

# 版本更新说明

1. 先读取本次版本的提交列表……
2. ……

文件格式要求

  • 文件名必须是 SKILL.md（大小写一致），使用 UTF-8 编码。
  • 文件第一个字符就必须是 ---。带 BOM 的文件会被判定为“缺少 frontmatter”。
  • frontmatter 必须是合法的 YAML 键值映射，并包含 name。
  • 不符合要求的 Skill 不会被加载。StablEdge 会为安装目录下的 Skill 记录诊断原因，例如 SKILL_MD_NO_FRONTMATTER、SKILL_MD_YAML_INVALID、SKILL_MD_NAME_MISSING、SKILL_MD_METADATA_INVALID、SKILL_MD_DUPLICATE_NAME，方便定位改坏了哪里。
为了兼容其他 Agent 产品的写法，description 写在一行里、没加引号又包含“冒号 + 空格”时，StablEdge 会尽量按字符串收下。其余 YAML 错误不做修复。稳妥起见，description 请始终加双引号。

字段一览

字段是否必填类型说明
name必填字符串Skill 的唯一名字，见下文命名规则。
description强烈建议字符串做什么、什么时候用。检索和自动匹配只看名字和它，见下文description 的写法。缺省为空字符串。
version可选字符串版本号。写成不带引号的 2.1 也会按字符串 "2.1" 处理。
license可选字符串许可证说明。
allowed-tools可选字符串列表推荐 Agent 使用的工具名。加载时会提示 Agent 优先用这些工具，使用其他工具需要用户确认。也接受 allowed_tools 写法。
paths可选字符串或字符串列表文件路径模式（gitignore 语法）。设置后成为“条件 Skill”，见下文paths。
compatibility可选字符串兼容性说明。
metadata可选字符串到字符串的映射附加信息。安装预览会展示其中的 category，以及用英文逗号分隔的 tags。值必须是字符串。
context可选inline 或 fork默认 inline，正文直接进入当前对话。其他值都按 inline 处理。fork 见下文。
progressive可选映射开启 Progressive 结构，见 Progressive 结构。
resources可选列表声明附带文件及其角色，见 资源与脚本。

上表之外的字段会原样保留，但 StablEdge 不使用，下文提到的网络域名声明除外。

命名规则

StablEdge 对 name 的校验规则如下：

  • 去掉首尾空白后，只能包含字母（含中文等 Unicode 文字）、数字、-、_、. 和空格；
  • 单个空格会被转成 -，连续的空白字符则判为不合法；转换后不超过 80 个字符；
  • 不能为空，也不能是 . 或 ..；
  • 安装时以转换后的结果作为目录名，例如 My Skill 会装到 My-Skill/。

规则允许的范围比较宽，但为了在各处都清晰、稳定，建议：

  • 只用小写字母、数字和连字符（hyphen-case），例如 release-notes；
  • 用简短的、以动作开头的短语，必要时加工具前缀，例如 gh-address-comments；
  • 目录名与 name 保持一致；
  • 不与已安装的 Skill 或内置 Skill 重名。重名的那一份会被忽略。

description 的写法

description 是 Skill 被选中的主要依据。Agent 在加载正文之前只能看到它，所以“什么时候用”必须写在这里，而不是写在正文里。

StablEdge 的检索是轻量的关键词匹配，没有用向量或模型：

  • 检索：把查询按空白和标点（包括中文的逗号、句号、顿号等）切成词，每个词命中名字加 8 分、命中 description 加 3 分、命中 paths 加 2 分；
  • 自动匹配：把 description 按同样的规则切成片段，任一片段（至少 2 个字符）出现在用户消息里，就认为匹配。

所以好的 description 应该：

  1. 先用一句话说明做什么、适用于什么场景；
  2. 列出用户真实会说的触发词，用顿号或逗号隔开，每个触发词尽量短；
  3. 写明不适用的场景，避免和相邻的 Skill 抢任务；
  4. 开头 80 个字就要讲清用途，因为浏览列表时只显示前 80 个字；
  5. 加双引号；不要在里面写尖括号。

内置 pdf Skill 的写法可以参考（摘自 builtin/pdf/SKILL.md）：

description: "当用户需要创建、读取、分析或操作 PDF 文档时使用。触发词：PDF、pdf 文件、读取 PDF、提取 PDF、合并 PDF、PDF 转文本等。不用于 Word 文档、电子表格或演示文稿任务。"

paths：按文件路径激活

设置了 paths 的 Skill 是条件 Skill：当对话涉及的文件路径（相对于工作区）匹配这些模式时，它会被自动激活。模式使用 gitignore 语法，例如 *.pdf 能匹配任意目录下的 PDF。

paths:
  - "*.pdf"

paths 只控制自动激活。条件 Skill 同样出现在 Skill 目录里，Agent 随时可以检索和加载它。

context：inline 与 fork

默认的 inline 会把正文交给当前对话里的 Agent。context: fork 要求 Skill 在隔离的异步环境里执行，结果再返回给当前对话；运行环境不支持隔离执行时，加载会直接失败，不会退回 inline。没有明确需要隔离执行的 Skill，请不要设置这个字段。

正文中的变量

加载 Skill 时，正文里的以下变量会被替换：

写法替换为
${SKILL_DIR}该 Skill 的目录
${SKILLS_USER_DIR}当前账号的 Skill 安装目录
${SESSION_ID}当前会话 ID
${WORKSPACE}当前工作区
${USER_NAME}当前用户名
$1、$2…加载时传入的第 1、2… 个参数

未知变量会原样保留。注意 Agent 不能用通用的文件工具直接访问 Skill 目录，引用附带文件时请写相对路径，让 Agent 通过 skill 工具读取，详见 资源与脚本。

声明脚本需要的网络域名

如果 Skill 的脚本需要联网，可以在 frontmatter 里声明域名，作为脚本运行时的默认网络白名单。StablEdge 兼容以下几种常见写法（任选其一）：

network:
  hosts:
    - api.example.com
# 或
permissions:
  network:
    hosts:
      - api.example.com
# 或
allowed-hosts:
  - api.example.com

这些声明只是候选值，用户确认运行脚本时能看到，Agent 也可以在调用时显式指定或传空列表来离线运行。详见 运行脚本。

本页目录