Marvis 技能制作规范

要解决什么问题

在 Marvis 里「导入技能」失败，或导入后名称对不上、触发不准，多半不是业务逻辑写错，而是 技能包外壳 不符合约定：SKILL.md 缺失、frontmatter 字段不全、文件夹 slug 与 name 不一致，都会直接触发解析或校验错误。这份规范把 Marvis 侧能接受的目录与文档格式写清楚，方便你在写技能前先对齐契约，而不是靠试错猜规则。

技能如何工作

规范围绕一个最小可导入单元展开：以文件夹名为技能 slug（建议全小写、连字符），并放在 Marvis 用户技能目录下；根目录必须存在正确大小写的 SKILL.md。

YAML frontmatter 是硬门槛：name 与 description 为必填；name 必须与文件夹名完全一致，description 应包含触发关键词，供 Marvis 判断何时调用。若文件由 Marvis 生成，frontmatter 内可能带有 AIGC: 元数据块，不影响导入但需保留。

正文建议用 Markdown 写清：核心能力、触发条件、具体操作指令（命令、脚本路径等）以及安全约束（例如密钥脱敏）。文档末尾还用表格归纳 常见错误 → 原因 → 后果（如缺少 name/description、YAML 格式错误、skill.md 大小写错误等），便于对照修复。

适用边界与注意点

• 路径与导入流程针对 Tencent Marvis 用户技能目录与面板「导入文件夹」流程，不泛化为其它 Agent 平台的 Skill 规范。
• 规范强调 可导入性与可识别性；业务指令写得多细仍取决于你的场景，但 frontmatter 与 slug 不一致时，可能出现「导入成功却识别异常」的灰色问题。
• 表格中的失败项多为 硬性失败（缺少 SKILL.md、YAML 解析错误等），应在提交或分发前自检 frontmatter 与文件名。