Skill 创建详细技术文档 2

12. 注册与发布流程

注册命令

ima_skill_create -d /sandbox/workspace/skills/{name}/
注意事项




事项


说明





目录路径

必须指向技能的根目录（含 SKILL.md 的目录）



覆盖更新

修改已有技能后重新执行同一命令即可覆盖



生效时间

审核通过后在新对话中生效，当前对话不会自动刷新



独立命令
ima_skill_create

 必须单独执行，不能与其他命令组合




注册后告知用户

技能已提交！审核通过后即可使用。如果以后想修改，可以说”修改我的 XX 技能”。


13. 最佳实践清单
description 写法


✅ 三段式：功能定义 + 触发意图列举 + 不适用场景排除


✅ 列出用户会怎么说的具体短语（”帮我调研一下XX””帮我写XX论文”）


✅ 显式排除不适用场景，防止误触发


❌ 不要只写功能，不写触发条件


❌ 不要写技术实现细节


正文组织


✅ 核心规则/铁律前置，设定全文基调


✅ 决策表 > 纯文字描述分支逻辑


✅ ✅/❌ 对比增强实操指导性


✅ “你的工作方式”段落声明接入策略


✅ 至少2个典型场景的工作流示例


❌ 不重复 LLM 已有能力（”请用优美的语言写作”）


❌ 不引用不存在的工具


篇幅控制


✅ SKILL.md ≤ 400 行


✅ 超出内容拆入 references/


✅ 在正文中说明何时读取哪个 reference


❌ 不写超长单文件


确认门设计


✅ ⛔ 符号 + 等待确认话术


✅ 声明跳过条件


✅ 长流程在关键决策节点设确认门


❌ 不设确认门导致 Agent 自作主张



14. 常见错误与避坑指南




错误


正确做法






name 用大写或空格


统一 kebab-case：my-skill-name




name 超过64字符


控制在64字符以内




description 只写功能


加上触发条件和不适用边界




SKILL.md 留 TODO 占位符


编写完成后全部替换




SKILL.md 超400行不拆分


拆入 references/




只说”必须”不说”为什么”


解释原因让 Agent 自主判断




引用不存在的工具


编写前检查自身工具列表




缺少确认门


长流程关键节点设确认门




缺少工作流示例


至少2个典型场景示例




不需要的目录保留


删除空目录




脚本缺少错误处理


脚本应有完整 try/except




忘记注册


完成后执行 ima_skill_create -d




修改后未重新注册


修改后重新执行注册命令




中文命名但不统一


建议统一英文 kebab-case，如需中文确保一致性





15. 附录：现有 Skill 结构对比




对比维度


ima-report


ima-knowledge


douyin-hot-trend


sales-conversion


forklift-expert


电子元器件应用指导





结构类型

流程型


任务型


工具/脚本型


规范型+流程型


能力集型


流程型（最严格）



Phase/Step 数

4 Step


无（按意图路由）


1 步


8 Phase


2模块（4+5步）


6 Phase



description 风格

功能+触发+排除


功能+操作+排除


极简功能描述


功能+触发+排除


多行折叠+双能力


功能+触发+排除



references/

❌


✅ 4文件


❌


✅ 7文件


✅ 5文件


❌



scripts/

❌


✅ 1文件


✅ 4文件


❌


❌


❌



确认门

✅ 1个


✅ 隐性


❌


✅ 隐性


✅ 隐性


✅ 2个



决策表

1张


4张


1张


15+张


1张


4+张



流程速览图

✅ ASCII


❌


❌


✅ 文本


❌


❌



中间文件

❌


❌


❌


❌


❌


✅ 6个



多轮修改规则

❌


❌


❌


❌


❌


✅



版本日志

❌


❌


✅


❌


❌


❌





本文档基于 ima.copilot 技能平台 v1.0 规范编写，参考了6个成熟技能的实战经验。