给 AI Agent 装个行车记录仪：用 Claude Code 和 Codex 的 Hook 追踪 Skill 调用

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log_skill.sh",
            "args": ["pre"]
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log_skill.sh",
            "args": ["post"]
          }
        ]
      }
    ],
    "UserPromptExpansion": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log_skill.sh",
            "args": ["expansion"]
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# log_skill.sh — append skill events to JSONL
set -euo pipefail

PHASE="${1:-unknown}"
LOG_DIR="${HOME}/.claude/skill-usage"
mkdir -p "$LOG_DIR"
LOG_FILE="${LOG_DIR}/skill_usage_$(date +%Y%m%d).jsonl"

# stdin 是 Claude Code 喂给咱们的事件 JSON
INPUT="$(cat)"

# 用 jq 给每条事件打上 phase 和本地时间戳，方便后面查
echo "$INPUT" | jq -c \
  --arg phase "$PHASE" \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '. + {phase: $phase, logged_at: $ts}' \
  >> "$LOG_FILE"

# Hook 必须静默退出，stdout 在 PreToolUse 里会被当成决策返回值
exit 0

{"session_id":"abc-123","tool_name":"Skill","tool_input":{"skill_name":"lazy-blog-write","prompt":"..."},"phase":"pre","logged_at":"2026-06-01T13:55:21Z"}
{"session_id":"abc-123","tool_name":"Skill","tool_response":{"success":true,"duration_ms":1832},"phase":"post","logged_at":"2026-06-01T13:55:23Z"}

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/env python3 ~/.codex/hooks/log_skill.py prompt"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|apply_patch|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/env python3 ~/.codex/hooks/log_skill.py pre"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|apply_patch|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/env python3 ~/.codex/hooks/log_skill.py post"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/env python3 ~/.codex/hooks/log_skill.py session"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""log_skill.py — append Codex skill-relevant events to JSONL."""
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path

LOG_DIR = Path.home() / ".codex" / "skill-usage"
LOG_DIR.mkdir(parents=True, exist_ok=True)
LOG_FILE = LOG_DIR / f"skill_usage_{datetime.now().strftime('%Y%m%d')}.jsonl"

SKILL_INVOCATION = re.compile(r"\$([a-zA-Z][\w-]*)")


def main() -> None:
    phase = sys.argv[1] if len(sys.argv) > 1 else "unknown"
    try:
        event = json.load(sys.stdin)
    except json.JSONDecodeError:
        # 收不到合法 JSON 时静默退出，不要拖累主流程
        return

    record = {
        "phase": phase,
        "logged_at": datetime.now(timezone.utc).isoformat(),
        "session_id": event.get("session_id"),
        "turn_id": event.get("turn_id"),
        "hook_event_name": event.get("hook_event_name"),
    }

    if phase == "prompt":
        prompt = event.get("prompt", "")
        # 把用户输入里的 $skill 显式调用挑出来
        skills = SKILL_INVOCATION.findall(prompt)
        record["skill_invocations"] = skills
        record["prompt_preview"] = prompt[:200]
    elif phase in {"pre", "post"}:
        record["tool_name"] = event.get("tool_name")
        record["tool_use_id"] = event.get("tool_use_id")
        # 参数留前 500 字符就够取证，别把整个 patch 都写进日志
        ti = event.get("tool_input")
        if ti is not None:
            record["tool_input_preview"] = json.dumps(ti)[:500]
    elif phase == "session":
        record["source"] = event.get("source")
        record["cwd"] = event.get("cwd")

    with LOG_FILE.open("a") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


if __name__ == "__main__":
    try:
        main()
    finally:
        # 任何异常都不要影响 Agent 主流程，silently exit 0
        sys.exit(0)

# 1. 过去一天，哪些 skill 被实际调用了，按次数排序（Claude Code 视角）
cat ~/.claude/skill-usage/skill_usage_$(date +%Y%m%d).jsonl \
  | jq -r 'select(.phase=="pre") | .tool_input.skill_name' \
  | sort | uniq -c | sort -rn

# 2. Codex 里，用户主动 $触发 的 skill 都有哪些
cat ~/.codex/skill-usage/skill_usage_$(date +%Y%m%d).jsonl \
  | jq -r 'select(.phase=="prompt") | .skill_invocations[]?' \
  | sort | uniq -c | sort -rn

# 3. 单次 skill 调用平均耗时（Claude Code，配对 pre/post）
cat ~/.claude/skill-usage/skill_usage_*.jsonl \
  | jq -s '
      group_by(.tool_use_id // .session_id)
      | map(select(length==2))
      | map({
          skill: (.[0].tool_input.skill_name // "unknown"),
          ms: ((.[1].logged_at | fromdate) - (.[0].logged_at | fromdate)) * 1000
        })
      | group_by(.skill)
      | map({skill: .[0].skill, avg_ms: (map(.ms) | add / length)})
    '

@startmindmap
* Skill Usage Hook
** Claude Code
*** PreToolUse / matcher: Skill
*** PostToolUse / matcher: Skill
*** UserPromptExpansion (斜杠命令)
*** 落点: ~/.claude/settings.json
** Codex CLI
*** UserPromptSubmit (扫 $skill)
*** PreToolUse / Bash|apply_patch|mcp__.*
*** PostToolUse / 同上
*** SessionStart
*** 落点: ~/.codex/hooks.json
** 日志策略
*** JSONL 按天分文件
*** 敏感字段 redact
*** logrotate / cron 清理
** 查询
*** skill 调用次数排行
*** 平均耗时
*** $显式 vs 隐式触发比例
** 安全闸门
*** Codex 需 /hooks trust
*** hook 失败不阻断 Agent
*** stdout 仅放决策 JSON
@endmindmap