Detecting and Fixing Drift Between a Guide Skill and Your Code

Pin a procedure into a built-in Guide skill and it gets left behind when the code later changes. Here is an operational design that machine-checks the things a Guide references, catches drift early, and keeps the Guide thin.

Antigravity²⁹⁷ Guide skill agents¹¹³ drift design¹⁴

✦ Premium Article

Since the built-in Guide skill landed in Antigravity at the end of June, I've been folding more of my repetitive work into Guides: the push procedure for my blogs, the article verification steps, the pre-release checklist. Write the steps once and you can hand them straight to a dynamic sub-agent, and the chore of re-explaining every time disappears.

A few weeks later, though, one Guide was steering an agent to a script path that no longer existed. I had tidied files on the repository side, but the Guide's steps were left behind, still old. No error surfaced. The agent tried to follow the instructions faithfully and quietly whiffed in front of a target that wasn't there.

That silent drift is the weak point of any mechanism that pins a procedure. This article lays out a design for catching drift between a Guide and code early and keeping the Guide thin, together with the verification shape I use across my own indie apps and Dolice blogs.

Why a Guide skill drifts quietly

A Guide skill is a procedure captured from the code and operations at one point in time. Accurate the moment it's captured, but the code keeps moving. Files relocate, command options change, and the behaviors it assumed get updated.

The problem is that there is no connection between the Guide and the code. Fix the code and the Guide knows nothing. When the Guide goes stale, the drift stays hidden until someone actually runs the procedure end to end. And because agents are faithful to instructions, they dutifully try to execute even a stale procedure, ending not in failure but in a whiff, the hardest outcome to notice.

The three layers where drift happens

When I review a Guide, I first sort out which layer the drift is in, because each layer is detectable to a different degree.

Layer	Example of drift	Ease of detection
Path	A referenced file or script was moved or deleted	Easy to catch mechanically by existence checks
Steps	A command's options or order changed	Only clear on execution. Medium
Assumptions	An implicit premise like "this step is idempotent" broke	Needs a human to read. Hard

Of these, the path layer can be all but automatically cleared with existence checks. I assign the steps layer to runtime checks and the assumptions layer to a design that keeps the Guide thin. Hardening the most tractable path layer first with a mechanism gave the best return.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦How to separate the three layers where a Guide skill silently drifts: paths, steps, and assumptions

✦A ~35-line verification script that checks the entities a Guide references (files, commands, scripts) still exist

✦Rules for keeping code as the source of truth and the Guide thin, plus wiring the check into pre-push

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Detecting drift — check that referenced entities exist

The idea is simple. Extract the file paths, invoked scripts, and referenced commands written into the Guide, and confirm they exist in the repository as it stands now. If they don't, that Guide has drifted at the path layer.

Extract path-like strings from the Guide's body
Relative to the repository root, confirm each entity exists
List the ones that don't as drift candidates
Run this check right before push and stop if there is drift

The important part is handing this to a mechanism rather than the human eye. Eyeballing misses things as Guides multiply. Because I keep several Guides per blog, a manual inventory broke down immediately.

Finding it in code

Here is a minimal script that runs the path-layer check. It picks up slash-containing tokens from the Guide and confirms they exist in the repository. Tune the extraction precision to your setup.

#!/usr/bin/env python3
# Check that reference paths inside a Guide skill still exist
import re
import sys
from pathlib import Path
 
repo = Path(sys.argv[1]).resolve()      # repository root
guide = Path(sys.argv[2])                # the target Guide file
text = guide.read_text(encoding="utf-8")
 
# pull path-like tokens from code blocks and inline code
candidates = set()
for m in re.finditer(r"`([^`\n]+)`", text):
    token = m.group(1).strip()
    # only things that look like relative paths, scripts, or config files
    if re.search(r"[\w./-]+\.(?:py|mjs|sh|ts|json|mdx)$", token) or token.startswith("./"):
        candidates.add(token.lstrip("./"))
 
missing = []
for c in candidates:
    # drop queries and args, keep the leading path part
    path_part = c.split()[0]
    if not (repo / path_part).exists():
        missing.append(path_part)
 
if missing:
    print(f"drift in {guide.name}: {len(missing)} reference(s) not found")
    for x in sorted(missing):
        print(f"   - {x}")
    sys.exit(1)
 
print(f"{guide.name}: all references exist")

Running it across my own Guides surfaced a handful of references to scripts I had moved during cleanup. None of them errored; they were the kind you only notice as a whiff once you run them. Inserting the check once let me kill that whiff before push.

How to fix it — code as truth, Guide thin

Once you find drift you fix it, but there's a policy to the fix: don't make the Guide the single source of truth.

The more you write full step sequences and paths into the Guide, the larger the surface that drifts when the code changes. I lean the other way: put the entities on the code side, and let the Guide only call them.

Approach	Drift surface	Fix effort
Write every step into the Guide (thick)	Wide. Drifts on every code change	Fix the Guide each time. Double bookkeeping
Entities in a script, Guide just calls it (thin)	Narrow. Only the callee's name	Fix the script and you're done. Centralized

A thick Guide is helpful right after you write it but becomes a liability as time passes. A thin Guide looks curt at first, but because it keeps code as the truth, fixing the code keeps the Guide correct on its own. This thin shape is what I recommend.

Wiring it into operations

Running the detection script whenever you happen to remember it is pointless. I fold this check in as one stage of the quality checks right before push.

Before push, run the check against the Guides you changed
Stop the push if even one drift shows, and either thin the Guide or fix the reference
Periodically run a batch check across all Guides to catch drift in ones you haven't touched

With this in place, a Guide that went stale as a side effect of tidying code automatically surfaces at the next push. The aim is to lift drift up to where a human notices it, before an agent whiffs on it.

Your next step

If you've started multiplying Guide skills, pick just one at hand and check whether its path references still exist. You'll probably find one or two that quietly drifted. From there, fix it toward thinning the Guide and leaning on code as the truth, and the next time you tidy the repository, the Guide will stay correct without troubling you.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.