Cmd Skills Review

Skills Review

Audit one skill or all skills, get a second opinion from Codex, then apply only what you approve.

• [When to use](#when-to-use)
• [Instructions](#instructions)
• [Codex prompt](#codex-prompt)
• [Apply phase](#apply-phase)

When to use

• "review my skills" / "audit my skills" / "revisit my skills" / "clean up my skills"
• "review the cmd-foo skill" — single-skill mode
• Before publishing or sharing the skills repo
• When the skill catalog has grown and feels bloated

Instructions

0. Determine scope

If the user named a specific skill (e.g. "review cmd-pr-edgecase"), set TARGET=skills/cmd-pr-edgecase/SKILL.md. Otherwise, set TARGET=skills/cmd-*/SKILL.md (all personal skills).

1. Inventory

Read every SKILL.md in scope. For each skill, record:

| Field | What to capture | |---|---| | Name | name: from frontmatter | | Description length | word count (rough) | | Has trigger phrases | yes / no | | disable-model-invocation | true / false / missing | | Overlaps with | list any skills with similar purpose |

Print the inventory table before proceeding so the user can orient.

2. Claude's analysis

For each skill (or the single target), produce a proposal row:

| Field | Values | |---|---| | Issue type | verbose / weak-trigger / missing-trigger / redundant / rename / merge-candidate / looks-good | | Suggested fix | one concrete sentence — what to change and how | | Priority | 🔴 breaking / 🟡 worth fixing / 🟢 minor |

Flag pairs that substantially overlap and note which one should be canonical.

3. Codex review

Write the inventory + proposals to a tempfile, then invoke Codex for a second opinion:

PROPOSAL_FILE=$(mktemp -t skills-proposal.XXXXXX.md)
OUT_FILE=$(mktemp -t skills-codex.XXXXXX.md)

# Write proposal to tempfile using the Write tool, then:

codex exec \
  --sandbox read-only \
  --skip-git-repo-check \
  --color never \
  --output-last-message "$OUT_FILE" \
  "$(cat  — `
- "Apply all 🔴 items"
- "Apply all 🟡 items"
- "Skip everything"

Do not proceed until the user responds. If the user selects nothing, stop and confirm.

### 6. Apply approved changes

For each approved item, edit the relevant `SKILL.md` in `~/workspace/agent-skills/skills//`.

After all edits:

1. **Update `README.md`** — update the description in the skills table for any edited skill; remove the row for any deleted skill; add a row for any renamed skill.
2. **Update `~/.claude/CLAUDE.md`** — if the change affects how the skill is triggered or described, update the corresponding entry in the Custom Skills section.
3. **Update `agents/AGENTS.md`** — same as above; both files should stay in sync.
4. Run `make link-skills` from `~/workspace/agent-skills` to re-link any renamed or new skill directories.

Report a summary table of what was applied:

| Skill | Change applied | Files updated |
|---|---|---|
| cmd-pr-edgecase | Description trimmed | SKILL.md, README.md |

## Codex prompt

The exact prompt is embedded in [step 3](#3-codex-review). Key requirements when adapting:

- Feed Codex the inventory + proposals file — not raw SKILL.md content — so it reviews Claude's reasoning, not just the raw text.
- Demand per-item verdicts so synthesis is mechanical, not interpretive.
- Allow Codex to flag issues Claude missed; this is the main value of the second pass.
- Read-only sandbox — Codex must not edit files.

## Apply phase

- Only edit files for approved items. No silent scope creep.
- For merges or deletes, confirm once more with the user before destructive action (removing a SKILL.md directory).
- If `codex exec` errors with auth, tell the user to run `codex login` and stop.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Olshansk](https://github.com/Olshansk)
- **Source:** [Olshansk/agent-skills](https://github.com/Olshansk/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.