1---
2name: skills-doctor
3description: "Diagnose and maintain Codex skill registries. Use for skill metadata budget warnings, duplicates, long descriptions, noisy plugins, or rollback-safe cleanup."
4---
5 
6# Skills Doctor
7 
8Use this skill to keep Codex skill loading healthy without losing recoverability. The current implementation targets Codex local skill roots and plugin caches.
9 
10## Core Workflow
11 
121. Inventory active skill sources.
132. Measure metadata pressure from `description:` fields and estimated registry lines.
143. Find duplicates by parsed skill `name`, with paths and modification times.
154. Preserve the configured preferred active root, for example `<agent-home>/skills`.
165. Archive disabled or superseded skills outside active loader roots with a manifest.
176. Rewrite descriptions for discovery quality, aiming for 120-180 parsed characters.
187. Scrub publishable bundles for local usernames, absolute paths, hostnames, secrets, and project-specific references.
198. Verify active counts, duplicate count, parsed description length, and estimated savings.
20 
21## Reference
22 
23Read `references/codex-skill-maintenance-process.md` before making changes. It describes the reusable process for similar Codex setups: how to inventory roots, rank budget savings, archive safely, rewrite descriptions, and verify the result.
24 
25## Rules
26 
27- Prefer reversible moves over deletion.
28- Preserve newest content when deduplicating; ties prefer `<preferred-skill-root>`.
29- Keep `SKILL.md` bodies intact when the problem is metadata budget pressure.
30- Treat current-thread warnings as possibly stale because skill metadata is loaded at session start.
31- Keep manifests under a timestamped archive directory outside active loader roots, for example `<archive-root>/<operation>-<timestamp>/manifest.json`.
32- For publishable skills, use placeholders such as `<codex-home>`, `<agent-home>`, `<project-root>`, and `<archive-root>` instead of machine-specific paths.
33 
34## Useful Measurements
35 
36Measure both:
37 
38- parsed description chars and approximate tokens
39- estimated registry chars including name, description, path, and formatting
40 
41Use `len(description) / 4` as a rough tokenizer-independent estimate. Keep enough headroom for path length, plugin skills, and future additions.
42