按 agentskills.io 最佳实践迁移技能方案：skills/ 文件夹 ＋手写 SKILL.md

[xuyushun441-sys]

背景

根据最新 agentskills.io 生态，当前主流 Agent Skill 的最佳实现方式不是发布为 npm 包，而是在仓库根目录直接创建 skills/ 文件夹，并为每个技能编写高质量的手写 SKILL.md 文件。现有 Zod 协议文件应只作为校验、推导和写文档时的参考源。

目标

1. 在 objectstack-ai/spec 仓库根目录下创��� skills/ 文件夹，每个子技能一个目录，例如：
   • skills/schema-design/
2. 每个技能目录下至少包含一个高质量手写的 SKILL.md，内容包括但不限于：
   • 前置 YAML frontmatter（name, description 等元数据，符合 agentskills.io spec）
   • 领域规则、经验指令、常见误区与最佳实践，重点强调「何时��」「用了该注意什么」等 AI Agent 可直接执行的"专家经验"型指令

参考链接

• agentskills.io/specification
• 最佳实践

Acceptance Criteria

• 仓库根目录有 skills/，下含多个技能子目录，每个有 SKILL.md
• 所有 SKILL.md frontmatter 合规范、内容以专家经验为主，强调"何时用、怎么用、注意事项"
• references/ 目录可选存放 Zod Schema 字段表或类型枚举
• 禁止直接 npm 发布、禁止全自动 build 生成
• 文档及用法发生变化时及时同步
• 更新相关 CHANGELOG.md/ROADMAP.md 并通过全部校验、测试

价值

• 遵循开源 Agent 生态通行标准，便于各类智能体（Claude、Cursor、Copilot 等）自动发现和调用协议技能
• 降低维护和发布复杂度（无需构建/发布包）
• 强化技能内容质量与 AI 可用性，提高开发协作效率