rootnode-repo-hygiene — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited rootnode-repo-hygiene (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
A two-phase Skill for auditing and cleaning up Claude Code repositories. Phase 1 sweeps the repo across 14 categories of hygiene concern plus a cross-category 7-layer placement leak check, producing a HYGIENE_REPORT.md. Phase 2 reads [APPROVED] markers placed in that file and executes the marked findings under critic-gate composition with halt-on-failure discipline.
The Skill is the operational counterpart to rootnode-cc-design: design produces the environment, hygiene maintains it. Structural findings that warrant fix-recipe derivation route to rootnode-cc-design REMEDIATE rather than executing here. Process-abstraction candidates that recur across CC environments route as warrant evidence for rootnode-skill-builder v2.
These five principles override looser interpretations elsewhere in this Skill. They are enforcement-grade.
1. Authorization is file-state-grounded. Phase 2 reads [APPROVED] markers from the report file. Verbal authorization in chat is never a substitute. The Skill MAY act as a text editor on the user's behalf using the three approval forms (blanket, fragmented, conditional — see "Authorization discipline" below). When acting as editor, the Skill produces the marked file for the user to save; Phase 2 then reads the saved file. There is no verbal-authorization fallback. The discipline guards against the silent execution problem: chat-side intent is high-context but ephemeral; the marked file is the durable contract.
2. Recommendation-only categories never execute directly. Categories 11-14 and 7-layer leak findings are recommendation-only. [APPROVED] markers on these findings are noted in Phase 2 but produce a "skipped — REMEDIATE recommended" notice rather than an execution batch. The marker is preserved in the report file (it documents user intent) but does not become a file edit. Reason: structural change requires fix-recipe derivation and 7-layer placement validation that single-edit Phase 2 execution cannot perform safely.
3. Defer-to-downstream is a first-class commit-plan option. When Phase 1 detects distribution intent + working-tree state + downstream-resolvable findings, it recommends defer-to-downstream over Options A/B/C. Phase 2 accepts deferral and executes file edits without git operations; the cleanup_execution_log substitutes for commit messages as the audit trail. This is the production-validated pattern from a CC deployment where engine-baseline commit hit a permission denial on 207 MB / 883-file scope and Path 3 deferral was the right answer rather than retrying a failed commit.
4. Bootstrap heritage carve-out calibrates Cat 1. When the active profile contains a bootstrap_heritage block, Cat 1 produces a "Bootstrap heritage inventory" subsection at the top of its findings and applies sharpened detection conditions: findings only surface for inherited content modified after the threshold date, referenced by in-engine code, treated as authoritative in current docs, or otherwise active in the current project. This eliminates false positives on legitimate inherited content while preserving the ability to catch problematic inheritance.
5. Structural findings route to REMEDIATE. Cat 11-14 and 7-layer leaks always route to rootnode-cc-design REMEDIATE mode. The handoff is named explicitly in the report's "Routing recommendations" section when remediate_routing: true (default). REMEDIATE handles fix-recipe derivation and 7-layer placement validation that single-edit Phase 2 execution cannot.
Trigger this Skill on:
Symptom-phrased triggers also apply: "my CLAUDE.md feels bloated," "I have permissions I don't think I use anymore," "my CC environment has accumulated drift," "I want to know what to clean up before I share this repo."
The Skill operates CC-side only. It scans Claude Code repositories — .claude/ directory, CLAUDE.md, hooks, subagents, MCP configurations. It does not audit Claude Projects (CP-side). For Project audits, use rootnode-project-audit.
Phase 1 walks four steps:
.claude/settings.json, .claude/settings.local.json), Skills (.claude/skills/), agents (.claude/agents/), hooks, MCP declarations. Detect bootstrap_heritage block in active profile and capture its inventory. Capture working-tree state (informational; never halt). Output: pre-flight summary at the top of the report file.F-{cat}.{n} ID, risk tag, confidence tag, evidence quote, recommended action). Cat 1 applies bootstrap heritage calibration when active. Cat 2 runs both stale-removal and missing-entry directions (D9). Cat 14 produces 8-field candidate blocks rather than standard findings. See references/sweep-categories.md for detection rules per category.L-{n} findings for content placed in the wrong layer for its concern. Findings appear in their own "7-Layer Leak Findings" section near the end of the report. See references/seven-layer-framework.md.output/hygiene_reports/HYGIENE_REPORT_{ISO8601}.md with: pre-flight summary, per-category findings sections, 7-layer leak findings section (if enabled), "Routing recommendations" section (if remediate_routing: true), "Recommended commit plan" section (if include_commit_plan: true), and a marking ledger area at the bottom. The marking ledger is empty at Phase 1 end; the user (or the Skill acting as editor) populates it as authorization decisions are made.Phase 2 walks five steps:
[APPROVED] marker in report), profile validation (JSON validates against schema), engine baseline coherence (state hasn't drifted since Phase 0), critic-gate availability (when threshold is required), marker placement validation (no [APPROVED] markers on Cat 11-14 / leak findings — those skip with notice). Failing any condition halts Phase 2 entry with the specific failure surfaced.[APPROVED] Cat 1-10 findings into batches: one category per batch, subdivided by confidence tier and risk tier. Higher-confidence and lower-risk batches execute first. Each batch carries metadata for the verification step: file changes expected, category-specific verification command, finding IDs included.cleanup_execution_log.md. See references/execution-discipline.md for the per-category verification table and full critic-gate composition rules including the 3-cycle REQUEST_CHANGES cap.Halt-on-failure discipline applies throughout Phase 2. Verification failure, critic-gate REJECT, REQUEST_CHANGES exceeding 3 cycles, and commit-plan permission denial all halt with a recorded reason; the Skill does not retry automatically. Resolution is user-driven and re-invocation continues with the remaining unmarked work.
Three profiles ship with the Skill:
Custom profiles must validate against schema/profile.schema.json. Required fields: categories, include_seven_layer_leak_check, include_commit_plan, critic_gate_threshold, remediate_routing. Optional: bootstrap_heritage (Cat 1 calibration), confidence_threshold (suppresses lower-confidence findings), cat_14_extension_pass (cross-candidate dependency analysis + build-this-first recommendation).
The critic_gate_threshold field controls Phase 2 composition with rootnode-critic-gate: required halts entry if critic-gate is not installed and submits every batch for review; optional allows per-batch user choice when critic-gate is installed.
The remediate_routing field controls whether the report includes a "Routing recommendations" section naming rootnode-cc-design REMEDIATE handoff for structural findings. When false, structural findings remain in the report as recommendation-only with no automated downstream pathway named.
Per Principle 1, authorization is file-state-grounded. The Skill supports three approval forms when acting as text editor on the user's behalf.
Blanket. User says "approve all Cat N findings." The Skill marks every finding in the named category [APPROVED]. Returns the marked report file for the user to save. Suitable when the category's findings are homogeneous and the user has reviewed them as a group.
Fragmented. User says "approve F-X.1 and F-X.3, defer F-X.2." The Skill validates each finding ID exists in the report, then marks per the user's intent ([APPROVED] or [DEFERRED] per the verb used). Returns the marked file. Suitable for mixed intent within a category — typical for Cat 1 (some parent-vestige findings approve, some defer to downstream migration) and Cat 9 (stale-state findings approve, restructuring findings defer to leak handling).
Conditional. User says "approve all medium-and-low risk findings; halt high-risk for review." The Skill walks unmarked findings, applies the predicate (risk filter, category filter, confidence filter, or combination), marks matching findings [APPROVED]. Findings failing the predicate remain unmarked. Returns the marked file along with a list of what got marked and what didn't. Suitable for sweeping the long tail of low-stakes findings without naming each.
Every editor action records a marking ledger entry at the bottom of the report file: timestamp, approval form, scope, finding IDs marked, action taken. The ledger is the audit trail; Phase 2's EC-1 check reads from it indirectly (by counting [APPROVED] markers in the body), and post-Phase-2 review reads from it directly.
Phase 1 produces a "Recommended commit plan" section. Phase 2 executes the chosen plan after batches complete and pass verification.
Options:
The commit plan is a recommendation; the user can override at Phase 2 invocation by naming a different plan. The Skill warns when the override conflicts with the deferral signal but does not block.
When the active profile's bootstrap_heritage block is populated, Cat 1 calibration changes per Principle 4. Block fields:
inherited_files — explicit file paths inherited from parent projectinherited_directories — glob patterns identifying inherited file groupspackage_json_name — parent project's package.json name (for identity-string detection)modified_recently_threshold — ISO 8601 date; files modified after this surface as findingsparent_project_name — parent project name for documentation/code reference detectionWhen the block is absent or empty, Cat 1 runs without calibration (appropriate for non-bootstrapped repos). The Phase 1 inventory subsection lists inherited files but generates no findings from inventory entries alone — only the modified-recently rule, in-engine reference rule, authoritative-citation rule, or other sharpened conditions surface findings. See references/sweep-categories.md Cat 1 section for full calibration semantics including the confidence floor that prevents inherited content from generating high-confidence false positives.
Cat 14 is the highest-value scan and the differentiating feature versus generic linters. Detection signals: recurring change_log operations (3+ entries with same shape), permission patterns covering the same operation family, repeated multi-step session_closeout sequences (3+ sessions with same 3+ step sequence), deterministic state queries CC re-derives each session, hooks ending in manual prompts.
Each candidate gets all eight fields including a scope tag — project-local (specific to this project's data, paths, workflows) or methodology-generalizable (recurs across CC environments of similar shape; transfers to other projects). Methodology-generalizable candidates are the warrant evidence for shared-tooling promotion: their candidate-block format is compatible with rootnode-skill-builder v2 Gate 2 exception clause, so a methodology-generalizable Cat 14 candidate IS the handoff brief for downstream Skill or runtime-tooling builds.
The deep-audit profile sets cat_14_extension_pass: true, which runs cross-candidate dependency analysis (which candidates unlock which), order-of-build recommendation (lower-complexity + higher-frequency + no-prerequisites first), and a single "build this first" pick.
See references/process-abstraction-detection.md for full detection signals, scope categorization rules, and worked examples from the production validation set.
With `rootnode-critic-gate` (Phase 2 batch review). When critic_gate_threshold: required, every Phase 2 batch submits to critic-gate before execution. Verdicts: APPROVE → execute; REQUEST_CHANGES → adjust + resubmit (3-cycle cap, then halt); REJECT → halt with rejection surfaced. When optional, critic-gate review is per-batch user choice when critic-gate is installed; the Skill prompts "critic-gate available — invoke?" before each batch.
With `rootnode-cc-design` REMEDIATE (downstream handoff). Cat 11-14 findings and 7-layer leak findings route to REMEDIATE rather than executing in Phase 2. The "Routing recommendations" section in the report names this handoff explicitly. REMEDIATE consumes the report as input; this Skill consumes nothing from REMEDIATE in return.
As Producer for `rootnode-skill-builder` v2 Gate 2. Methodology-generalizable Cat 14 candidates (the 8-field block format) satisfy skill-builder v2's Gate 2 warrant evidence requirement. The user uploads the candidate block as a process-abstraction handoff brief; skill-builder's Gate 2 exception clause accepts it without requiring the standard 3+ occurrence + design-lineage proof.
This Skill operates exclusively on Claude Code repositories. The scan logic walks .claude/ directory contents, settings files, hooks, subagents, MCP configurations, and CLAUDE.md. None of these surfaces exist on Claude Projects.
For Project audits, use rootnode-project-audit. For prompt-level audits (single prompt or system prompt), use rootnode-prompt-validation. The CC-only constraint is intentional: cross-surface "audit anything" Skills produce shallow analysis on both sides because the surfaces have different mechanics (CP layers vs. CC layers) and different anti-pattern profiles.
The user invokes the Skill at the engine root with default profile. Phase 1 produces a report with 23 findings across 14 categories plus 3 leak findings. The user marks via three approval forms in the same session: blanket on Cat 2 ("approve all Cat 2"), fragmented on Cat 1 + Cat 9 ("approve F-1.3, defer F-1.1/F-1.2; approve all stale-state findings, skip line-count and mixed-reference"), conditional on the rest ("approve all medium-and-low risk"). The Skill applies markers via the editor pathway, recording each in the marking ledger. Phase 2 reads the marked file, builds 9 batches, executes with optional critic-gate review on the high-risk-flagged Cat 2 entry (the Bash(rm -rf*) permission removal), runs final verification (test backstop passes), and closes out. Total: 18 executed, 2 deferred, 11 + 3 leaks routed to REMEDIATE. See references/worked-example.md for the full walkthrough including Phase 1 finding output, marking ledger entries, and per-batch execution log.
Same engine as Example 1 but with active distribution intent: the maintainer is planning a fresh-repo migration in the next week. Phase 1 detects distribution intent (in CLAUDE.md), working-tree state (12 modified files), and downstream-resolvable findings (Cat 1 parent-vestige work likely moot under fresh-repo migration). The "Recommended commit plan" section names defer-to-downstream over Options A/B/C with rationale. Phase 2 accepts the deferral: file edits accumulate in the working tree (~30 modified files post-execution); no git operations run; the cleanup_execution_log substitutes for commit messages. The fresh-repo migration session handles baseline + cleanup commit pairing in proper context. This Path 3 case is production-validated: the original Phase 2 attempt under Option B engine baseline commit hit a permission denial on the engine's 207 MB / 883-file scope, which surfaced defer-to-downstream as the right answer rather than retrying the failed commit.
A maintainer runs quick-scan weekly as a pre-commit sanity check: Cat 1, 2, 6, 9 only, high-confidence floor, no leak check, no commit plan. The pass typically completes in minutes and surfaces 0-3 findings — usually a stale permission or a CLAUDE.md state value that drifted. Findings get marked blanket-style and executed without critic-gate. Once a quarter, the maintainer runs deep-audit with cat_14_extension_pass: true: all 14 categories, low-confidence floor, leak check on, critic-gate required. The deep-audit run typically surfaces 30+ findings including the long tail of speculative items the standard sweep suppresses; the extension pass surfaces dependency chains in Cat 14 (e.g., a state-query script that unlocks a snapshot-update hook). The maintainer batches REMEDIATE-bound findings into a separate session with rootnode-cc-design.
This Skill is the wrong tool when:
rootnode-skill-builder.rootnode-prompt-compilation.rootnode-prompt-validation.rootnode-project-audit.The Skill is also wrong for non-rootnode CC environments where the canonical references (root_AGENT_ENVIRONMENT_ARCHITECTURE.md, root_CC_ENVIRONMENT_GUIDE.md, root_AGENT_ANTI_PATTERNS.md) are not the audit standard. The Skill bakes in those references as the canonical source of truth; deployments using a different anti-pattern catalog will get findings that don't match their model.
Phase 2 halts at EC-1 (no `[APPROVED]` markers found). The user authorized verbally but didn't have the editor pathway invoked, or saved the marked file to a different path than the report. Re-invoke the Skill in editor mode with the user's verbal intent; produce the marked file; user saves; Phase 2 retries.
Phase 2 halts at EC-4 (critic-gate not installed, threshold required). Either install rootnode-critic-gate or downgrade the profile threshold to optional. Silently lowering the threshold to skip the gate is a discipline failure — the threshold was set to required for a reason (typically: profile is deep-audit, or mode-router conditions like sleeping/unattended map to strict).
Phase 2 halts at EC-3 (engine baseline coherence drift). The engine state shifted between Phase 1 and Phase 2 (test count changed, version bumped, branches diverged). Re-run Phase 1 to refresh the baseline; the report regenerates with current state and the user re-marks.
Phase 2 halts at EC-5 (markers on recommendation-only findings). The user marked Cat 11-14 or leak findings [APPROVED]. Phase 2 surfaces a notice naming the marked findings, names the REMEDIATE handoff, and proceeds with Cat 1-10 markers only. The marker is preserved in the report (it documents user intent) but does not flow into a Phase 2 execution batch.
Critic-gate REQUEST_CHANGES exceeds 3 cycles on a batch. The issue is structural; manual user intervention is the right escalation. The Skill halts with the unresolved critic finding surfaced. Three cycles is enough for the critic to surface and confirm a single class of issue but few enough that runaway loops can't develop.
Verification step fails after batch execution. The batch's assumptions were wrong. The Skill does not retry automatically. Investigate the verification output, address the cause (typically: a finding's recommended action did not produce the expected post-state), re-invoke Phase 2 with the remaining unmarked work.
Commit plan execution hits permission denial (e.g., engine baseline commit on a large engine scope). Accept defer-to-downstream as the right answer; the cleanup log already serves as audit trail. Re-running with Option B/C in the same context will hit the same denial.
Cat 1 surfaces too many false positives on inherited content. The active profile is missing the bootstrap_heritage block, or the block's inherited_files / inherited_directories are incomplete. Populate the block with the actual inheritance scope and re-run; the carve-out will eliminate the false-positive cluster.
Cat 14 surfaces no candidates in a project with obvious recurring work. The change_log discipline isn't being practiced (entries are too sparse to surface 3+ recurrence) or session_closeouts don't exist. The detection signals depend on documented work history; environments without those artifacts produce empty Cat 14 output. The fix is upstream — establish change_log + session_closeout discipline first.
This SKILL.md carries the activation discipline and the principle layer. Detail content lives in references/:
references/sweep-categories.md — 14 categories with detection rules, scan procedures, finding formats, confidence calibration, recommendation-only routingreferences/anti-pattern-catalog.md — Skill-relevant anti-pattern subset with audit-time application; CP-only patterns explicitly listed as not-scannedreferences/seven-layer-framework.md — 7-layer model, leak-check procedure, leak finding format, profile gatingreferences/execution-discipline.md — Phase 2 mechanics: entry conditions, batch construction, per-batch execution, critic-gate composition, commit plan execution, cleanup_execution_log formatreferences/process-abstraction-detection.md — Cat 14 deep dive: detection signals, candidate output structure, scope categorization, routingreferences/cc-best-practices.md — 12 convergence patterns this Skill audits againstreferences/worked-example.md — End-to-end production-validated walkthroughSchema and profiles:
schema/profile.schema.json — Draft-07 profile validationprofiles/default.json, profiles/quick-scan.json, profiles/deep-audit.jsonThe Skill's Phase 1 output ALWAYS includes a marking ledger area at the bottom of the report file (even when empty). The Skill's Phase 2 output ALWAYS produces a cleanup_execution_log entry per batch and a closeout summary, even when batches halt. These artifacts are the durable audit trail; they are not optional.
When in doubt about whether to execute or recommend: recommend. The cost of a deferred execution is one re-invocation; the cost of an incorrect execution is variable and can include destructive change. Phase 2's halt-on-failure discipline reflects the same principle — the Skill stops cleanly rather than guessing at a recovery the user hasn't authorized.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.