Skills Doctor

Use this skill to keep Codex skill loading healthy without losing recoverability. The current implementation targets Codex local skill roots and plugin caches.

Core Workflow

1. Inventory active skill sources.
2. Measure metadata pressure from description: fields and estimated registry lines.
3. Find duplicates by parsed skill name, with paths and modification times.
4. Preserve the configured preferred active root, for example <agent-home>/skills.
5. Archive disabled or superseded skills outside active loader roots with a manifest.
6. Rewrite descriptions for discovery quality, aiming for 120-180 parsed characters.
7. Scrub publishable bundles for local usernames, absolute paths, hostnames, secrets, and project-specific references.
8. Verify active counts, duplicate count, parsed description length, and estimated savings.

Reference

Read 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.

Rules

• Prefer reversible moves over deletion.
• Preserve newest content when deduplicating; ties prefer <preferred-skill-root>.
• Keep SKILL.md bodies intact when the problem is metadata budget pressure.
• Treat current-thread warnings as possibly stale because skill metadata is loaded at session start.
• Keep manifests under a timestamped archive directory outside active loader roots, for example <archive-root>/<operation>-<timestamp>/manifest.json.
• For publishable skills, use placeholders such as <codex-home>, <agent-home>, <project-root>, and <archive-root> instead of machine-specific paths.

Useful Measurements

Measure both:

• parsed description chars and approximate tokens
• estimated registry chars including name, description, path, and formatting

Use len(description) / 4 as a rough tokenizer-independent estimate. Keep enough headroom for path length, plugin skills, and future additions.