How to use the Refocusing agent skill: setup and examples

What the Refocusing skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a particular kind of task. The refocusing skill is for the moment when a long session may have drifted. It tells the agent to re-check the outcome the person actually wants, not just the task it is currently doing.

To do this, the agent reads the current project structure and work trace, then reads the full source notes it needs before acting. The skill runs a bundled Python script, scripts/trace-to-root.py, which walks up the topology and work directory paths to gather that context. The skill also includes a short reference, references/refocus.md, with three questions: what the person is trying to get, whether the next action moves that, and what has been concluded without opening the relevant file or running the thing.

Install the Refocusing skill

Download the ZIP for the skill from this page. You can then install it in one of two ways.

For Claude Code, unzip the folder into your global skills directory at ~/.claude/skills/, or into a project's .claude/skills/ directory to limit it to one project.

In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Global install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

The skill is invoked as refocusing, its frontmatter name. You do not need to type that exact word every time. The skill's description says it applies when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action.

Plain requests that match those situations work well. Ask the agent to check that it is still working toward the right outcome, or to re-ground itself after a long session.

• "Check that you still understand what the user actually needs before you continue."
• "Context was just compacted. Refocus on the product goal before the next change."
• "We've finished the design phase. Trace the current work and confirm the next step serves the outcome."

Run the trace script safely

When the agent needs a new trace, it resolves the absolute path to the bundled script and runs it as one plain command from its current working directory. It does not change into the skill directory, because that can change the work node the trace infers.

The script accepts --trees with topology, work or both, and --depth with light or full. Light work traces include intent and note names. Full traces include the complete node and note bodies. The script finds topology.root and workspace.root with rig config get.

• Requires Python 3 and the OpenRig CLI (the rig command) with its daemon running.
• Uses no network access, according to the skill's listing.
• Runs a local script, so it is unsuitable where running local Python scripts is restricted.

Know what the skill does not cover

The skill is not a restart, a wake-up, or a phase checkpoint. It is not for orienting a fresh session or waking an idle agent seat. Use it when a long session is drifting or when a managed restore needs current context.

During a managed restore, the agent should use the trace that arrived with the request rather than rerunning the script. A packet pointer, compact summary or truncated extract does not count as a full source read, so the agent should read the required notes with its file-read tool.

Tips for getting good results

Use the skill in OpenRig rigs where agents are working on a goal over many steps. If you know which work node or topology node is current, the skill can pass it in with --work-start or --topology-start, using its literal absolute path. Do not substitute the project root for a mission or slice node.

If the trace reports a missing chain file, treat that as evidence of a gap and say so. The skill does not follow pointers to invent a second parent.

• Pass a known current node with --work-start or --topology-start.
• Read full source notes when the next action depends on them.
• Report any missing context instead of guessing.