注册问题

.opencode/skills/opencode-init/SKILL.md

@@ -233,17 +233,24 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 
 ```
 1. 重新递归扫描 .opencode/，再次分组
-2. 期望状态：
+2. 【强制】验证所有 Skills 的 frontmatter：
+   - 遍历 `.opencode/skills/*/SKILL.md`
+   - 每个文件必须检查：第一行是否为 `---`、是否包含 `name:` 字段、frontmatter 是否正确闭合
+   - 缺失 frontmatter 的 Skill 会无法被 opencode 注册（即使文件存在也不会出现在 available_skills 中）
+   - 发现缺失 → 立即报告并修复（参考其他 Skill 的 frontmatter 格式）
+3. 期望状态：
    - A 组：全部保留，文件内容未被动过
    - B 组：数据文件仅含模板内容
    - C 组：为空（或仅剩用户明确要求保留的文件）
+   - 所有 Skill 的 frontmatter 完整
    - 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
    - project根 opencode.json：instructions 已正确配置
-3. 给用户一份结构化报告，至少包含：
+4. 给用户一份结构化报告，至少包含：
    - 删除的文件
    - 重置的文件
    - 新注册/移除的 registry 条目
    - .gitignore 的处理结果（新建/追加/覆盖/放弃）
+   - Skill frontmatter 验证结果
    - 未处理的文件（如果有，逐条说明原因）
 ```
 
@@ -841,7 +848,7 @@ public/build/
 
 | # | 检核项 | 操作 |
 |---|--------|------|
-| 1.1 | Skill 目录存在 `SKILL.md` 且含正确 frontmatter | 验证 `name`、`description` 字段 |
+| 1.1 | Skill 目录存在 `SKILL.md` 且含正确 YAML frontmatter | **强制**：第一行必须是 `---`，必须含 `name:` 字段，必须正确闭合。缺失 frontmatter 会导致 opencode 无法注册该 Skill（`"Skill not found"`），即使文件存在、registry 有注册、AGENTS.md 有引用。 |
 | 1.2 | `canonical-manifest.json` → `canonical_skills` | **首选更新目标**：在 JSON 数组中追加新 Skill 目录路径 |
 | 1.3 | `opencode-init` 规范清单 → Skills 白名单 | 在 `### Skills（规范 Skill 目录白名单）` 下新增条目（与 1.2 保持同步） |
 | 1.4 | `opencode-init` 清理清单 → 阶段 3 | 检查：新 Skill 如有数据文件，需在 B 组重置列表新增条目 |
@@ -918,6 +925,7 @@ public/build/
 | `canonical-manifest.json` VS `canonical_skills` | glob `.opencode/skills/*/` → 不在 manifest 中且非项目级 → 警告 |
 | `canonical-manifest.json` VS `template_data_files` | glob `.opencode/data/**/*` → 不在 manifest 中 → 警告 |
 | `canonical-manifest.json` VS disk | manifest 中的路径 → glob/read 验证文件存在 |
+| Skill frontmatter 完整性 | 遍历所有 `SKILL.md` → 验证第一行 `---`、含 `name:` 字段、正确闭合 |
 | `AGENTS.md` 引用的 Skill | grep Skill 名 → 必须在 `canonical-manifest.json` → `canonical_skills` 中 |
 | `AGENTS.md` 引用的数据文件 | grep 文件路径 → 必须在 `canonical-manifest.json` → `template_data_files` 中 |
 | `AGENTS.md` 引用的 docs/ 文档 | glob 检查文件存在 |

.opencode/skills/spec-docs/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: spec-docs
+description: >-
+  规范文档全生命周期管理系统。在 Agent 执行架构/规范类任务前自动提醒是否需要创建文档，
+  周期性审查文档与 changelog/代码的一致性（遗漏、陈旧、互斥检测），写入/更新规范文档。
+  触发关键词："架构"、"重构"、"设计方案"、"交互规范"、"编码规范"、"审查文档"、"review docs"等。
+---
+
 # Skill: spec-docs
 
 # Spec Docs