refine_skill

Overview

This skill refines an existing Codex skill by translating usage evidence into minimal, validated updates. It focuses on tightening triggers, correcting workflow text, and updating metadata, scripts, and runtime configuration. The goal is small, auditable diffs that fix real-world failures and improve signal reliability.

How this skill works

It inspects the target skill’s frontmatter, workflow text, referenced scripts, assets, and agent configuration, then synthesizes concise problem statements and small change sets. Changes are applied with a minimal-diff mindset and validated automatically using a quick validation script. If configuration or scripts are stale or missing, it regenerates or adds only the smallest required resources and runs representative checks.

When to use it

• Improve or tighten trigger descriptions and frontmatter
• Iterate or refactor a skill based on usage/session-mining evidence
• Fix broken workflows, missing steps, or metadata errors
• Add a tiny helper script required for deterministic behavior
• Regenerate or repair agent runtime configuration files when stale

Best practices

• Collect concrete evidence: user feedback, session logs, error traces, or failing examples before changing the skill
• Define a one-line problem statement and 2–3 success criteria up front
• Prefer the smallest change set that addresses the evidence; avoid large rewrites
• Always run the quick validation step after changes and run any added scripts on a sample input
• Document the intent and validation result in the change commit message

Example use cases

• Tighten triggers for a document-processing skill after users report false positives
• Use session-mining notes to remove a confusing workflow step and add a brief clarifying sentence
• Add a small conversion script to a PDF skill, then run a sample conversion and validate
• Regenerate the agent runtime config when prompts or model settings become inconsistent with current usage
• Rename a workflow step and update references to avoid a mismatch between docs and code