How to Troubleshoot Skills Not Loading or Executing Correctly in Antigravity

Check that skills are installed in ~/.gemini/antigravity/skills or .agent/skills/, regenerate the data/skills_index.json manifest with npm run generate-index, and verify the skill isn't disabled in skills/.disabled/ using the skills_manager.py script.

Antigravity Awesome Skills are plain-text SKILL.md files stored in a dedicated skills directory. When a host tool like Claude Code or Gemini CLI references a skill with @skill-name, it loads only that single file to avoid context overflow. If a skill fails to appear, returns stale advice, or triggers a truncation error, the root cause usually lies in one of three layers: installation path errors, manifest synchronization issues, or host-side loading configuration. This guide covers the exact diagnostic steps and source files from the sickn33/antigravity-awesome-skills repository.

Verify the Installation Path

Most host tools look for the skill tree in specific locations. If the directory is elsewhere, the AI will report "skill not found" even when the files exist.

The default paths are:

• ~/.gemini/antigravity/skills — used by Claude Code and Gemini CLI
• .agent/skills/ — workspace-relative fallback

If you installed the repository elsewhere, move or symlink it to one of these locations, then restart your AI client. The installation requirements are documented in the repository root README.md under the installation section.

Check the Index Manifest

The host discovers available skills by reading data/skills_index.json, a lightweight manifest generated by tools/scripts/generate_index.py. If this file is stale or missing entries, the host cannot resolve skill references.

Inspect the manifest for your specific skill:

cat data/skills_index.json | jq '.skills[] | select(.id=="brainstorming")'

If the skill is absent, regenerate the index:

npm run generate-index

This command executes tools/scripts/generate_index.py, which writes the updated manifest to the repository root data/skills_index.json (lines 151–155 in the source).

Ensure the Skill Isn't Disabled

Skills can be toggled on or off using tools/scripts/skills_manager.py. Disabled skills are moved to skills/.disabled/ and will not appear in the index or host autocomplete.

List currently active skills:

python3 tools/scripts/skills_manager.py list

Check for hidden skills:

python3 tools/scripts/skills_manager.py disabled

If your target skill appears under Disabled Skills, enable it:

python3 tools/scripts/skills_manager.py enable brain-storming

The script uses resolve_skill_path to safely handle directory moves and prints clear status messages (lines 20–78 in skills_manager.py).

Fix Context Overflow and Windows Truncation Errors

When a host accidentally concatenates every SKILL.md into a single system prompt, the model's context overflows, causing a "TrajectoryChatConverter: could not convert a single message before hitting truncation" error on Windows.

Recovery steps from docs/users/windows-truncation-recovery.md:

1. Back up Antigravity profile folders (~/.gemini/antigravity-browser-profile/)
2. Delete corrupted browser storage (Local Storage, Session Storage, IndexedDB)
3. Clear the Windows temp directory (%TEMP%)
4. Restart Antigravity and reinstall only needed skills

A batch helper script is available at the end of the Windows truncation recovery guide for automated cleanup.

Configure the Host Loader

If you control the host configuration, set explicit limits to prevent silent skill dropping. The recommended settings from docs/integrations/jetski-cortex.md are:

loader:
  overflowBehavior: "error"   # fail fast instead of silently dropping data

  maxSkillsPerTurn: 5         # explicit limit to keep the prompt small

Setting overflowBehavior to "error" surfaces over-loading as a clear error rather than a silent truncation. The maxSkillsPerTurn limit ensures the host loads only the requested skill files, not the entire library.

Summary

• Installation: Ensure skills are in ~/.gemini/antigravity/skills or .agent/skills/
• Manifest: Regenerate data/skills_index.json with npm run generate-index after any manual changes
• Enablement: Use tools/scripts/skills_manager.py to verify skills aren't in skills/.disabled/
• Overflow: On Windows, follow the truncation recovery guide to clear corrupted storage and temp files
• Configuration: Set overflowBehavior: "error" and maxSkillsPerTurn: 5 in host loader configs

Frequently Asked Questions

Why does my AI say "skill not found" when the file exists?

The host reads data/skills_index.json to resolve skill IDs, not the filesystem directly. If you added a skill manually without regenerating the index, the entry is missing. Run npm run generate-index to update the manifest. Also verify the skill isn't disabled in skills/.disabled/ by running python3 tools/scripts/skills_manager.py list.

How do I recover from the Windows "TrajectoryChatConverter" truncation loop?

This occurs when the host loads too many skills at once, overflowing the context window. Follow the recovery checklist in docs/users/windows-truncation-recovery.md: back up profile folders, delete browser storage and IndexedDB, clear %TEMP%, and restart. Use the batch script provided in that guide to automate the cleanup.

Can I load multiple skills at once without hitting context limits?

Yes, but you must configure the host loader correctly. Set maxSkillsPerTurn to a modest number (5 or fewer) and overflowBehavior to "error" as shown in docs/integrations/jetski-cortex.md. This prevents the host from concatenating the entire skill library into one prompt, which would cause the model to drop content silently.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}