Codex 与 Claude Code 的 Skill Plugin Hook 机制

skill-name/
├── SKILL.md          ← 任务说明（frontmatter + 正文）
├── scripts/          ← 可执行脚本
├── references/       ← 参考文件
└── assets/           ← 资源文件

会话启动 → 只加载 name + description（轻量，占上下文很少）
用户触发 → 加载 SKILL.md 正文
执行中    → 按需读取 references / scripts / assets

my-plugin/
├── .claude-plugin/plugin.json   ← CC manifest
├── .codex-plugin/plugin.json    ← Codex manifest（可同时存在）
├── skills/
├── hooks/
├── commands/
├── agents/
├── .mcp.json
└── bin/

UserPromptSubmit   用户提交消息时
PreToolUse         工具调用前（可阻止执行）
PostToolUse        工具调用后
Stop               回合结束时
SessionStart       会话启动时

~/.claude/plugins/
├── installed_plugins.json       ← 安装注册表
├── known_marketplaces.json      ← 市场来源注册
├── cache/                       ← 版本化缓存（仅 git-based 市场用）
│   └── claude-plugins-official/
│       ├── skill-creator/205b6e0b3036/     ← git SHA 做版本号
│       └── frontend-design/205b6e0b3036/
├── marketplaces/                ← 市场目录
│   ├── claude-plugins-official/ ← git clone 的官方市场
│   ├── iplugin/                 ← 本地目录市场
│   │   └── iplugin -> /Users/markz/code/tools/iplugin  ← ★ 软链接
│   └── RDxiaogang/
├── data/                        ← ${CLAUDE_PLUGIN_DATA}，持久数据
└── local/                       ← 手动注册的本地插件

config.toml:
  [marketplaces.personal]
  source = "/Users/markz"
      ↓
寻找 /Users/markz/.agents/plugins/marketplace.json
      ↓
marketplace.json 显式列出每个插件及其相对路径：
  { "name": "iplugin", "source": { "path": "./plugins/iplugin" } }
      ↓
解析 /Users/markz/plugins/iplugin（软链接 → 源码仓库）

~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/

~/.codex/
├── config.toml                  ← 主配置（插件启用、hook trust、MCP 等）
├── plugins/
│   └── cache/
│       ├── personal/
│       │   └── iplugin/
│       │       └── 0.13.6/      ← 当前版本的完整副本
│       ├── openai-bundled/      ← Codex App 内置插件
│       └── openai-curated/      ← 审核过的第三方插件
├── hooks/
│   └── iplugin-skill-telemetry.py  ← 稳定 wrapper
└── skill-usage.jsonl            ← telemetry 日志
 
~/plugins/
└── iplugin -> /Users/markz/code/tools/iplugin  ← 软链接
 
~/.agents/plugins/marketplace.json  ← personal marketplace 索引

[hooks.state."iplugin@personal:hooks/codex-hooks.json:post_tool_use:0:0"]
trusted_hash = "sha256:01acb9c..."
enabled = true

/Users/markz/code/tools/iplugin/         ← 唯一真实源码（git 仓库）
├── .claude-plugin/plugin.json           ← CC manifest
├── .codex-plugin/plugin.json            ← Codex manifest
├── skills/                              ← 共用（SKILL.md 格式通用）
├── hooks/
│   ├── hooks.json                       ← CC 专用 hook 配置
│   ├── codex-hooks.json                 ← Codex 专用 hook 配置
│   └── skill-telemetry.py              ← 共用脚本
└── ...
 
        ┌─── 软链接 ───┐
        v               v
CC 侧                   Codex 侧
~/.claude/plugins/      ~/plugins/
  marketplaces/iplugin/   iplugin -> 源码
    iplugin -> 源码

settings.json hook:
  "python3 ~/.claude/plugins/marketplaces/iplugin/iplugin/hooks/skill-telemetry.py"
      ↓ 解引用软链接
  /Users/markz/code/tools/iplugin/hooks/skill-telemetry.py

marketplace.json → ~/plugins/iplugin → 源码仓库
      ↓ Codex 读取 .codex-plugin/plugin.json 的 version
      ↓ 全量复制到缓存
~/.codex/plugins/cache/personal/iplugin/0.13.6/
      ↓ ${PLUGIN_ROOT} 指向缓存
hook 执行：缓存目录里的脚本

PostToolUse hook (completed)
feedback: python3: can't open file
  '~/.codex/plugins/cache/personal/iplugin/0.13.0/hooks/skill-telemetry.py':
  [Errno 2] No such file or directory

旧方案：${PLUGIN_ROOT}/hooks/skill-telemetry.py
  ↓ 依赖版本缓存路径，升级后可能失效
 
新方案：$HOME/.codex/hooks/iplugin-skill-telemetry.py
  ↓ 固定位置的 wrapper，再动态定位真实脚本

1. 环境变量 IPPLUGIN_TELEMETRY_SCRIPT（手动覆盖）
2. /Users/markz/code/tools/iplugin/hooks/skill-telemetry.py（源码仓库）
3. ~/.codex/plugins/cache/personal/iplugin/*/hooks/skill-telemetry.py（最新缓存）