Skip to content

Commit 80d29f1

Browse files
invalidclaude
andcommitted
docs: add skills-to-commands migration plan
Record plan to migrate 5 skills to commands (codemap: namespace) plus SessionStart hook for auto-triggering context detection. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 51eaadb commit 80d29f1

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

docs/plan/2026-02-20-rust-cli-rewrite.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,67 @@ ignore = "0.4" # .gitignore 支持
143143
- 将预编译二进制放入 ccplugin/bin/
144144
- 最终验证插件安装流程
145145

146+
## 待办:Skills → Commands + Hook 迁移
147+
148+
### 问题
149+
150+
当前 5 个功能(scan、load、update、query、impact)全部实现为 skills。存在以下问题:
151+
- 名称冲突风险:`scan``load``update``query` 过于通用,可能与其他插件冲突
152+
- 误触发:skill 根据 description 关键词自动激活,"扫描"、"查找"、"更新" 在日常对话中极其常见,可能在无关上下文中触发
153+
- 不可控:用户讨论非 CodeMap 相关的 scan/query 时也可能被激活
154+
155+
### 方案:Commands + Hook 混合模式
156+
157+
**Commands(明确操作):**
158+
159+
将 5 个 skill 转为 commands,获得 `codemap:` 命名空间隔离:
160+
161+
| 当前 (skill) | 迁移后 (command) | 说明 |
162+
|-------------|-----------------|------|
163+
| `/scan` | `/codemap:scan` | 全量扫描 |
164+
| `/load` | `/codemap:load` | 加载图谱 |
165+
| `/update` | `/codemap:update` | 增量更新 |
166+
| `/query` | `/codemap:query` | 符号查询 |
167+
| `/impact` | `/codemap:impact` | 影响分析 |
168+
169+
文件变更:`ccplugin/skills/*/SKILL.md``ccplugin/commands/*.md`,调整 frontmatter 格式。
170+
171+
**Hook(自动触发):**
172+
173+
添加 `SessionStart` hook 实现自动上下文恢复:
174+
175+
```json
176+
{
177+
"hooks": {
178+
"SessionStart": [{
179+
"hooks": [{
180+
"type": "command",
181+
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.sh\"",
182+
"timeout": 10,
183+
"statusMessage": "CodeMap: 检测项目图谱..."
184+
}]
185+
}]
186+
}
187+
}
188+
```
189+
190+
`session-start.sh` 逻辑:
191+
1. 检测当前工作目录是否存在 `.codemap/graph.json`
192+
2. 如果存在 → 输出提示信息,建议用户使用 `/codemap:load` 加载图谱
193+
3. 如果不存在 → 静默退出,不干扰用户
194+
195+
这样既实现了自动触发(提示用户图谱可用),又避免了 skill 误触发的问题。
196+
197+
### 迁移状态
198+
199+
- [ ] 将 5 个 skills 转为 commands
200+
- [ ] 创建 SessionStart hook 脚本
201+
- [ ] 创建 hooks/hooks.json
202+
- [ ] 更新 README 中的 skill 相关文档
203+
- [ ] 测试安装验证
204+
205+
---
206+
146207
## 兼容性约束
147208

148209
- `.codemap/` 输出目录格式必须与 Node.js 版本完全一致

0 commit comments

Comments
 (0)