Maintain, disable and evaluate skills

Understand the approach

Treat a skill as maintained project material. Its description affects selection; its instructions affect execution; its supporting files can change the result. Record the version or commit used in an evaluation so a future comparison is meaningful. A passing case from last week cannot certify today's changed procedure. Keep a small collection of representative requests rather than rebuilding an elaborate evaluation system before there is a real workflow to protect.

Codex discovers local skills in documented repository and user locations, and it detects skill changes automatically. If an update is not visible, inspect the actual path and refresh or restart as documented. Duplicate names are not merged; both can appear in selectors. That makes precise naming and source inspection important when a personal and project package look alike. Do not apply the source guide's Claude-specific precedence rules or reload commands to Codex without verification.

Disabling a skill and deleting its files are different operations. The documented skills.config setting can disable a package by path without discarding it, and distribution as a plugin has its own update process. Choose the smallest maintenance action that solves the observed problem. For the lab, update readme-evidence-review in the practice repository, retain a before-and-after record, and leave personal or organization settings unchanged unless you separately choose to configure them.

The five native-setup checks copy every support file, reject an existing destination, place the explicit-only policy correctly, repair a copied README from two findings to none, and preserve the original fixture. They do not run a model. For an instruction change, keep these factual regressions and repeat the actual selection matrix from the prepared project. Disable a local skill only by its resolved SKILL.md path if that is the intended operation; the documented personal setting takes effect after restarting Codex. A discovery problem is not a reason to delete the package or overwrite user configuration.

Practice and acceptance

Maintain selection and factual-output regressions independently; a version change must be judged against fixed cases.

Try it step by step

1. Read the linked lab guide, inputs and expected outputs before running the exercise.
2. Create an evaluation table with direct, indirect, missing-input and unrelated requests, expected behavior, actual behavior and the skill version.
3. Run the cases independently on fixed practice inputs. Record activation and supported output findings in separate columns.
4. Revise the description for a selection failure or the procedure for an execution failure. Change one relevant layer at a time.
5. Rerun the failing case and nearby cases, then inspect the project diff to confirm that no unrelated package was changed.
6. If disabling is appropriate, review the documented configuration example as an option. Verify the actual resolved path before applying it in a chosen environment.

A useful starting example

Illustration · adapt before use.

| Case | Expected | Observed | Skill version |
| --- | --- | --- | --- |
| Direct README review | Evidence-backed gaps | Record actual result | Record commit/date |
| Paraphrased readiness question | Appropriate activation | Record actual result | Same version |
| Missing README | Report missing input | Record actual result | Same version |
| Change button color | Do not use readme-evidence-review | Record actual result | Same version |

[[skills.config]]
path = "/your/reviewed/project/.agents/skills/readme-evidence-review/SKILL.md"
enabled = false
# Instructional personal-config fragment; choose the real path and restart deliberately.

Check your result

• The evaluation record identifies the skill source and version used for each result.
• Missing inputs and unrelated requests are covered alongside successful invocation.
• You can explain the difference between refreshing discovery, disabling a skill and removing its files.
• Helper results, actual host activation and unexecuted application commands remain distinguishable.

Common mistakes

• Declaring success because a package appears in a list or one friendly example works.
• Changing several similarly named skills and personal configuration while debugging a single project package.