Hook Portability Doctor

    1

    Audit Claude Code hook configs before moving to DeepSeek Harness. Get source-backed findings, JSON pointers, and Chinese JSON/Markdown reports. Python 3.11+, offline static checks; no hook commands executed.

    Free

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Hook Portability Doctor

    Example session with this skill installed

    Read this skill's SKILL.md and audit the bundled examples/migration-gaps.json against the dsh-claude-ce7073d profile. Use --strict and write reports to reports/demo. Show the complete generated Markdown report and explain the exit code. Do not execute any hook commands, and do not assume a target plugin root or project directory.

    • Read your context and instructions
    • Compiled the hook portability doctor

    This demo uses the bundled synthetic fixture examples/migration-gaps.json. The checker actually ran with --strict; exit code 1 means explicit static incompatibilities were found. No hook commands were executed. The complete generated Markdown report follows.

    Hook 迁移检查报告

    结论:发现明确不兼容项。

    本报告检查 Claude Hook 配置通过指定 DSH 兼容桥的静态差异。安装版本和实际执行尚未验证。

    • 输入:examples/migration-gaps.json
    • 规则:dsh-claude-ce7073d;目标提交:ce7073d51254c26cd63b22a60835b8f948deb447
    • 输入 SHA-256:cca494cc9d665bde28fe9a4b46bdb05b97c0458ca47d07eba588c00aed49bdd4
    • 检查器版本:0.2.0;规则核对日期:2026-11-03
    • 事件:4;配置处理器:5;待运行验证的 command 候选:2

    同一原因的路径配置、工具匹配提示按问题组归并,关联位置仍全部保留。

    分类问题组数量
    明确不兼容3
    行为变化2
    配置待确认1
    需要核对2

    检查项

    1. 明确不兼容 · HP001

    • 位置:<code>/hooks/Notification</code>
    • 判断:目标不识别此事件,整组配置会在解析处理器之前被忽略。
    • 建议:核对源平台事件名称;需要保留该功能时寻找目标的原生入口。删除配置不等于完成迁移。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-CONFIG

    2. 明确不兼容 · HP001

    • 位置:<code>/hooks/PreCompact</code>
    • 判断:目标不识别此事件,整组配置会在解析处理器之前被忽略。
    • 建议:核对源平台事件名称;需要保留该功能时寻找目标的原生入口。删除配置不等于完成迁移。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-CONFIG

    3. 行为变化 · HP003

    • 位置:<code>/hooks/PreToolUse/0/hooks/0/async</code>
    • 判断:async: true 不被采用;目标按事件的既定调度方式串行处理匹配命令,不保留此字段的后台执行语义。
    • 建议:核对是否依赖此选项;在目标中验证替代方式。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-LIMITATIONS

    4. 配置待确认 · HP005

    • 位置:<code>/hooks/PreToolUse/0/hooks/0/command</code>
    • 判断:命令引用 CLAUDE_PLUGIN_ROOT,本次检查未收到 pluginRoot;不能据此断言用户没有配置。
    • 建议:用 --plugin-root 提供目标桥的实际插件根目录后复查。
    • 确定性:需要目标上下文或实际验证
    • 依据:DSH-CONFIG

    5. 需要核对 · HP006

    • 位置:<code>/hooks/PreToolUse/0/matcher</code>
    • 判断:工具名与目标正则语义需要运行核对。
    • 建议:核对实际匹配主体;本工具不使用 Python 正则冒充目标正则验证。
    • 确定性:需要目标上下文或实际验证
    • 依据:DSH-CONFIG

    6. 明确不兼容 · HP002

    • 位置:<code>/hooks/Stop/0/hooks/0/type</code>
    • 判断:目标只执行 command 处理器,这个处理器会被跳过。
    • 建议:确认其意图后编写经过验证的目标实现;仅修改 type 无法保留原功能。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-CONFIG

    7. 行为变化 · HP003

    • 位置:<code>/hooks/Stop/0/hooks/1/args</code>
    • 判断:独立 args 字段被忽略;目标只保留 command 字符串。
    • 建议:核对是否依赖此选项;在目标中验证替代方式。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-LIMITATIONS

    8. 需要核对 · HP004

    • 位置:<code>/hooks/Stop/0/matcher</code>
    • 判断:目标对该事件忽略 matcher。源平台也可能如此,不能仅凭此字段断言迁移产生回归。
    • 建议:确认功能未依赖此匹配条件;此 matcher 不参与目标正则校验。
    • 确定性:已确认该目标快照的行为
    • 依据:DSH-CONFIG

    尚未验证

    • 目标实际安装版本与规则快照是否一致
    • Hook 命令、脚本输出、依赖和 shell 行为
    • 目标正则是否合法及实际工具名称是否匹配
    • 其他配置层的合并、事件时序与实际运行结果

    处理器候选数量只反映静态结构;正则、脚本依赖和运行时仍可能阻止注册或执行。

    Next steps: inspect report.json and report.md, confirm the actual DSH version and target root context, then separately test the affected hooks in the target runtime.

    inspect report.json and report.md

    Connects securely to your tools. The creator never sees your data.

    About this skill

    What it does

    Hook Portability Doctor checks Claude Code hooks.json, settings.json, or a plugin directory before migration to the DeepSeek Harness (DSH) Claude Hook bridge. It produces Chinese Markdown and JSON reports with rule IDs, JSON pointers, impact, suggested next steps, and source references pinned to a DSH commit.

    Findings you can act on

    • Unsupported events and non-command handlers that the target snapshot skips.
    • Ignored handler options such as async and args.
    • Missing plugin-root or project-directory context, kept separate from confirmed errors.
    • Matcher behavior and other items that require manual or runtime verification.

    Findings are grouped as incompatible, behavior_change, configuration, and manual_review. The checker does not run hook commands or change your configuration.

    How to use it

    Give your agent a local JSON path or plugin directory. With Python 3.11+ and local shell/file access, it runs the bundled standard-library checker and explains report.json and report.md. No API key, account connection, or network access is required for an ordinary local audit. Optional public-case reproduction downloads hash-pinned public JSON only when explicitly requested.

    Scope and evidence

    Version 0.2.0 includes rules HP001–HP008 for the dsh-claude-ce7073d profile, pinned to DSH commit ce7073d51254c26cd63b22a60835b8f948deb447. This is a fixed reference snapshot, not a claim about the latest DSH release or the user's installed version. The included checker passed 59 tests and 4 offline CLI scenarios during listing preparation.

    Boundaries

    This checks Claude Hook configuration targeting the specified DSH bridge. Invoking it from Codex does not add support for migrating Codex hook formats. It does not execute third-party hooks, inspect their script internals, validate JavaScript regex syntax, emulate shells, merge configuration layers, or prove runtime compatibility. Native-client discovery and full third-party plugin execution require separate verification.

    Free and open source

    MIT licensed. The ZIP includes SKILL.md, the checker, pinned rule data, references, documentation, and examples. The public GitHub repository is linked in the documentation field. Reports are primarily in Chinese; the agent can explain them in your preferred language.

    Only Claude Hook configuration targeting the DSH Claude bridge snapshot ce7073d is covered. The installed DSH version is not compared automatically. No Codex-hook migration, runtime-compatibility guarantee, hook execution, script-internal analysis, shell emulation, JavaScript-regex validation, configuration-layer merging, or automatic fixes. Reports are primarily Chinese. An agent must have local access to the full bundle and Python 3.11+; remote SKILL.md loading alone may not expose the bundled scripts. target_runtime_verified and execution_verified remain false for scanned inputs.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 13 days ago

    • Free with an Agensi account

    Requires

    Python 3.11+
    Agent with local shell and file access
    Python

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Network Access
    Environment Variables

    The normal audit runs the bundled Python checker, reads the user-selected local JSON/plugin paths, and writes report.json/report.md to a chosen report directory. It never executes hook command strings. No API key or connected account is needed. Network access to GitHub/raw.githubusercontent.com is optional, only for explicitly requested public-case downloads or evidence lookup. Environment variables are used by optional GitHub Action/distribution utilities; the core checker inspects variable references as text rather than reading their secret values. Browser access is not needed for the core check.

    Listed13 days ago

    What's inside

    Frequently Asked Questions

    It runs deterministic static checks against a source-pinned DSH bridge profile and reports rule IDs, JSON pointers, and evidence links. The assistant explains those results and separates confirmed differences from items needing runtime verification.

    Four categories: incompatible (unsupported events or non-command handlers skipped by the target), behavior_change (ignored options), configuration (missing target-root context), and manual_review (matcher semantics or other uncertainties). Findings retain rule IDs and JSON pointers.

    Version 0.2.0 uses the fixed dsh-claude-ce7073d profile, based on DSH commit ce7073d51254c26cd63b22a60835b8f948deb447. It does not claim to represent the newest release or the user's installed target. Other versions and migration routes require separate rules and verification.

    The tool requires a Python 3.11+ environment and access to your local `hooks.json`, `settings.json`, or plugin directories to perform the audit.

    No, the tool performs a static audit of your configuration files and directory structures without executing any scripts or emulating a shell environment.

    The complete MIT-licensed 0.2.0 skill bundle: SKILL.md, agents metadata, Python checker, pinned profile, evidence references, Chinese Markdown/JSON reporting, documentation, examples, tests, and optional CLI/GitHub Action integration utilities. No API key is required for a local audit.

    New in Code Quality & Review