Troubleshooting

Common Installation Issues

`npx antigravity-awesome-skills` returns 404

If the npm package lookup fails, use the GitHub package fallback:

npx github:sickn33/antigravity-awesome-skills

This directly references the GitHub repository and bypasses npm registry issues.

This is the recommended fallback if you encounter any npm-related errors.

Windows Clone Issues (Symlinks)

Windows Users: This repository uses symlinks for official skills. Windows requires special configuration to handle symlinks properly.

Why This Happens

The repository includes symlinked files in the skills/official/ directory. Windows treats symlinks differently than Unix-based systems and may fail to create them without proper permissions.

Solution 1: Enable Developer Mode (Recommended)

Open Windows Settings

Press Win + I to open Settings

Navigate to Developer Settings

Go to Update & Security → For developers

Enable Developer Mode

Toggle Developer Mode to ON

Clone the repository

git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills

Solution 2: Git Clone with Symlinks Flag

If you can’t enable Developer Mode, run Git as Administrator and use the symlinks flag:

# Run this in an Administrator Command Prompt or PowerShell
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills

What does -c core.symlinks=true do?

This flag tells Git to create actual symlinks on Windows instead of copying the files. Without this flag, Git may:

Create text files containing the symlink path instead of actual links
Fail to properly link the official skills
Cause “file not found” errors when trying to use official skills

Skills Installed But Not Detected

If your AI assistant doesn’t recognize skills after installation, the path is likely incorrect.

Check Your Installation Path

Different tools expect skills in different locations:

# Antigravity global (default)
~/.gemini/antigravity/skills/

# Antigravity workspace
.agent/skills/

# Claude Code
.claude/skills/

# Gemini CLI
.gemini/skills/

# Cursor
.cursor/skills/

# OpenCode
.agents/skills/

Solution: Reinstall to Correct Path

Use the tool-specific installer flag:

# Antigravity (explicit)
npx antigravity-awesome-skills --antigravity

# Claude Code
npx antigravity-awesome-skills --claude

# Gemini CLI
npx antigravity-awesome-skills --gemini

# Cursor
npx antigravity-awesome-skills --cursor

# Kiro CLI/IDE
npx antigravity-awesome-skills --kiro

# Custom path
npx antigravity-awesome-skills --path .agents/skills  # OpenCode

Verify Installation

Antigravity
Claude Code
Cursor
OpenCode

# Global installation
test -d ~/.gemini/antigravity/skills && echo "Skills installed in ~/.gemini/antigravity/skills"

# Workspace installation
test -d .agent/skills && echo "Skills installed in .agent/skills"

test -d .claude/skills && echo "Skills installed in .claude/skills"

test -d .cursor/skills && echo "Skills installed in .cursor/skills"

test -d .agents/skills && echo "Skills installed in .agents/skills"

Update Issues

Update an Existing Installation

Manual Update

If you installed via git clone, navigate to the installation directory and pull:

cd ~/.gemini/antigravity/skills  # or your installation path
git pull origin main

NPX Auto-Update

If you installed via npx, simply run the installer again:

npx antigravity-awesome-skills

The installer automatically runs git pull if the directory already exists.

Web App Auto-Update

Good news! You no longer need to manually run git pull or npx antigravity-awesome-skills to update your skills.

Windows: Double-click START_APP.bat (or run it in your terminal)
macOS/Linux: Run cd web-app && npm run app:dev from the repo root

Both methods automatically fetch and merge the latest skills from the original repository every time you open the Web App, ensuring you always have the most up-to-date catalog.

Reinstall from Scratch

If you encounter persistent issues, remove the installation and reinstall:

# Remove existing installation
rm -rf ~/.gemini/antigravity/skills  # or your installation path

# Reinstall
npx antigravity-awesome-skills

This will delete any custom modifications you’ve made to skills. Back up your changes first if needed.

Usage Issues

AI Assistant Doesn’t Recognize Skills

Possible Cause 1: Wrong Installation Path

Check your tool’s documentation for the expected skills path. Use the installer with the correct flag:

npx antigravity-awesome-skills --claude   # Claude Code
npx antigravity-awesome-skills --cursor   # Cursor
npx antigravity-awesome-skills --gemini   # Gemini CLI

Possible Cause 2: Restart Needed

Some tools require a restart after installing skills:

Close your IDE or CLI completely
Reopen it
Try invoking a skill again

Possible Cause 3: Typos in Skill Name

Skill names are case-sensitive and use hyphens:✅ @brainstorming
❌ @brain-storming
❌ @BrainstormingCheck the exact skill name in the catalog or by listing the directory:

ls ~/.gemini/antigravity/skills/  # or your installation path

Possible Cause 4: Tool Doesn't Support Skills

Verify your tool supports the SKILL.md format. See the Compatibility page for supported platforms.

Skill Gives Incorrect or Outdated Advice

Verify you're using the latest version

cd ~/.gemini/antigravity/skills  # or your installation path
git pull origin main

Check the skill's SKILL.md file

cat ~/.gemini/antigravity/skills/[skill-name]/SKILL.md

Verify the skill description matches your expectations.

Open an issue on GitHub

If the skill is genuinely outdated or incorrect, please report it:Open an issueInclude:

Which skill
What went wrong
What should happen instead
Your environment (OS, tool, version)

Multiple Skills with Similar Names

How to choose the right skill

Some skills have similar names but different purposes:

@brainstorming - General feature planning
@systematic-debugging - Bug fixing methodology
@concise-planning - Task organization

Check the skill’s description:

# View skill metadata
head -20 ~/.gemini/antigravity/skills/[skill-name]/SKILL.md

Or browse the catalog in the Web App or CATALOG.md.

Path and Permission Issues

Permission Denied Errors

Linux/macOS

If you get permission errors during installation:

# Don't use sudo with npx - install to user directory instead
npx antigravity-awesome-skills --path ~/.antigravity-skills

# For git clone
git clone https://github.com/sickn33/antigravity-awesome-skills.git ~/.antigravity-skills

Avoid installing to system directories that require sudo.

Windows

If you get “Access Denied” errors:

Run Command Prompt or PowerShell as Administrator
Use the symlinks flag:

git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills

Skills Directory Not Found

Workspace vs Global Installation

Some tools support both workspace and global installations:Workspace (project-specific):

.agent/skills/       # Antigravity workspace
.cursor/skills/      # Cursor workspace
.kiro/skills/        # Kiro workspace

Global (all projects):

~/.gemini/antigravity/skills/  # Antigravity global
~/.kiro/skills/                # Kiro global

Make sure you’re installing to the correct scope for your needs.

Tool-Specific Issues

Kiro IDE Import Issues

Individual skill import not working

If importing individual skills via the Kiro IDE GUI fails:

Verify the URL format:

https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/[skill-name]

Check your internet connection
Try bulk installation instead:
```
npx antigravity-awesome-skills --kiro
```

GitHub Copilot Compatibility

GitHub Copilot has limited support for skills. You must manually copy and paste skill content.

How to use skills with GitHub Copilot

Clone for reference

git clone https://github.com/sickn33/antigravity-awesome-skills.git ~/skills-reference

Find the skill

cat ~/skills-reference/skills/[skill-name]/SKILL.md

Copy content

Copy the entire SKILL.md content

Paste in Copilot Chat

Paste in GitHub Copilot Chat, followed by your request

OpenCode Path Issues

OpenCode not finding skills

OpenCode changed its default skills path to .agents/skills/:

# Install to correct path
npx antigravity-awesome-skills --path .agents/skills

# Verify
test -d .agents/skills && echo "Skills installed correctly"

See the Place Files directive on OpenCode Docs.

Quality and Validation Issues

Skill Fails Quality Checks

For Contributors

If you’re contributing a skill and it fails CI checks:

Run validation locally:

npm run validate          # Standard checks
npm run validate:strict   # CI-level checks

Check for required fields:
- Valid description in frontmatter
- Usage examples in the skill
- Proper SKILL.md format
Validate references (optional):
```
python3 scripts/validate_references.py
```
See QUALITY_BAR.md for full requirements

Official Skills Are Broken Links

Symlink issues with official skills

Official skills in skills/official/ are symlinked from vendor repositories. If they appear as broken:On Windows:

# Clone with symlinks enabled
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills

On Linux/macOS: Symlinks should work automatically. If not:

# Check if symlinks are preserved
ls -la ~/.gemini/antigravity/skills/skills/official/

# You should see -> arrows indicating symlinks

If symlinks are still broken, open an issue.

Getting Help

Check the FAQ

Many common questions are already answered

Browse Examples

See real-world usage patterns

Open a Discussion

Ask questions to the community

File an Issue

Report bugs or request features

Still Having Issues?

If this guide didn’t solve your problem:

Gather information

Collect:

Your OS and version
Your AI tool and version
Installation path you used
Exact error message
Steps to reproduce

Search existing issues

Check if someone else had the same problem: Search GitHub Issues

Open a new issue

If you can’t find a solution: Create a new issueProvide all information from Step 1.

Remember: The whole point of this project is to make AI assistants easier to use. If this guide didn’t help, let us know so we can improve it! 🙌

Get Started

Usage

Guides

Common Installation Issues

`npx antigravity-awesome-skills` returns 404

Windows Clone Issues (Symlinks)

Why This Happens

Solution 1: Enable Developer Mode (Recommended)

Solution 2: Git Clone with Symlinks Flag

Skills Installed But Not Detected

Check Your Installation Path

Solution: Reinstall to Correct Path

Verify Installation

Update Issues

Update an Existing Installation

Reinstall from Scratch

Usage Issues

AI Assistant Doesn’t Recognize Skills

Skill Gives Incorrect or Outdated Advice

Multiple Skills with Similar Names

Path and Permission Issues

Permission Denied Errors

Skills Directory Not Found

Tool-Specific Issues

Kiro IDE Import Issues

GitHub Copilot Compatibility

OpenCode Path Issues

Quality and Validation Issues

Skill Fails Quality Checks

Official Skills Are Broken Links

Getting Help

Check the FAQ

Browse Examples

Open a Discussion

File an Issue

Still Having Issues?

Build docs developers (and LLMs) love

Get Started

Usage

Guides

​Common Installation Issues

​npx antigravity-awesome-skills returns 404

​Windows Clone Issues (Symlinks)

​Why This Happens

​Solution 1: Enable Developer Mode (Recommended)

​Solution 2: Git Clone with Symlinks Flag

​Skills Installed But Not Detected

​Check Your Installation Path

​Solution: Reinstall to Correct Path

​Verify Installation

​Update Issues

​Update an Existing Installation

​Reinstall from Scratch

​Usage Issues

​AI Assistant Doesn’t Recognize Skills

​Skill Gives Incorrect or Outdated Advice

​Multiple Skills with Similar Names

​Path and Permission Issues

​Permission Denied Errors

​Skills Directory Not Found

​Tool-Specific Issues

​Kiro IDE Import Issues

​GitHub Copilot Compatibility

​OpenCode Path Issues

​Quality and Validation Issues

​Skill Fails Quality Checks

​Official Skills Are Broken Links

​Getting Help

Check the FAQ

Browse Examples

Open a Discussion

File an Issue

​Still Having Issues?

Build docs developers (and LLMs) love

Common Installation Issues

`npx antigravity-awesome-skills` returns 404

Windows Clone Issues (Symlinks)

Why This Happens

Solution 1: Enable Developer Mode (Recommended)

Solution 2: Git Clone with Symlinks Flag

Skills Installed But Not Detected

Check Your Installation Path

Solution: Reinstall to Correct Path

Verify Installation

Update Issues

Update an Existing Installation

Reinstall from Scratch

Usage Issues

AI Assistant Doesn’t Recognize Skills

Skill Gives Incorrect or Outdated Advice

Multiple Skills with Similar Names

Path and Permission Issues

Permission Denied Errors

Skills Directory Not Found

Tool-Specific Issues

Kiro IDE Import Issues

GitHub Copilot Compatibility

OpenCode Path Issues

Quality and Validation Issues

Skill Fails Quality Checks

Official Skills Are Broken Links

Getting Help

Still Having Issues?