The Day My Own Skill Stopped Firing — When the Built-in Guide Skill Collides With Yours
Since the built-in Guide skill arrived, custom skills started getting skipped or double-fired. Here is how to observe which skill is chosen, and how to settle the conflict through descriptions and naming.
One morning, a custom skill I rely on simply did not fire. The prompt was the same as always. The only difference was the built-in Guide skill that had landed the day before. The agent leaned on the Guide skill's description and returned generic guidance instead of the steps I had prepared.
When you run several apps and sites in parallel as an indie developer, skills are the foundation that pins your own procedures in place. And that foundation can shift quietly when a built-in skill is added. Left alone, this slides into the most draining workaround of all: rephrasing the prompt every time to dodge the wrong skill.
Here is how I replaced guessing with observation, and settled the conflict through descriptions and naming.
Skills Are Chosen by Keywords in the Description
Antigravity selects a skill using the description placed at the top of SKILL.md. It matches your request against each skill's description and fires the closest one. In other words, the description — not the skill name — holds the steering wheel.
The built-in Guide skill has a deliberately broad description. Because it leans on general phrases like "guide you through" and "show how to proceed," its vocabulary overlaps easily with custom descriptions. The moment they overlap, which one wins stops being stable.
The first thing to do is to avoid deciding, by assumption, whether a conflict even exists.
First, Observe Why a Skill Was Chosen
Before fixing anything, nail down what is actually happening. The procedure is this.
Run the same request once with explicit invocation (name the skill directly with /) to confirm the custom skill itself still works.
Then ask in natural language only, without naming the skill, and check which skill fired from the opening line of the response.
If the wrong skill fired, place your custom description next to the built-in one and eyeball which words overlap.
Move the overlapping words one at a time, in either the request or the description, and reproduce how the firing changes.
What matters is not rewriting the description on a hunch. Move one word at a time and actually see the boundary before you fix it. Fix it without seeing the boundary, and a different request will trigger the opposite collision — an endless back-and-forth.
In my own case, a request that had been firing a different skill every time converged on the same custom skill three runs in a row after I added a single line of trigger words. When I instead moved two words at once without watching the boundary, the built-in stepped forward again on a different request, and it cost two extra round trips to fix. Observe first, then move one word at a time — that is the fastest repair in the end.
Observed symptom
Likely cause
First thing to try
Custom skill never fires
The built-in description sits closer to the request
Add a unique trigger phrase to your description
Two fire and the response blends
The descriptions share nearly identical vocabulary
Narrow one skill's scope in its description
A different skill each time
Both match weakly
Make explicit invocation the default
Guide appears unintentionally
The request asks "how to proceed"
Phrase the request as verb + object, imperative
✦
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 procedure to observe why a skill was chosen, instead of guessing and patching
✦How to write a description that does not collide with the built-in, plus a naming discipline
✦How to decide when to deliberately disable or override the built-in Guide skill
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.
The single most effective move to reduce collisions is to write your custom description with words that do not overlap the built-in. General verbs — guide, explain, walk through — will always compete with the built-in. Use nouns specific to your own workflow and a concrete object instead.
Here is a collision-prone description.
---name: release-checklistdescription: Guides you through a release. Shows the steps in order.---
This shares almost the same vocabulary as the Guide skill's "guide you through the steps," so it competes. Pulled toward unique words, it becomes this.
---name: release-checklistdescription: | Runs the pre-submission store check for iOS/Android apps. Use when verifying, in this order, version numbers, screenshot diffs, dSYM attachment, and JA/EN release-note consistency. Triggers: pre-submission store check, pre-release verification, submission checklist---
Three points matter. First, narrow the scope with specific nouns (store submission, dSYM, JA/EN consistency). Second, state when to use it with an explicit condition. Third, add a line of explicit trigger phrases. The narrower and more concrete the description, the more reliably it beats the built-in's broad one.
Name Skills as Verb + Object
The skill name itself is also a cue. General names like helper or assistant match every request weakly, so they become neither a reason to be chosen nor a reason to be skipped. Use names where the verb or object is obvious at a glance, such as release-checklist or admob-fill-rate-diagnosis. For a custom skill that diagnoses AdMob fill rate, putting the unique phrase "AdMob fill rate" in both the name and the description keeps the built-in generic guidance from pulling it away.
I settled on prefixing custom skill names with a project-specific tag. For a verification skill shared across several apps, I fold the target into the name. When the scope is clear from the name alone, the person writing the request naturally reaches for phrasing that fires it.
Deciding Whether to Override or Disable the Built-in
Unique words and naming resolve most of it, but cases remain where the built-in Guide skill still steps forward. Here you decide whether to disable the built-in or override it with your own.
There is only one axis: can the request be handled well enough by the built-in's generic guidance? If yes, do not force an override. Only for requests whose quality breaks without your own steps should you make explicit invocation the default, or disable the built-in within that workspace. Override everything, and you throw away the benefit of the built-in improving over time.
Scope disabling to the workspace level to stay safe. Cut it globally and you sweep up the projects where you would happily use it. Holding skills as two sets — "things to share" and "things to apply only in this repo" — makes the conflict far easier to manage.
Keep a Record of What Fired
Finally, keep a light record of which skill fired for which request. If the opening line of the response names the fired skill, transcribing that into your work log is enough.
After a few days accumulate, the pattern of collisions becomes visible. Once you know the reproducible condition — "this phrasing always brings up Guide" — you can fix the description or your own phrasing habits based on observation rather than guesswork. Treat skill traffic control not as a one-time setting but as something you revisit each time the built-ins update, and the quiet drift stops pushing you around.
As a next step, pick one custom skill you currently rely on and add a single line of unique trigger words to its description. Starting with the skill most prone to collision is the most rewarding place to begin.
Share
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.