first commit

2026-03-21 18:57:10 +08:00
commit c49aa1a5e9
570 changed files with 107167 additions and 0 deletions
--- a/skills/self-improving-agent-3.0.5/references/hooks-setup.md
+++ b/skills/self-improving-agent-3.0.5/references/hooks-setup.md
@@ -0,0 +1,223 @@
+# Hook Setup Guide
+
+为 AI coding agents 配置自动 self-improvement triggers。
+
+## Overview
+
+hooks 会在关键时机注入提醒，以便主动记录 learnings：
+- **UserPromptSubmit**：每次 prompt 后提醒是否需要记录 learnings
+- **PostToolUse (Bash)**：当 command 失败时进行 error detection
+
+## Claude Code Setup
+
+### Option 1: Project-Level Configuration
+
+在项目根目录创建 `.claude/settings.json`：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/self-improvement/scripts/activator.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/self-improvement/scripts/error-detector.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Option 2: User-Level Configuration
+
+将以下内容加入 `~/.claude/settings.json`，实现全局启用：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/skills/self-improvement/scripts/activator.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Minimal Setup（仅 Activator）
+
+如果希望降低开销，只使用 UserPromptSubmit hook：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/self-improvement/scripts/activator.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Codex CLI Setup
+
+Codex 使用与 Claude Code 相同的 hook system。在 `.codex/settings.json` 中写入：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/self-improvement/scripts/activator.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## GitHub Copilot Setup
+
+Copilot 不直接支持 hooks。可以改为在 `.github/copilot-instructions.md` 中加入提示：
+
+```markdown
+## Self-Improvement
+
+在完成包含以下情况的任务后：
+- Debugging non-obvious issues
+- 发现 workarounds
+- 学到项目特定 patterns
+- 解决 unexpected errors
+
+考虑使用 self-improvement skill 的格式，将这条 learning 记录到 `.learnings/`。
+
+对于对其他 sessions 也有价值的高价值 learnings，考虑做 skill extraction。
+```
+
+## Verification
+
+### Test Activator Hook
+
+1. 启用 hook 配置
+2. 启动新的 Claude Code session
+3. 发送任意 prompt
+4. 确认上下文中出现 `<self-improvement-reminder>`
+
+### Test Error Detector Hook
+
+1. 为 Bash 启用 PostToolUse hook
+2. 运行一个会失败的 command：`ls /nonexistent/path`
+3. 确认出现 `<error-detected>` reminder
+
+### Dry Run Extract Script
+
+```bash
+./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
+```
+
+预期输出会展示将要创建的 skill scaffold。
+
+## Troubleshooting
+
+### Hook Not Triggering
+
+1. **Check script permissions**：`chmod +x scripts/*.sh`
+2. **Verify path**：使用绝对路径，或使用相对项目根目录的路径
+3. **Check settings location**：确认是 project 级还是 user 级配置
+4. **Restart session**：hooks 会在 session 启动时加载
+
+### Permission Denied
+
+```bash
+chmod +x ./skills/self-improvement/scripts/activator.sh
+chmod +x ./skills/self-improvement/scripts/error-detector.sh
+chmod +x ./skills/self-improvement/scripts/extract-skill.sh
+```
+
+### Script Not Found
+
+如果使用相对路径，请确认当前目录正确；否则使用绝对路径：
+
+```json
+{
+  "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
+}
+```
+
+### Too Much Overhead
+
+如果 activator 让你觉得太打断：
+
+1. **Use minimal setup**：仅启用 UserPromptSubmit，不启用 PostToolUse
+2. **Add matcher filter**：只在特定 prompts 下触发：
+
+```json
+{
+  "matcher": "fix|debug|error|issue",
+  "hooks": [...]
+}
+```
+
+## Hook Output Budget
+
+activator 被设计为轻量输出：
+- **Target**：约 50-100 tokens 每次触发
+- **Content**：结构化 reminder，而不是冗长说明
+- **Format**：XML tags，便于解析
+
+如果还需要进一步降低开销，可以直接修改 `activator.sh`，让输出更短。
+
+## Security Considerations
+
+- hook scripts 以与 Claude Code 相同的权限运行
+- scripts 只输出文本；不会修改文件，也不会执行额外 commands
+- error detector 会读取 `CLAUDE_TOOL_OUTPUT` environment variable
+- 所有 scripts 都是 opt-in 的（必须手动配置才会启用）
+
+## Disabling Hooks
+
+如果想临时停用，又不想删除配置：
+
+1. **Comment out in settings**：
+```json
+{
+  "hooks": {
+    // "UserPromptSubmit": [...]
+  }
+}
+```
+
+2. **或直接删除 settings file**：没有配置时 hooks 就不会运行