session-start-hook

用途

该技能用于为 Claude Code 创建和开发启动钩子（SessionStart hook）。当用户希望为 Claude Code 配置仓库、创建 SessionStart 钩子以确保测试和 linter 在 Claude Code 会话（CLI、web 或 API）中可用时使用。

创建 SessionStart 钩子，在会话启动时安装依赖，使测试和 linter 能够正常工作。
钩子通过 stdin 接收输入，包含 session_id、source（startup|resume|clear|compact）、transcript_path、permission_mode、hook_event_name、cwd 等字段。
支持异步模式：通过输出 {"async": true, "asyncTimeout": 300000} 让钩子在后台运行，减少延迟，但会引入竞态条件。
提供环境变量：$CLAUDE_PROJECT_DIR（仓库根路径）、$CLAUDE_ENV_FILE（写入环境变量的路径）、$CLAUDE_CODE_REMOTE（是否在远程环境运行）。
可使用 $CLAUDE_ENV_FILE 持久化会话变量，例如 echo 'export PYTHONPATH="."' >> "$CLAUDE_ENV_FILE"。
可使用 $CLAUDE_CODE_REMOTE 仅在远程环境运行脚本。

工作流程如下：

分析依赖：查找依赖清单文件（如 package.json/package-lock.json → npm、pyproject.toml/requirements.txt → pip/Poetry、Cargo.toml → cargo、go.mod → go、Gemfile → bundler），并阅读 README.md 等文档获取环境设置上下文。
设计钩子：创建安装依赖的脚本。关键原则：首次迭代不使用异步模式，仅在用户要求时切换；除非用户另有要求，仅为 web 编写钩子（参见 $CLAUDE_CODE_REMOTE）；容器状态在钩子完成后会被缓存，优先使用能利用该缓存的依赖安装方式（如优先 npm install 而非 npm ci）；保持幂等（可安全多次运行）；非交互式（无用户输入）。

不应放入 SessionStart 钩子的内容：不要在用户范围（~/.claude/skills/）和项目范围（.claude/skills/）之间复制技能——那是 ./dotfiles/sync.sh 的职责。

技能新鲜度检查（缺失或过时则安装）：使用本地快速 diff 检查，仅在过时时联网。默认仓库（camacho/ai-skills）可通过 AI_SKILLS_REPO 覆盖。

Dotfiles 缺失检查：通过钩子的 JSON message 字段（而非 stderr）在 Claude 会话上下文中显示提示，"continue": true 保持会话运行。

创建钩子文件：mkdir -p .claude/hooks，创建 .claude/hooks/session-start.sh，并 chmod +x。
在设置中注册：在 .claude/settings.json 中添加 hooks.SessionStart 配置，command 为 $CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh。若文件已存在则合并配置。
验证钩子：直接运行 CLAUDE_CODE_REMOTE=true ./.claude/hooks/session-start.sh，确认依赖已安装且脚本成功完成。
验证 linter：确定运行 linter 的正确命令，对示例文件运行（无需 lint 整个项目），如有问题则更新启动脚本并重新测试。
验证测试：确定运行测试的正确命令，运行一个测试（无需运行整个测试套件），如有问题则更新启动脚本并重新测试。
提交并推送：创建提交并推送到远程分支。