Guide · Agent skill
How to use the Refit agent skill: environment retrospective guide
Updated · written with AI from the project's own documentation and checked against our catalogue data
Refit is an agent skill for Claude-based coding setups that looks back at the working environment an agent used, rather than the code it wrote. It reads Oh My ClaudeCode (OMC) instrumentation such as trace timelines, friction reports, logs and plan notepads, then proposes changes to the place that should own each fix. This guide explains what the skill does, how to install it, how to trigger it, and what to check before approving anything.
Refit: Environment RetrospectiveYeachan-Heo/oh-my-claudecode · MIT Download the skill Quick start
- 1Download and unzip. Download the refit ZIP from this page and unzip it into ~/.claude/skills/ or the project's .claude/skills/ folder.
- 2Confirm OMC is in place. Make sure Oh My ClaudeCode is installed on the repo and that its trace, friction report and logs instruments have session history to read.
- 3Ask for a retrospective. In a session on the repo, ask for an environment retrospective of recurring friction, focusing on the environment rather than the code.
- 4Read the ranked findings. Review each finding with its surface, intended change and the one line of instrument evidence behind it.
- 5Approve or veto each line. Approve the findings you want applied and veto the rest. Nothing is written before you decide.
- 6Verify new checks. For any new deterministic check, confirm it passes on a clean run and fails on a deliberate violation before accepting it as landed.
What the refit skill makes the agent do
Refit surveys the environment the agent worked in. It does not review the code the agent produced, and it does not summarise the lessons of a single launch run. It reads the instruments OMC already records, looks for recurring friction such as a check that kept failing, a run that stalled, or a debugging output that was never captured, and turns those into proposed environment changes.
Each finding is assigned to one of four surfaces: a deterministic check (lint rule, hook or CI job), a steering surface (docs in docs/standards/ or CLAUDE.md/AGENTS.md), a tool surface (.mcp.json, scripts/, hooks or OMC config), or an information surface (exposing logs, service state or documented access paths). A finding that fits none of these is declined, with a stated reason.
Install the refit skill
Download the refit ZIP from this page. You can install it in one of two ways.
For a personal install across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: unzip into ~/.claude/skills/
- Single project: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
Check the requirements before you run it
Refit depends on Oh My ClaudeCode (OMC) being installed, with its trace, friction report and logs instruments available. Without OMC session history there is nothing to read, and the result will be empty.
Refit also calls the agent-doc-discipline skill when it writes steering prose, and it can use a configured notification channel (configure-notifications) for headless summaries. The notification channel is optional.
- Required: Oh My ClaudeCode (OMC) with trace, friction report and logs instruments
- Required: the agent-doc-discipline skill
- Optional: a configured notification channel (configure-notifications) for headless summaries
Trigger refit with a natural request
Refit is user-invoked, so you ask for it directly in the session. The skill begins by reading OMC's instruments before it asks you anything. Phrase the request around the environment rather than the code, for example asking for a retrospective of recurring friction on the repo.
Expect the skill to read trace timelines and summaries, the session friction report, .omc/logs/, and any plan notepads in .omc/notepads/. It also reads the repo's package.json scripts and CI workflows before proposing new checks.
- Ask for a retrospective of recurring friction in this repo's OMC sessions
- Ask which checks are wired up in CI and whether any are silently broken
- Ask what the last plan's problems.md suggests should change in the environment
Review and approve the proposals
Refit presents findings ranked by severity, each as finding, surface and intended change, with one line of instrument evidence. It then stops and waits for your approval. Each line can be approved or vetoed on its own.
When you approve a finding, refit writes it to the matching surface. A newly installed deterministic check must be shown to fail on a deliberate violation before it counts as landed. Afterwards, refit records the file location where each finding landed, so the next refit starts from that record.
- Approve or veto each line individually
- New checks must run clean, fail on a deliberate violation, then have that violation reverted
- Landed findings are recorded one file location per line
Run refit unattended and review the output
A scheduler such as cron or a CI timer can start a headless session that runs refit. In that mode refit writes proposals only, to .omc/refit/pending-proposals.md, and does not change any surface. If a notification channel is configured, it sends a summary so you know a survey is waiting.
Read the pending proposals before approving anything. The next interactive refit starts from that pending list instead of running the survey again. If the survey found nothing, the output says so.
- Output file: .omc/refit/pending-proposals.md
- Nothing lands without your approval, even in headless mode
What people use it for
- Reducing a recurring lint or hook failure by turning it into a deterministic check that fires before the agent gets stuck
- Auditing the repo's CI and lint setup against problems recorded in real OMC sessions
- Moving repeated style corrections into the matching docs/standards/ file, rather than loading more instructions onto the implementer
- Making a dev-server log or service state visible to the agent when it kept guessing at a missing signal
- Running scheduled headless surveys that leave a pending proposal list for review
Frequently asked questions
Is the refit agent skill free?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms before you reuse or redistribute it.
What do I need before I can use refit?
You need Oh My ClaudeCode (OMC) installed with its trace, friction report and logs instruments, plus the agent-doc-discipline skill. A configured notification channel is optional and only used for headless summaries.
Where do I install the refit skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repo. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does refit change my code or config without asking?
No. Refit proposes findings and waits for your approval, and each line can be approved or vetoed separately. In headless mode it only writes a proposal file to .omc/refit/pending-proposals.md.
Does refit review the code the agent wrote?
No. Refit looks at the environment, not the code. The skill states that code review and verification are handled by the review and verify skills.
What happens if refit finds no problems?
It says so plainly, for example 'no findings', and does not invent issues. A repo with no OMC session history will also produce an empty result, because there are no instruments to read.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Refit suits developers and teams who already use Oh My ClaudeCode on a repo and want recurring agent friction turned into checks, docs, tooling or information fixes over time. It is not a code reviewer and will return nothing useful without OMC session history. Because it runs scripts and can be scheduled unattended, read its proposals before approving any of them.
Download the skill