Codex Skill Maintenance Process

Use this reference when a Codex setup reports skill metadata budget pressure or shows too many skill entries in the prompt.

1. Inventory

Identify active roots first. Common Codex roots:

• <codex-home>/skills/.system
• <codex-home>/skills
• <agent-home>/skills
• <project-skill-root>
• <codex-home>/plugins/cache/*

Count active SKILL.md files and parse frontmatter name: plus description:. Keep plugin cache and local skill roots separated in the report.

2. Diagnose Budget Pressure

Compute:

• number of active skill records
• total parsed description chars
• approximate description tokens: chars / 4
• estimated registry chars: name + description + path + formatting
• descriptions above the chosen cap
• duplicate parsed names across active roots

If the warning appears in an already-open thread, tell the user the warning can reflect session-start metadata. Verify disk state anyway.

3. Rank Savings

Rank by reversible impact:

1. Duplicate skill names across roots.
2. Thin wrapper skills whose target content is already installed locally.
3. Rare plugin bundles unrelated to current work.
4. Long descriptions that include paths, runbook details, model lists, or commands.
5. Low-frequency personal or device-specific skills.

Prefer local metadata rewrites before disabling core engineering skills.

4. Deduplicate

For duplicate parsed names:

1. Compare SKILL.md modification time.
2. Keep the newest copy in the configured preferred active root, commonly the agent-managed skill root.
3. On exact ties, keep the configured preferred root.
4. Move superseded active directories into a timestamped archive.
5. Write a manifest with source path, archive path, reason, and chosen canonical path.

Handle same-root duplicate names explicitly. If a newer non-preferred-root variant owns the best content, archive both variants first, then copy the chosen content into <preferred-skill-root>/<name> and archive duplicates.

Recommended manifest fields:

• created_at_utc
• operation
• policy
• actions[]
• actions[].action
• actions[].source
• actions[].archive
• actions[].reason
• actions[].canonical_path
• actions[].old_chars and actions[].new_chars for metadata rewrites

5. Archive Noisy Skills

Move disabled skill directories out of loader-visible roots. Good archive pattern:

<archive-root>/<operation>-<timestamp>/...

Archive candidates:

• thin wrapper skills that only point to content already installed locally
• plugin bundles unrelated to current work
• old plugin versions that duplicate a current version
• one-off workflow skills the user does not need globally

For plugin caches, move only the specific skills/ directory or bundle subtree and leave a small marker file at the original parent explaining where the archive lives.

5.5 Publication Hygiene

Before packaging or publishing a cleaned skill, scan the bundle for private or setup-specific content:

• local usernames and home paths
• absolute filesystem paths
• hostnames, IP addresses, domains, tokens, or account identifiers
• project names that only make sense on the source machine
• archive paths that reveal local cleanup history
• machine-specific commands that should be placeholders

Use placeholders in publishable text:

• <codex-home>
• <agent-home>
• <project-root>
• <preferred-skill-root>
• <archive-root>
• <plugin-cache>

Keep concrete paths only when they are part of the user's current local operation and the skill will stay private.

6. Rewrite Descriptions

Rewrite metadata for discovery. The full SKILL.md body can carry process details after the skill triggers.

Good description format:

Use for <task/domain>. Triggers: <words or task shape>. Critical constraint: <only if needed>.

Remove from descriptions:

• absolute paths unless required for triggering
• long command sequences
• model/provider catalogs
• implementation steps
• historical incidents
• whole policy paragraphs

Recommended caps:

• 120-140 chars for simple or rare skills
• 150-180 chars for important routing skills
• avoid exceeding 180 chars unless the metadata is safety-critical

7. Verify

After changes, verify:

• active skill count
• duplicate parsed names
• active wrapper-skill count if those were archived
• active disabled-plugin skill files
• parsed description chars and approximate tokens
• longest descriptions
• frontmatter parse errors

Report before/after counts and the archive manifest path. Tell the user to start a fresh session to confirm prompt-time warnings disappear.