skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
affaan-m/ecc103 installs

config-health

Runtime configuration integrity monitoring for Claude Code. Detects config drift, rule staleness, and hook wiring gaps at startup, with an optional per-tool mode. Complements delivery-gate with startup soft monitoring.

How do I install this agent skill?

npx skills add https://github.com/affaan-m/ecc --skill config-health
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubwarn

    The skill establishes persistence by installing shell hooks that execute Python scripts automatically during session startup and tool use. It relies on an external installation tool (npx ecc-universal) that downloads code from the npm registry, requiring trust in the source package and the resulting scripts.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Config Health

A real-time monitoring layer. delivery-gate blocks at session end; config-health catches problems during the session — when cheap to fix.

When to Activate

  • After installing delivery-gate and wanting defense in depth
  • When hooks silently stop firing
  • When config rules accumulate but you're unsure which still work
  • At session startup for config integrity scan
  • Optionally before high-risk Edit/Write operations; this is opt-in, not default

How It Works

Session Start → config-health scans rules/hooks (soft warnings, never blocks) Session Work → optional PreToolUse guard, only if you wire it yourself Session End → delivery-gate verifies (hard block, exit 2)

Boundary: "Can this be fixed retroactively?" Config drift → config-health warns. Missing growth-log → delivery-gate blocks (hard exit 2).

What It Monitors

  1. Hook Wiring Audit: every script a hook command references, checked against disk. Runs at session start by default. An optional PreToolUse mode can also run it per matched Edit/Write call; that mode is not part of the default wiring and is not recommended unless you want the recurring cost.
  2. Rule Health: every rules/*.md referenced from CLAUDE.md exists.
  3. Guard Staleness: rules whose fire counter has been zero across the last five sessions recorded in rule-health.jsonl — the last five records, then filtered down to the ones complex enough to judge, so a verdict needs at least five records in total.

The default wiring is SessionStart only. PreToolUse is available as an opt-in mode, but it is not recommended by default: it adds a fresh-process parse of this script to every matched Edit and Write without adding tool-specific evidence. See PreToolUse Cost.

Hook Paths

Hook commands are split the way a shell splits them before any path is checked, so a normal plugin install does not report every hook as missing:

  • ~/.claude/scripts/x.py, $HOME/scripts/x.py and ${USERPROFILE}/… resolve against the user home.
  • ${CLAUDE_PLUGIN_ROOT}/… and ${CLAUDE_PROJECT_DIR}/… are expanded.
  • A bare relative path (.claude/scripts/x.py, scripts/hooks/x.js) is resolved under the project dir, the user home and the plugin root, because a hook command does not say which of those it runs from. It is reported only when it is missing from all three.
  • A quoted word is one argument, so python3 "C:\Program Files\ecc\guard.py" is not cut at the space, and ; | & inside quotes are part of the name rather than separators. One deliberate exception to shell quoting: a backslash escapes only whitespace, quotes and shell metacharacters — never another backslash, $ or a backtick. So C:\Users\me\guard.py, \\server\share\x.py and C:\$Recycle.Bin\x.py survive intact, which a POSIX escaper would mangle into paths that do not exist.
  • An interpreter's program body is not a script path, and the two kinds are treated differently. sh -c "python3 x.py" is a command line, so it is scanned again as one; -c, -lc and --command all count, and an option in between (bash -x -c, bash -o pipefail -c) does not orphan the body. A node -e or python -c body is source in another language, where a string is a string: p.join(r,'scripts/hooks/x.js') is assembled at runtime and is not a file anything will open, so it is skipped. A missing file named inside a JS body is therefore not reported — the monitor cannot tell a path from a string.

What is skipped rather than reported: a token carrying a placeholder this monitor does not resolve, a placeholder whose expansion lands outside the audited roots, a single-quoted placeholder (the shell does not expand it), a command with an unclosed quote anywhere in it including inside a sh -c payload, and a sh -c chain nested deeper than three.

--check prints what was left unjudged, because a blind spot nobody can see is not a health check:

| N hook path(s) not audited | placeholders or paths the monitor would not judge, plus commands it could not parse | | N hook command(s) have an unclosed quote | commands with a quote that never closes — a typo, not a design decision | | N hook command(s) nested sh -c deeper than 3 levels | nesting the monitor stopped following; the rest of the command was still audited | | N interpreter program body/bodies were skipped unjudged | node -e / python -c bodies, where a file named inside is a string in another language and cannot be checked | | N settings file(s) could not be read | a warning, not info: a malformed settings file is the one input whose contents decide the answer, and it was not audited | | N relative hook path(s) were satisfied by the user home or plugin root | the multi-root trade: a project-scoped hook that is genuinely broken looks exactly like a healthy plugin one here | | $CLAUDE_PLUGIN_ROOT resolved to … | the root it judged against |

On a healthy ECC install the last two lines are the interesting ones: a real one reports 0 findings with 23 program bodies skipped and 17 relative paths satisfied by the plugin root.

Env Inputs

Findings are a function of the settings files and these variables, not of the process environment:

VariableEffect
CONFIG_HEALTH_USER_HOMEuser home; also what ~ and $HOME resolve to
CLAUDE_CONFIG_DIRClaude data root; user settings and the rule-health log; default ~/.claude
CLAUDE_PROJECT_DIRproject dir
CONFIG_HEALTH_PLUGIN_ROOTpins the plugin root
CLAUDE_PLUGIN_ROOTplugin root; CONFIG_HEALTH_PLUGIN_ROOT wins

When a launcher sets CLAUDE_CONFIG_DIR, ~/.claude/settings.json is not the file Claude loads. The monitor reads $CLAUDE_CONFIG_DIR/settings.json instead, and --check prints the root it resolved.

More than one plugin installed? The provider sets CLAUDE_PLUGIN_ROOT to the root of the plugin that is running, so a settings line wired for a second plugin is judged against the wrong directory. One variable cannot describe two plugins; set CONFIG_HEALTH_PLUGIN_ROOT explicitly in that case.

Standalone install? Copy the entry point and its three helper modules (config_health_constants.py, config_health_paths.py, config_health_scan.py) into the same directory as config-health.py; the entry imports them by name. That puts it where no plugin root is in its environment. Two things follow, and both are worth acting on rather than ignoring:

  • ${CLAUDE_PLUGIN_ROOT}/… lines become unresolvable, so they are skipped — silence, not verification;
  • the plugin root is no longer one of the directories a relative path is checked against, so ECC's own scripts/hooks/x.js references get judged against your project and your home, and this repo's 23 hooks produce 17 findings. Those findings are not noise; they are the monitor correctly reporting that it cannot see the plugin.

Set CONFIG_HEALTH_PLUGIN_ROOT in the hook's env block, or wire those hooks with ~ or $HOME, if you want them covered.

PreToolUse Cost (opt-in)

--pretool is opt-in. If you wire it, it runs once per matched tool call — typically every Edit and every Write — in a fresh process, and the audit runs on every one of them. "Does this script exist" is a property of the settings files, not of the call about to run, so a per-tool hook adds no tool-specific evidence.

Measured on this repository's real 23 hook commands, Python 3.12 on Windows, interleaved A/B so scheduler drift cancels, median of 30 paired runs:

beforeafter
the wiring audit itself, in process4.33 ms3.83 ms
parsing and compiling this script (a __main__ script is never byte-cached)1.06 ms3.00 ms
whole --pretool process, median50.6 ms54.7 ms
python -c pass, for reference42.1 ms42.1 ms

Two things worth separating, because they point in opposite directions:

  • The audit got cheaper. 4.33 ms → 3.83 ms, despite now doing strictly more work: expanding placeholders, splitting commands like a shell, and checking three roots per relative path. The old version spent that time producing 55 findings about files that exist, each one a stat plus a formatted string.
  • The script got bigger, and that is the whole cost. 10.7 KB → 42 KB is +1.9 ms of parse-and-compile on every invocation, because a script run as __main__ is never byte-cached to a .pyc.

Net: +4.1 ms on a ~55 ms hook invocation, about 8%, and the honest attribution is script size, not the audit. Stripping every docstring recovers 0.15 ms of the compile, so it is the code, not the prose.

This is why the default wiring keeps only --startup: the audit runs once per session instead of once per matched tool call, and the parse cost goes with it. Opt in only if the per-call check is worth about 8% on each matched call.

The hook payload is drained and discarded, never parsed and never printed. Its size cannot change the verdict. timeout in the hook wiring, not the read, is what bounds a hanging hook.

Examples

Missing hook script: hook "PreToolUse" references missing script: .claude/scripts/ghost.py → the settings file points at a file that is not there. Still exit 0.

Dead rule reference: CLAUDE.md references missing rule file: rules/ghost.md → exit 0.

Rule staleness: rule "双池强制触发" has not fired in the last 5 sessions → may be dead — the window is the five most recent complex sessions, not an arbitrary number of sessions back. Any positive count inside that window keeps the rule alive, even in a short session: a count above zero means the rule did fire.

Healthy plugin install: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/guard.py" with the plugin installed → no finding. If guard.py is genuinely absent from the plugin → one finding, still exit 0 — provided CLAUDE_PLUGIN_ROOT (or CONFIG_HEALTH_PLUGIN_ROOT) is set in the monitor's own environment. Without it the token is unresolvable and there is no finding either way.

What this monitor reads: the hook-wired settings files — settings.json in the user dir, in the project dir, and .claude/settings.local.json in the project dir; plus the plugin's own hooks/hooks.json when CLAUDE_PLUGIN_ROOT (or CONFIG_HEALTH_PLUGIN_ROOT) is set — CLAUDE.md (in the project dir), and $CLAUDE_CONFIG_DIR/session-data/rule-health.jsonl (default ~/.claude/session-data/rule-health.jsonl). It reads no documentation to find references, and it does not count how many places a script is wired.

Install

ECC users: install the config-health module with an explicit hook decision — npx ecc-universal install --modules config-health --enable-hooks for the default SessionStart wiring, or the full profile with hook consent. The installer refuses to apply a hook-shipping module without --enable-hooks or --no-hooks. It is a Claude-only module; PreToolUse is opt-in. It does not target other harnesses, so it stays isolated from shared 13-harness modules.

The module ships its own hook config (manifests/install-assets/config-health-hooks.json), merged into settings.json at install time with the install root substituted for ${CLAUDE_PLUGIN_ROOT} — so a home install points at ~/.claude/scripts/config-health.py and a project install at <project>/.claude/scripts/config-health.py. Because that merge is a settings write, it is gated by hook consent:

  • npx ecc-universal install --modules config-health --enable-hooks wires the SessionStart hook.
  • npx ecc-universal install --modules config-health --no-hooks installs the script and skill only; nothing is written to settings.json, and you wire it yourself from the JSON below.

Uninstall removes the hook entry along with the files.

Standalone: copy scripts/config-health.py and the three helper modules (config_health_constants.py, config_health_paths.py, config_health_scan.py) to ${CLAUDE_CONFIG_DIR:-~/.claude}/scripts/ and verify the entry point exists before enabling. The helpers must sit in the same directory as the entry point. If your launcher sets CLAUDE_CONFIG_DIR, use that path in the hook command; ~/.claude is not the file Claude loads in that setup.

Important: Merge these hook entries into your existing hooks object — do not replace it, or you will lose hooks like delivery-gate.

Default (SessionStart only):

{
  "hooks": {
    "SessionStart": [{"hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --startup", "timeout": 60}]}]
  }
}

Optional per-tool mode (opt-in; adds a fresh process on every matched Edit and Write; not recommended by default):

{
  "hooks": {
    "PreToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --pretool", "timeout": 60}]}]
  }
}

Design Principles

  1. Never block on process monitoring — config-health warns; delivery-gate blocks
  2. Check what delivery-gate can't — config behavior vs filesystem state
  3. Bias every judgement toward silence, and count what you did not judge. A path this monitor cannot build is unknown, not missing. A relative path is reported only when it is missing under every audited root. The asymmetry is deliberate: silence costs a missed check, a false warning costs the user's trust in every other line this hook prints.
  4. Say what you did not check. --check prints the skipped, unparsed and cross-root counts, so a blind spot can be found and fixed rather than assumed.

Files

FilePurposeHook
scripts/config-health.pyCLI entry: startup, pre-tool, checkSessionStart; PreToolUse opt-in
scripts/config_health_constants.pyConstants, regexes, audit sets—
scripts/config_health_paths.pyPath resolution and defensive reads—
scripts/config_health_scan.pyShell-command tokenising and scanning—

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/affaan-m/ecc/config-health">View config-health on skillZs</a>