# Refine > Refine an existing Codex skill in place with minimal diffs, then validate with quick_validate. Trigger when asked to improve a skill's trigger description/frontmatter, workflow text, metadata, scripts/references/assets, or agents/openai.yaml; also for requests to iterate, refactor, rename, or fix a skill using usage/session-mining evidence (for example from $seq). Use when this capability is needed. - Skill: `tomevault-io/refine-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/refine-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/refine-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/refine-2 --- # 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/`. ## 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) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/tkersey) — claim your Tome and manage your conversions.