freeze

Overview of freeze skill

What freeze does

freeze is a guardrail skill that restricts file edits to one directory for the session. It blocks Edit and Write outside the allowed path, so it is useful when you want a workflow automation agent to stay inside a module, a feature folder, or a debugging sandbox. If you need the freeze skill to prevent accidental wide-ranging changes, this is the right fit.

Who should install it

Install freeze if you regularly ask an agent to debug, refactor, or patch code in a narrow scope and you do not want it to “helpfully” touch unrelated files. It is most valuable for maintainers, reviewers, and anyone working in a mixed or risky codebase where edit boundaries matter more than broad autonomy.

Why it is different

The main differentiator is enforcement, not guidance. freeze uses a pre-tool hook to deny edits outside the chosen directory, which is stronger than a prompt that merely asks the model to stay focused. That makes the freeze guide practical for real containment, especially in sessions where accidental drift would be expensive.

How to Use freeze skill

Install and initialize the boundary

For freeze install, add the skill to your environment with the repository’s skill manager, then choose the directory you want to lock down. The skill’s setup flow is interactive because the allowed path is session-specific. In practice, you should be ready to answer: “Which directory should be frozen?” with a precise path, not a vague area like “the backend.”

Read these files first

Start with SKILL.md to understand the control flow, then inspect bin/check-freeze.sh to see how the boundary is enforced. If you are adapting the skill, also review SKILL.md.tmpl to understand the generated structure. These files tell you what the freeze usage actually permits, what gets blocked, and where path parsing can fail or be lenient.

Give the skill a precise prompt

The best input is a focused task plus a clear boundary. For example: “Freeze edits to apps/payments and fix the failing unit tests there without changing shared libraries.” That is better than “debug this app,” because freeze needs a directory target and a task that fits inside it. The more exact the scope, the less likely the agent will ask for exceptions.

Practical workflow tips

Use freeze when the first pass should be surgical: locate the bug, patch within one folder, and verify without expanding scope. If the task truly requires cross-directory changes, do not force it into freeze; either widen the allowed path or use a different workflow. The skill works best when the requested change set is naturally bounded and the repository layout is clear.

freeze skill FAQ

Is freeze only for debugging?

No. Debugging is a common use, but the freeze skill also helps with constrained refactors, feature isolation, and review-safe edits. The key question is whether you want the agent to stay inside one directory while it works.

How is this different from a normal prompt?

A normal prompt depends on the model following instructions. freeze adds enforcement through hooks, so out-of-bound edits are blocked even if the model tries them. That makes it more reliable for Workflow Automation jobs where guardrails matter.

Is freeze beginner-friendly?

Yes, if the user can name a directory confidently. The main beginner mistake is choosing a boundary that is too broad or too narrow. If the directory is ambiguous, the session may stall while you clarify scope.

When should I not use freeze?

Do not use it when the task is expected to span multiple modules, shared configs, or repo-wide formatting. In those cases, the restriction can slow the work or cause unnecessary blocked actions. Freeze is best when the boundary is a real decision, not just a preference.

How to Improve freeze skill

Make the boundary explicit

The biggest quality gain comes from naming the exact directory and the intended outcome together. Good input looks like: “Freeze edits to services/auth and update the token refresh flow without touching shared/.” Weak input like “fix auth” forces guesses and increases the chance of blocked or incomplete edits.

Provide files, symptoms, and limits

For better freeze usage, include the failing file, the observed behavior, and any files that are off-limits. Example: “Only edit apps/admin; the bug is in src/table.ts; do not change API contracts.” This helps the agent stay inside the frozen zone while still solving the real problem.

Watch for boundary mismatch

The most common failure mode is a task that secretly needs a wider scope than the frozen directory allows. If the agent keeps hitting denied writes, the fix is usually to expand the boundary or split the task into stages. That is a feature, not a bug: freeze is telling you the plan and the scope do not match.

Iterate after the first pass

After the first output, inspect whether the solution relied on assumptions outside the frozen path. If it did, tighten the prompt by adding one or two concrete constraints: target directory, allowed file types, and what must remain untouched. For the best freeze skill results, iterate by clarifying scope, not by asking for more creativity.