Refine

Overview

Refine a target Codex skill by turning evidence into minimal, validated in-place updates.

Inputs

• Target skill name or path

• Improvement signals (user feedback, session mining notes, errors, missing steps)

• Constraints (minimal diff, required tooling, validation requirements)

Example Prompts

• "Refine the docx skill to tighten triggers and regenerate agents/openai.yaml."

• "Add a small script to the pdf skill, then validate it."

• "Use session-mining notes to refine the gh skill's workflow."

Workflow (Double Diamond)

Discover

• Read the target skill's SKILL.md , agents/openai.yaml (if present), and any scripts/ , references/ , or assets/ .

• Collect evidence from usage: confusion points, missing steps, bad triggers, or stale metadata.

• If no example prompts are provided, synthesize 2-3 realistic prompts that should trigger the skill.

Define

• Write a one-line problem statement and 2-3 success criteria.

• Choose the smallest change set that addresses the evidence.

• Record explicit constraints (always run quick_validate, minimal diffs, required tooling).

Develop

• List candidate updates: frontmatter description, workflow steps, new resources, or metadata regeneration.

• Prefer minimal-incision improvements; only add resources when they are repeatedly reused or required for determinism.

Deliver

• Implement the chosen changes directly in the target skill; do not invoke $ms separately.

• Keep SKILL.md frontmatter compliant for the target skill (name/description only unless a system skill allows more).

• Regenerate agents/openai.yaml if stale or missing.

• If adding scripts, run a representative sample to confirm behavior.

Validation

Always run quick_validate on the target skill. Example command: uv run --with pyyaml -- python3 codex/skills/.system/skill-creator/scripts/quick_validate.py codex/skills/<skill-name> .

Output Checklist

• Updated SKILL.md with accurate triggers and clear workflow

• Updated or regenerated agents/openai.yaml when needed

• New or modified resources (scripts/references/assets) if justified

• Validation signal from quick_validate (and script runs if added)