1# Codex Skill Maintenance Process
2 
3Use this reference when a Codex setup reports skill metadata budget pressure or shows too many skill entries in the prompt.
4 
5## 1. Inventory
6 
7Identify active roots first. Common Codex roots:
8 
9- `<codex-home>/skills/.system`
10- `<codex-home>/skills`
11- `<agent-home>/skills`
12- `<project-skill-root>`
13- `<codex-home>/plugins/cache/*`
14 
15Count active `SKILL.md` files and parse frontmatter `name:` plus `description:`. Keep plugin cache and local skill roots separated in the report.
16 
17## 2. Diagnose Budget Pressure
18 
19Compute:
20 
21- number of active skill records
22- total parsed description chars
23- approximate description tokens: `chars / 4`
24- estimated registry chars: name + description + path + formatting
25- descriptions above the chosen cap
26- duplicate parsed names across active roots
27 
28If the warning appears in an already-open thread, tell the user the warning can reflect session-start metadata. Verify disk state anyway.
29 
30## 3. Rank Savings
31 
32Rank by reversible impact:
33 
341. Duplicate skill names across roots.
352. Thin wrapper skills whose target content is already installed locally.
363. Rare plugin bundles unrelated to current work.
374. Long descriptions that include paths, runbook details, model lists, or commands.
385. Low-frequency personal or device-specific skills.
39 
40Prefer local metadata rewrites before disabling core engineering skills.
41 
42## 4. Deduplicate
43 
44For duplicate parsed names:
45 
461. Compare `SKILL.md` modification time.
472. Keep the newest copy in the configured preferred active root, commonly the agent-managed skill root.
483. On exact ties, keep the configured preferred root.
494. Move superseded active directories into a timestamped archive.
505. Write a manifest with source path, archive path, reason, and chosen canonical path.
51 
52Handle 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.
53 
54Recommended manifest fields:
55 
56- `created_at_utc`
57- `operation`
58- `policy`
59- `actions[]`
60- `actions[].action`
61- `actions[].source`
62- `actions[].archive`
63- `actions[].reason`
64- `actions[].canonical_path`
65- `actions[].old_chars` and `actions[].new_chars` for metadata rewrites
66 
67## 5. Archive Noisy Skills
68 
69Move disabled skill directories out of loader-visible roots. Good archive pattern:
70 
71`<archive-root>/<operation>-<timestamp>/...`
72 
73Archive candidates:
74 
75- thin wrapper skills that only point to content already installed locally
76- plugin bundles unrelated to current work
77- old plugin versions that duplicate a current version
78- one-off workflow skills the user does not need globally
79 
80For 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.
81 
82## 5.5 Publication Hygiene
83 
84Before packaging or publishing a cleaned skill, scan the bundle for private or setup-specific content:
85 
86- local usernames and home paths
87- absolute filesystem paths
88- hostnames, IP addresses, domains, tokens, or account identifiers
89- project names that only make sense on the source machine
90- archive paths that reveal local cleanup history
91- machine-specific commands that should be placeholders
92 
93Use placeholders in publishable text:
94 
95- `<codex-home>`
96- `<agent-home>`
97- `<project-root>`
98- `<preferred-skill-root>`
99- `<archive-root>`
100- `<plugin-cache>`
101 
102Keep concrete paths only when they are part of the user's current local operation and the skill will stay private.
103 
104## 6. Rewrite Descriptions
105 
106Rewrite metadata for discovery. The full `SKILL.md` body can carry process details after the skill triggers.
107 
108Good description format:
109 
110`Use for <task/domain>. Triggers: <words or task shape>. Critical constraint: <only if needed>.`
111 
112Remove from descriptions:
113 
114- absolute paths unless required for triggering
115- long command sequences
116- model/provider catalogs
117- implementation steps
118- historical incidents
119- whole policy paragraphs
120 
121Recommended caps:
122 
123- 120-140 chars for simple or rare skills
124- 150-180 chars for important routing skills
125- avoid exceeding 180 chars unless the metadata is safety-critical
126 
127## 7. Verify
128 
129After changes, verify:
130 
131- active skill count
132- duplicate parsed names
133- active wrapper-skill count if those were archived
134- active disabled-plugin skill files
135- parsed description chars and approximate tokens
136- longest descriptions
137- frontmatter parse errors
138 
139Report before/after counts and the archive manifest path. Tell the user to start a fresh session to confirm prompt-time warnings disappear.
140