第五章　文件格式与协议

本章覆盖第 21–24 章：SKILL.md 格式、数据与备份、文件命名约定与设置导出格式。

第二十一节技能（SKILL.md）格式

[!ref] 详解见用户手册「技能（Skill）系统」节。

21.1 文件结构

<skill-root>/
├── SKILL.md              # 必需。前置元数据 + 模板正文
├── README.md             # 可选。给人看的说明
├── examples/             # 可选。示例输入输出
└── …                     # 可选附加资源

21.2 前置元数据字段

SKILL.md 顶部使用 --- 分隔的 YAML 前置元数据，所有可识别字段：

字段	类型	必填	说明
`name`	string	✓	用作 slash 名（建议小写连字符）
`description`	string	✓	一句话说明，列在 `/help` 中
`argument-hint`	string		`<arg1> <arg2>` 提示
`allowed-tools`	array		限制本技能可用的工具白名单
`denied-tools`	array		黑名单（与白名单二选一）
`work-modes`	array		适用工作模式 `[plan, execute, …]`
`model`	string		强制使用的模型；缺省继承当前
`temperature`	number		强制温度；缺省继承当前
`version`	string		语义化版本号
`license`	string		SPDX 标识
`author`	string		作者 / 团队
`tags`	array		用于市场过滤
`signature`	string		国密签名块（由签名工具自动写入）

21.3 正文模板

正文为标准 Markdown，支持下列扩展：

语法	含义
`$1` `$2` `$N`	第 N 个位置参数
`$ARGUMENTS`	全部参数原样拼接
!`<shell>`	Shell 预处理；输出替换该位置
`{{include:path}}`	内联另一个 Markdown 文件（相对 skill-root）

21.4 三层加载优先级

层级	路径	优先级
全局	应用数据目录的全局技能区	最低
工作区	`<workspace>/.config/skills/<name>/`	中
插件	插件包内提供	高

21.5 调用方式

方式	触发点	行为
用户 slash	`/<name> <args>`	渲染后注入下一回合 system prompt
助手主动	`skill.invoke` 工具	渲染后作为工具响应回到对话流

21.6 内置技能

内置技能（如 skill-creator）启动时自动物化、内容漂移自动覆盖。
构建期签名 + 内置签名锚点（trust ExtraSignerRoots），严格签名策略下也放行。
设置 → 技能 面板以「内置」徽标区分内置 / 自建 / 第三方。
兼容 Agent Skills（agentskills.io）：跨客户端发现 / 解析容错 + 工具名翻译映射。

21.7 `market.check`（发布契约校验）

内置只读、确定性、离线工具，按 zMarket 发布契约校验本地技能 / 插件目录：

参数	类型	默认	说明
`path`	string	—	必填，待校验目录相对路径（如 `.avlcode/skills/my-skill`）
`kind`	string	自动探测	`skill` / `plugin` / `mcp` / `provider`
`version`	string	目录推断	覆盖 / 补充严格 semver
`source`	string	`./<name>`	覆盖 source 形态
`manifest`	string	从目录派生	直接给 manifest JSON

报告过 / 不过 + 原因 + 缺什么（name slug、严格 semver、source 形态、能力声明、归档安全等）。不联网、不提交。注：.skill-sign 签名 ≠ zMarket 认可；只查发布契约形态，非运行时安全审计。

第五章 文件格式与协议

第二十一节 技能（SKILL.md）格式