用途
claude-code-ops 是一个针对 Claude Code 自身运行机制的工具型技能，覆盖四类表面：钩子系统（hooks）、技能格式（skill frontmatter）、无头/编程式使用（headless），以及配置调试。它替代了此前的 claude-code-hooks、claude-code-headless、claude-code-debug 三个技能。资料注明其编写基准为 Claude Code ~v2.1.17x，内容对齐 2026 年 6 月文档；并提示这些表面变化较快，精度要求高时应核对在线文档。
主要能力
技能内置多份分工明确的参考资料，按使用意图路由：
- 编写/修复 hook、事件契约、阻塞工具、审计日志 → references/hooks-reference.md
- 编写 skill、frontmatter 字段、$ARGUMENTS、!
cmd注入、触发问题 → references/skills-reference.md - claude -p、CI 脚本、输出解析、stream-json、结构化输出、后台代理 → references/headless-reference.md
- 配置不生效、插件校验、/doctor → references/debugging-reference.md
- 设计新扩展（选择表面、作用域、撰写 description/prompt）→ references/extension-architecture.md
随附资源：scripts/validate-hooks-json.py 用于按 30 事件契约对 hooks.json（或 settings.json 的 "hooks" 块）做结构化离线校验；assets/hooks.json.template 提供常见模式起手模板（PreToolUse Bash、PostToolUse Edit|Write、SessionStart，基于 ${CLAUDE_PLUGIN_ROOT} 根路径）。
使用方式
校验 hooks 文件（离线、结构化）：
python skills/claude-code-ops/scripts/validate-hooks-json.py hooks/hooks.json
脚本说明：退出码 0 表示干净，可输出发现项、JSON 格式错误、未找到等结果。支持 --json 输出便于 CI 消费，例如：
python skills/claude-code-ops/scripts/validate-hooks-json.py --json hooks/hooks.json | jq '.data[]'
--strict 会把可移植性警告（未使用根路径的命令路径）计为发现项。
新建 hooks 文件可从 assets/hooks.json.template 复制，去掉 // 注释行（正式 hooks.json 必须是严格 JSON），再用上述脚本校验。
技能还给出心智模型：Skills 为按需加载的提示内容（描述始终在上下文，正文在调用时加载），是指导而非保证；Hooks 为生命周期事件上的确定性 shell/HTTP/MCP/model 处理器，属于保证（“绝不能发生”用 hooks 或权限，“我们这么做”用 skills/CLAUDE.md）；Subagents 为独立上下文窗口，拥有自己的系统提示、工具、模型、权限；Headless 是同一代理循环由 claude -p 驱动；Plugins 是打包以上内容的目录（skills/、agents/、hooks/hooks.json、.mcp.json），清单位于 .claude-plugin/plugin.json。
Hooks 速览：在 "hooks" 键下配置，位置可为 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、插件 hooks/hooks.json 或 skill/agent frontmatter。契约是 stdin 传入 JSON 载荷，以退出码响应（0 正常，2 阻止并输出 stderr 反馈），并可选输出 stdout JSON。事件目录包括 SessionStart、SessionEnd、Setup、UserPromptSubmit、UserPromptExpansion、PreToolUse、PermissionRequest、PermissionDenied、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、StopFailure、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、TeammateIdle、Notification、MessageDisplay、ConfigChange、CwdChanged、FileChanged、PreCompact、PostCompact、InstructionsLoaded、WorktreeCreate、WorktreeRemove、Elicitation、ElicitationResult。Hook 类型有 command、http、mcp_tool、prompt、agent；matcher 为区分大小写的字符串（如 "Edit|Write"，允许正则）。
Skills 速览：项目路径 .claude/skills/<name>/SKILL.md，个人路径 ~/.claude/skills/<name>/SKILL.md。frontmatter 字段含 when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、allowed-tools、disallowed-tools、model、effort、context: fork + agent、hooks、paths、shell；替换项含 $ARGUMENTS、$ARGUMENTS[N]、$N、$name、${CLAUDE_SKILL_DIR}、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT}；!command 在加载时执行并内联输出。正文在整个会话保留，但自动压缩仅重新附加其前 5,000 tokens（跨技能 25,000），建议 SKILL.md 少于 500 行、约 5k tokens。
Headless 速览：claude --bare -p "query" --allowedTools "Read,Grep" --output-format json | jq -r '.result'；--bare 用于可复现 CI 运行；--output-format json 产出 .result、.session_id、.is_error、.total_cost_usd、.num_turns；--json-schema 产出 .structured_output；stream-json 用于 token 流；多轮用 --continue、--resume、--fork-session，上限用 --max-turns、--max-budget-usd；后台运行用 claude --bg。
调试路径：用 /context、/memory、/skills、/agents、/hooks、/mcp、/permissions 查看加载项；/doctor 检查配置有效性；/status 查看作用域优先级；claude --debug 观察实时；claude --safe-mode 与 CLAUDE_CONFIG_DIR=/tmp/clean claude 做二分。资料还列出常见问题：hooks 属于 settings.json 而非 ~/.claude.json；matcher 是区分大小写的字符串而非数组；skills 需要文件夹加 SKILL.md；.mcp.json 位于仓库根；settings.local.json 覆盖 settings.json；磁盘上的 agent 文件在会话启动时加载；CI 中使用 claude plugin validate --strict。
适用场景
需要编写或修复 Claude Code hook、理解 hook 事件契约、在 CI 中调用 claude -p 并解析输出、编写 skill 并解决触发问题、排查配置不生效，或设计新的 Claude Code 扩展时。
限制
资料提示这些表面变化较快，精度重要时需核对官方在线文档；脚本为离线结构化校验，非运行时验证；文中注明两个旧契约已失效：$TOOL_INPUT 环境变量式 hook 契约（现改读 stdin JSON）与独立命令文件系统（命令已并入 skills）。其他未在资料中说明的功能、收费或平台信息暂未提供。