Treating Built-in Guide Skills as Design Assets, Not Throwaway Prompts

Antigravity v2.2.1 added built-in Guide skills. Here is a concrete structure and set of judgment calls for running them as version-controlled, shared design assets instead of one-off instructions.

Antigravity³⁷⁶ agents¹⁴³ skills⁴ design¹⁴ operations³³

✦ Premium Article

Do you ever feel like you keep explaining the same things to your agent? The directory conventions, the commit message style, the points you always check in review. If you paste those in at the start of every conversation, your time dissolves before you reach the work you actually wanted to do.

Antigravity v2.2.1 added built-in Guide skills, which let you freeze that repetition into a reusable skill. The question is whether you consume it as a one-time convenience or grow it into a place where your knowledge and your team's knowledge accumulate. That choice changes how much value you get six months from now.

As an indie developer, I run several blogs and apps in parallel under Dolice, so the background knowledge I feed agents grows without limit if I leave it unmanaged. Every time I wrote a Guide skill as a throwaway, I ended up rewriting near-identical content three or four times. Once I settled on an operating pattern, the agent's first moves stabilized and the re-explaining dropped noticeably. Here is that pattern.

A Guide skill moves knowledge outside the conversation

The point of a Guide skill is to lift the premises you used to carry in conversation context out into referenceable external knowledge. That behaves quite differently from writing the same thing directly into a prompt.

Aspect	Repeat in each prompt	As a Guide skill
Updates	Re-paste by hand each time	Fix one file, reflected everywhere
History	None, untraceable	Intent is traceable in Git diffs
Sharing	Stuck in personal notes	Reaches the whole team via the repo
Context cost	Burns tokens every time	Loaded only when needed

History is what helps most. If you record why a convention exists in the skill's change log, your future self avoids relitigating the same debate. For me, that single benefit justifies putting skills under Git.

Split into three layers so skills do not bloat

The common early mistake is cramming everything into one skill. When conventions, procedures, and troubleshooting all live in a single file, the agent cannot pick the relevant section by context, and accuracy actually drops.

I split skills into three layers by role.

Layer 1: Invariant premises (foundation)

The universal agreements of the project. Low change frequency, referenced by nearly every task.

.antigravity/guides/
├── foundation/
│   ├── repo-conventions.md      # directory and naming rules
│   ├── commit-style.md          # commit message shape
│   └── review-checklist.md      # mandatory review points

Layer 2: Per-task procedures (workflows)

The steps for recurring work, like "add one article" or "bump a dependency." Because these are procedures, I spell the steps out as a numbered list.

├── workflows/
│   ├── add-article.md           # adding an article
│   ├── dependency-bump.md       # bump and verify
│   └── release-checklist.md     # pre-release checks

Layer 3: Pitfalls and fixes (pitfalls)

Traps you have hit before, recorded as symptom-and-fix pairs. When the agent enters a similar situation, pointing it here stops it from repeating the failure.

└── pitfalls/
    ├── edge-cache-stale.md      # cache-driven inconsistency
    └── i18n-count-mismatch.md   # detecting JA/EN count drift

My rule of thumb is 200-400 lines per file. Past that, it is a sign the file mixes multiple concerns, so I consider splitting. Under 50 lines, I consider merging it into a related skill.

✦

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

✦A three-layer directory structure for Git-managed Guide skills you can grow over time

✦Why one bloated skill hurts accuracy, and the 200-400 line rule for splitting them

✦A small smoke-test script plus a monthly staleness check so skills never quietly rot

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 →

Design the inside of a single Guide skill

Giving the file's contents a shape too makes it easier for the agent to interpret. The structure I use has five parts: purpose, premises, steps, checks, and pitfalls.

# Add one article
 
## Purpose
Add a JA/EN paired article under content/ and push with counts matched.
 
## Premises
- Work on a clone under /tmp
- Treat the Japanese version as canonical; match English to it
 
## Steps
1. Confirm the slug does not collide with an existing one
2. Create both the ja and en .mdx files
3. Pass the quality gates
4. Confirm JA/EN counts match, then push
 
## Checks
- find shows equal ja and en counts
- Frontmatter premium / level match across JA and EN
 
## Pitfalls
- Forgetting en causes a 404 on language switch
- Bundling the gate and the push into one run hides failures

The key is always writing the checks and pitfalls. A steps-only skill stays a recipe, but adding checks and pitfalls gives the agent a basis for verifying its own output. I treat any skill without a checks section as unfinished and send it back before merge.

Measure whether a skill is working

To avoid writing and forgetting, measure the effect lightly. You do not need rigorous evaluation, just enough to notice regressions.

Fix a few representative tasks and record how the agent's first moves change before and after applying a skill. I run a minimal check like the following whenever I update a skill.

#!/usr/bin/env bash
# guide-skill-smoke.sh — quick regression check after a skill update
set -euo pipefail
 
GUIDE_DIR=".antigravity/guides"
fail=0
 
# 1. Every Guide file has required sections
for f in $(find "$GUIDE_DIR" -name '*.md'); do
  for section in "## Purpose" "## Checks"; do
    if ! grep -q "$section" "$f"; then
      echo "missing: $f has no $section"
      fail=1
    fi
  done
done
 
# 2. No file has bloated past the 400-line cap
for f in $(find "$GUIDE_DIR" -name '*.md'); do
  lines=$(wc -l < "$f")
  if [ "$lines" -gt 400 ]; then
    echo "bloat: $f is ${lines} lines (cap 400)"
    fail=1
  fi
done
 
[ "$fail" -eq 0 ] && echo "✅ Guide skills healthy" || { echo "❌ needs fixing"; exit 1; }

Even a check this small catches skills that forgot their checks section and skills that quietly ballooned. In my setup, this script is wired into the article-adding procedure and runs before every push.

Detect staleness monthly

The greatest enemy of a Guide skill is going out of date. When a tool version moves up and a convention changes but the skill stays in the past, it steers the agent the wrong way. Failing silently is arguably worse than writing nothing at all.

Once a month, I surface skills with old last-modified dates.

# list Guides untouched for 60+ days
find .antigravity/guides -name '*.md' -mtime +60 \
  -exec echo "review: {}" \;

Anything on that list gets a "still correct?" pass that same month. If it holds, I just refresh the date; if it has drifted, I fix it or delete it when it has served its purpose. Keeping skills trustworthy matters more than accumulating them, at least for long-term operation.

Where to start

You do not have to organize everything at once. Carve out the single explanation you repeat most into one Guide skill first. For me, the first one was "the article-adding procedure." Once you feel that working, expanding into foundation and pitfalls settles in without strain.

A skill is not finished the moment you write it; it is something you trim while using, add checks to, and fix as it ages. In running Dolice Labs, the skills that have helped most were the handful I revised again and again. I hope you find your own handful that keeps paying off.

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.