fix: disable skills-loader by default

Author: majiayu000

README.md

@@ -53,7 +53,7 @@ Rules use **negative constraints** ("X does not exist") to implicitly guide AI 
 
 ### 2. Hooks — Real-Time Interception
 
-No manual steps needed. Hooks trigger automatically during AI operations:
+Most hooks trigger automatically during AI operations; `skills-loader` remains an optional manual hook:
 
 | Scenario | Hook | Result |
 |----------|------|--------|
@@ -252,7 +252,7 @@ codex:
 | Profile | Hooks Installed | Use Case |
 |---------|----------------|----------|
 | `minimal` | pre-write, pre-edit, pre-bash | Lightweight — only critical interception |
-| `core` (default) | minimal + post-edit, post-write, skills-loader, analysis-paralysis | Standard development |
+| `core` (default) | minimal + post-edit, post-write, post-guard-check, analysis-paralysis | Standard development |
 | `full` | core + stop-guard, learn-evaluator, post-build-check | Full defense + learning |
 | `strict` | full + all hooks active at runtime | Maximum enforcement |
 

README_CN.md

@@ -58,7 +58,7 @@ VibeGuard 通过两条路径注入规则：
 
 ### 2. Hooks 实时拦截（写代码时自动触发）
 
-不需要手动运行，AI 操作时自动拦截：
+大多数 Hook 不需要手动运行，AI 操作时自动拦截；`skills-loader` 为保留的可选脚本：
 
 | 场景 | 触发 | 结果 |
 |------|------|------|
@@ -69,7 +69,7 @@ VibeGuard 通过两条路径注入规则：
 | AI 编辑后新增了 `console.log` / `print()` 调试语句 | `post-edit-guard` | **警告** — 提示使用 logger |
 | AI 新建文件后存在重复定义或同名文件 | `post-write-guard` | **警告** — 检测重复定义 |
 | AI 编辑后构建检查失败（`full` profile） | `post-build-check` | **警告** — 自动运行对应语言构建检查 |
-| 会话首次工具调用时 | `skills-loader` | **加载** — 自动匹配并加载相关 Skill |
+| 需要时手动启用 | `skills-loader` | **可选** — 首次 Read 时输出 Skill/学习提示，默认不启用 |
 | `git commit` 时 | `pre-commit-guard` | **拦截** — 质量检查 + 构建检查，10s 超时硬限 |
 | AI 想结束但有未验证的源码变更（`full` profile） | `stop-guard` | **门禁** — 提醒完成验证后再结束 |
 | 会话结束时 | `learn-evaluator` | **评估** — 采集指标 + 检测纠正信号，有信号时建议 /learn |
@@ -411,7 +411,7 @@ vibeguard/
 │   ├── post-write-guard.sh               #   新文件重复检测
 │   ├── post-build-check.sh               #   构建检查（full profile）
 │   ├── post-guard-check.sh               #   MCP guard_check 后处理
-│   ├── skills-loader.sh                  #   会话首次自动加载 Skill
+│   ├── skills-loader.sh                  #   可选的首次 Read Skill/学习提示脚本（默认不启用）
 │   ├── stop-guard.sh                     #   完成前验证门禁
 │   └── learn-evaluator.sh                #   会话结束学习评估
 ├── guards/                               # 静态检查脚本（支持 // vibeguard:ignore 行内排除）

docs/how/learning-skill-generation.md

@@ -62,7 +62,7 @@ VibeGuard 的学习系统对标 OpenAI Harness 的反馈循环，实现"操作 
 | pre-bash-guard | 命令前 | 危险命令拦截 |
 | post-edit-guard | 编辑后 | unwrap/console.log/硬编码/Go error 丢弃/超大 diff |
 | post-write-guard | 新建后 | 重复定义检测 |
-| skills-loader | 首次 Read | Skill 匹配加载（不写日志） |
+| skills-loader | 手动可选的首次 Read | Skill/学习提示加载（默认不注册，不写日志） |
 | learn-evaluator | Stop | 会话指标聚合 |
 
 ### Session ID 机制
@@ -264,7 +264,8 @@ date: YYYY-MM-DD
 
 ## Skill 自动复用
 
-新会话第一次 `Read` 操作时，`skills-loader.sh`（PreToolUse Hook）自动触发两件事：
+`skills-loader.sh` 现在保留为可选脚本，默认不会由 setup 自动注册。
+如需手动挂到 `PreToolUse(Read)`，它会在新会话第一次 `Read` 操作时触发两件事：
 
 ```
 新会话 → 首次 Read
@@ -275,8 +276,8 @@ date: YYYY-MM-DD
   │
   ├─ [Skill 匹配] 扫描 ~/.claude/skills/ 和 .claude/skills/
   │   ├─ 读取每个 SKILL.md 的 frontmatter（name + description）
-  │   ├─ 打分：语言匹配 +2，项目名匹配 +3，触发关键词匹配 +1
-  │   └─ 输出 top 5 匹配 Skill 到会话上下文
+  │   ├─ 打分：语言匹配 +2，项目名匹配 +3
+  │   └─ 输出 top 5 匹配 Skill 提示
   │
   └─ 创建 flag 文件，本会话不再重复加载
 ```
@@ -383,7 +384,7 @@ Hook 升级（强制警告，打断 Agent 循环）
 |------|------|
 | `hooks/log.sh` | 日志基础设施，提供 vg_log 函数 |
 | `hooks/learn-evaluator.sh` | Stop 事件时会话指标采集 |
-| `hooks/skills-loader.sh` | 首次 Read 时加载匹配 Skill |
+| `hooks/skills-loader.sh` | 可选的首次 Read Skill/学习提示脚本（默认不启用） |
 | `hooks/post-build-check.sh` | 构建检查 + 连续失败升级（U-25 机械化） |
 | `scripts/gc-scheduled.sh` | GC 定期学习（跨会话模式识别） |
 | `.claude/commands/vibeguard/learn.md` | /vibeguard:learn 命令（双模式路由） |
@@ -397,6 +398,6 @@ Hook 升级（强制警告，打断 Agent 循环）
 | GC 后台定期学习 | gc-scheduled.sh 学习阶段（跨项目信号汇总） |
 | Skill 手动提取 | /vibeguard:learn 模式 B |
 | 失败驱动改进 | /vibeguard:learn 模式 A（5-Why + 守卫生成） |
-| 上下文自动加载 | skills-loader.sh（PreToolUse Read 触发） |
+| 可选提示加载 | skills-loader.sh（可手动挂到 PreToolUse Read） |
 | 知识去重 | 去重决策表（5 种处理路径） |
 | 质量门控 | 4 条标准（可复用、非平凡、具体、已验证） |

hooks/CLAUDE.md

@@ -15,7 +15,7 @@ Claude Code hooks 脚本，在 AI 操作前后自动触发。
 | `post-write-guard.sh` | PostToolUse(Write) | 新文件创建后检测重复定义和同名文件 |
 | `post-build-check.sh` | PostToolUse(Edit/Write) | 编辑后自动运行语言对应的构建检查 |
 | `post-guard-check.sh` | PostToolUse(guard_check) | MCP guard_check 调用后的处理 |
-| `skills-loader.sh` | PreToolUse(Read) | 会话首次工具调用时自动加载匹配的 Skill（每会话一次） |
+| `skills-loader.sh` | 手动可选 | 可选的首次 Read 提示脚本；默认不注册到 hooks |
 | `stop-guard.sh` | Stop | 完成前验证门禁，检查未提交的源码变更 |
 | `learn-evaluator.sh` | Stop | 会话结束时采集指标 + 检测纠正信号（高 warn 率、文件 churn、escalate），有信号时建议 /learn |
 | `pre-commit-guard.sh` | git pre-commit | 提交前自动守卫：质量检查 + 构建检查，10s 超时硬限 |

hooks/skills-loader.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# VibeGuard Skills Loader — 会话首次工具调用时加载匹配 Skill
+# VibeGuard Skills Loader — 可选的 Skill/学习提示加载器
 #
-# 挂在 PreToolUse(Read) 上，每会话只触发一次。
+# 默认不注册；如需启用，可手动挂在 PreToolUse(Read) 上，每会话只触发一次。
 # 扫描 ~/.claude/skills/ 和 .claude/skills/ 中的 SKILL.md，
 # 按项目语言和当前目录匹配，输出相关 Skill 摘要。
 #

scripts/lib/settings_json.py

@@ -45,7 +45,6 @@ def has_pre_hooks(data: dict[str, Any]) -> bool:
         any(_entry_contains(entry, "pre-write-guard") for entry in pre)
         and any(_entry_contains(entry, "pre-bash-guard") for entry in pre)
         and any(_entry_contains(entry, "pre-edit-guard") for entry in pre)
-        and any(_entry_contains(entry, "skills-loader") for entry in pre)
     )
 
 
@@ -171,7 +170,7 @@ def cmd_upsert_vibeguard(args: argparse.Namespace) -> int:
     upsert_hook(hooks, args.repo_dir, "PreToolUse", "Write", "pre-write-guard.sh", state)
     upsert_hook(hooks, args.repo_dir, "PreToolUse", "Bash", "pre-bash-guard.sh", state)
     upsert_hook(hooks, args.repo_dir, "PreToolUse", "Edit", "pre-edit-guard.sh", state)
-    upsert_hook(hooks, args.repo_dir, "PreToolUse", "Read", "skills-loader.sh", state)
+    upsert_hook(hooks, args.repo_dir, "PostToolUse", "mcp__vibeguard__guard_check", "post-guard-check.sh", state)
     upsert_hook(hooks, args.repo_dir, "PostToolUse", "Edit", "post-edit-guard.sh", state)
     upsert_hook(hooks, args.repo_dir, "PostToolUse", "Write", "post-write-guard.sh", state)
     # analysis-paralysis-guard for core and above

tests/test_setup.sh

@@ -104,6 +104,8 @@ assert_cmd "安装后 Codex MCP 已配置" python3 "${CODEX_MCP_HELPER}" check -
 assert_cmd "settings helper 检测 mcp 已配置" python3 "${SETTINGS_HELPER}" check --settings-file "${HOME}/.claude/settings.json" --target mcp
 assert_cmd "settings helper 检测 pre hooks 已配置" python3 "${SETTINGS_HELPER}" check --settings-file "${HOME}/.claude/settings.json" --target pre-hooks
 assert_cmd "settings helper 检测 post hooks 已配置" python3 "${SETTINGS_HELPER}" check --settings-file "${HOME}/.claude/settings.json" --target post-hooks
+assert_cmd "默认安装启用 post-guard-check" grep -q "post-guard-check.sh" "${HOME}/.claude/settings.json"
+assert_cmd "默认安装不启用 skills-loader" bash -c "! grep -q 'skills-loader.sh' '${HOME}/.claude/settings.json'"
 assert_cmd "默认 core profile 不启用 full hooks" bash -c "python3 '${SETTINGS_HELPER}' check --settings-file '${HOME}/.claude/settings.json' --target full-hooks >/dev/null 2>&1; test \$? -ne 0"
 
 header "setup --clean"