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.