th-tooling

name	th-tooling
description	Use for hygiene of this machine's AI-tooling harness — the ~/.dotfiles repo, the ai-bootstrap skills tree, and the installed tool homes (~/.claude, ~/.codex, ~/.gemini): auditing real skill usage from transcripts, archiving unused skills, reviewing dotfiles for conflicting aliases/config, refreshing snapshot state (skill symlinks, submodules, mirrored assets), transcript disk retention, compacting agent memory (AGENTS.md notes, bd memories), and auditing MCP/permission/hook config against actual use. Route to exactly one subskill per task. Triggers: "audit my skills", "which skills are unused", "review my dotfiles", "clean up my zshrc", "refresh snapshots", "old transcripts eating disk", "compact my notes to self", "audit my MCP servers", "harness hygiene".
metadata	{"owner":"tze","authors":["tze","Claude Fable 5"],"status":"active","last_reviewed":"2026-06-12"}
compatibility	audit-skill-hygiene requires uv (Python 3.9+) and reads local Claude Code / Codex transcripts; all subskills assume the ~/.dotfiles + ai-bootstrap layout.

TH Tooling

Superskill router for keeping the AI-tooling harness clean as cruft accumulates over months of use. Three subskills live under subskills/, each a complete skill package. They are not in the global catalog — discover them lazily and load at most one per task.

/th-engineering governs the quality of a change; /th-projects governs a project's knowledge architecture; this superskill governs the harness itself: which skills are installed, what the dotfiles configure, and whether snapshot state (symlinks, submodules, mirrors) is fresh.

Discover subskills

PKG="$(dirname "<absolute-path-to-this-SKILL.md>")"
find "$PKG/subskills" -maxdepth 2 -name SKILL.md
rg -n "^name:|^description:" "$PKG"/subskills/*/SKILL.md

Routing table

Task intent	Subskill	Typical trigger
Measure real skill usage from Claude Code / Codex transcripts; recommend archiving non-new skills with no real usage in the window.	subskills/audit-skill-hygiene/SKILL.md	"audit my skills", "which skills are unused", "frontmatter is bloating my context"
Review dotfiles (rc files, aliases, env, tool config) for conflicts, dead config, and best practices — without touching secret files.	subskills/dotfiles-review/SKILL.md	"review my dotfiles", "clean up my zshrc", "are my aliases conflicting"
Re-run every snapshot/mirror flow so installed state matches source: skill symlinks, git submodules, plugin updates. Also hosts the read-only harness doctor (all verify checks, no refresh).	subskills/refresh-snapshots/SKILL.md	"refresh snapshots", "update submodules", "relink skills", "is my harness healthy"
Disk retention for session transcripts and tool logs: inventory, age-tiered compress/delete policy, audit-window trade-off.	subskills/transcript-retention/SKILL.md	"transcripts eating disk", "clean up old sessions"
Compact append-only agent memory: AGENTS.md notes-to-self, bd memories — dedupe, merge superseded, retire orphans, keep guardrails.	subskills/memory-hygiene/SKILL.md	"AGENTS.md is huge", "compact my notes", "stale memories"
Audit non-skill context surfaces: MCP servers, permission allowlists, hooks — configured vs. actually used in transcripts.	subskills/config-surface-audit/SKILL.md	"audit my MCP servers", "stale permissions", "config bloat"

Routing rules

• Measure vs. act: "what is unused / what should go" → audit-skill-hygiene. Actually moving skills to skills/archive/ is part of that subskill's output contract; the move itself needs no other subskill.
• Config content vs. installed state: questions about what the dotfiles say (aliases, exports, rc files) → dotfiles-review; questions about whether what's installed matches the repo (links, submodules, mirrors) → refresh-snapshots.
• Full hygiene pass: run all three as parallel subagents, each given the absolute path to its subskills/<name>/SKILL.md, the scope, and an output contract of findings + proposed commands. Synthesize before acting.
• Fallback: harness-adjacent but no row fits (e.g. authoring a new skill → /th-engineering skill-standards; bootstrap.sh logic changes → plain engineering work). Do not load a subskill to browse.

Shared invariants (all subskills)

• Recommendations over silent action: archive moves, dotfile edits, and submodule advances are proposed with evidence (counts, file:line, command output) before being applied.
• Never read or quote secret material: anything gitignored, under credentials/, or in to_source/machine_specific / to_source/passwords is out of bounds (verify with git check-ignore when unsure).
• Non-destructive by default: prefer skills/archive/ moves and idempotent re-runs over deletion; everything must be restorable with one git mv or one bootstrap re-run.