Troubleshooting & FAQ

Troubleshooting & FAQ

This section provides answers to common questions and troubleshooting steps you might encounter when using Antigravity Awesome Skills.

Troubleshooting

Installation Issues

npx antigravity-awesome-skills Command Not Found or Fails

• Node.js and npm Not Installed: Ensure you have Node.js and npm (or npx) installed on your system. You can download them from nodejs.org. Verify installation with node -v and npm -v.
• Network Connectivity: A stable internet connection is required to fetch the skills. Check your network if the installation hangs or fails with network-related errors.
• Permissions Issues: On some systems, you might encounter permission errors. Try running the command with elevated privileges (e.g., sudo npx antigravity-awesome-skills on Linux/macOS, or an administrator PowerShell/CMD on Windows), though this is often not recommended for npx. Ensure your user has write access to the target installation directory.
• NPM Cache: Clear your npm cache with npm cache clean --force and try again.

Slow Installation or Network Errors

• Internet Connection: Verify your internet speed and stability.
• VPN/Firewall: If you're using a VPN or behind a corporate firewall, it might be blocking access to registry.npmjs.org or GitHub. Try temporarily disabling them or configuring them to allow access.
• npm Registry Issues: Occasionally, the npm registry might experience temporary slowdowns. You can check the status at status.npmjs.org.

Skill Execution Problems

Skill Fails to Load or Execute

• Incorrect Path/Invocation: Ensure you are invoking the skill correctly within your AI assistant or script. Double-check the path to the SKILL.md file or any associated scripts.
• AI Assistant Compatibility: Not all AI assistants interpret SKILL.md files identically. Verify that your specific AI tool supports structured instructions in the expected format. Refer to the "Best skills by tool" section in the main README for tool-specific guidance.
• Syntax Errors in SKILL.md: While official skills are tested, if you've modified a skill, ensure there are no syntax errors in the Markdown or embedded code blocks that might confuse the AI.

Missing Dependencies for Python Skills

Many skills include Python scripts (e.g., api_bench.py, serve_api.py, api_validator.py) that require specific Python packages. If you run a skill and encounter an ImportError (e.g., ModuleNotFoundError: No module named 'fastapi'):

1. Identify Missing Package: The error message usually specifies the missing package.
2. Install Package: Use pip to install the required package. For example:

   pip install fastapi uvicorn
   # Or for the Claude Monitor skill:
   pip install psutil
   

3. Check Skill's Directory: Some skill scripts include an automatic pip install check, but it's good practice to ensure all dependencies are met.

API Key or Authentication Errors

Many advanced skills interact with external APIs (e.g., Claude, Instagram, Gemini). If a skill fails with authentication-related messages:

• Missing API Key: Ensure you have configured the necessary API keys or authentication tokens. The SKILL.md or associated scripts/documentation usually specify how to provide these (e.g., environment variables, a config.py file, or direct input to the AI).
• Incorrect API Key: Double-check that your API key is correct and hasn't expired.
• Insufficient Permissions: Verify that your API key has the necessary permissions for the operations the skill is attempting to perform.
• Service-Specific Configuration: For skills like the instagram client, ensure you've followed its specific setup instructions (e.g., python scripts/auth.py --setup) to configure accounts and tokens.

Rate Limit Exceeded Messages

If you see errors like "Rate limit exceeded," "Too many requests," or similar messages:

• Understanding Rate Limits: API providers enforce rate limits to prevent abuse and ensure fair usage. This means you can only make a certain number of requests within a given time frame.
• Wait and Retry: The simplest solution is often to wait for a short period (e.g., a few minutes or an hour) and then retry the operation. Many APIs reset their limits periodically.
• Check API Documentation: Consult the documentation for the specific API (e.g., Anthropic, Google Gemini, Meta Graph API) to understand its rate limits and best practices for handling them.
• Reduce Frequency: If you're automating tasks, consider introducing delays between requests to stay within limits.

Skill Produces Unexpected or Incorrect Output

• Review SKILL.md Instructions: Carefully re-read the SKILL.md file for the specific skill. Ensure you understand its purpose, constraints, and expected inputs/outputs.
• Clarify Your Prompt: When interacting with an AI assistant, provide even more context, clearer requirements, and explicit examples if possible. Ambiguity can lead to varied results.
• Break Down Complex Tasks: If a skill is meant for a very specific task, but you're trying to achieve something broader, try breaking your overall task into smaller steps, using individual skills for each step.
• Inspect Intermediate Steps (if applicable): If the skill's script produces intermediate results, inspect them to pinpoint where the output deviates from expectations.
• AI Assistant Specific Behavior: Different AI models can interpret instructions subtly differently. If an output is consistently off, consider if your AI assistant requires a slightly different phrasing or input structure.

Skill Not Working with a Specific AI Assistant

• Check Compatibility Matrix: Refer to the "Best skills by tool" section in the main README to see if the skill is explicitly tested or optimized for your AI assistant.
• Input Format: Some AI assistants prefer SKILL.md directly, while others might need you to paste the content or adapt it to their specific prompt format (e.g., using specific delimiters or role-based prompts).
• Tooling/Plugin Support: For assistants that support plugins or specific tooling, ensure the skill is correctly integrated or invoked according to the tool's documentation.
• Provide Feedback: If a skill consistently fails with a specific AI assistant despite your best efforts, consider opening an issue on the GitHub repository.

Frequently Asked Questions

What are "Agentic Skills"?

Agentic Skills are reusable, structured playbooks (primarily in SKILL.md format) that provide AI coding assistants with explicit operating instructions. Instead of generic prompts, skills offer context, strong constraints, and clear output expectations for recurring tasks. They help agents perform better, faster, and more reliably across various development workflows like planning, coding, debugging, testing, and security review.

How do I update my installed skills?

• If installed via npx: Simply re-run the installation command:

  npx antigravity-awesome-skills
  

  This will fetch the latest versions of all skills from the GitHub repository.
• If cloned directly from GitHub: Navigate to the cloned directory and pull the latest changes:

  cd /path/to/antigravity-awesome-skills
  git pull
  

How do I find the best skill for my task?

The repository offers several ways to discover skills:

• 📚 Browse 1,470+ Skills: Check the main README for a link to the complete searchable catalog.
• Bundles: Explore collections of skills curated for specific roles or use cases (e.g., "Frontend Developer Bundle," "Security Engineer Bundle").
• Workflows: Discover sequences of skills designed to achieve more complex, multi-step tasks.
• Best skills by tool: Find skills specifically recommended or optimized for your AI coding assistant.

Are these skills compatible with my AI coding assistant?

Antigravity Awesome Skills are designed for a wide range of AI coding assistants, including Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, Kiro, OpenCode, GitHub Copilot, and others that can interpret structured instructions.

Generally, if your AI tool supports multi-turn conversations, structured Markdown inputs, or has a mechanism for "tools" or "plugins," these skills should be adaptable. We recommend checking the "Best skills by tool" section in the main README for specific recommendations and integration notes.

Can I contribute new skills or improve existing ones?

Yes! We welcome contributions from the community. If you have an idea for a new skill, a way to improve an existing one, or have found a bug, please:

• Open an Issue: Describe your idea or the problem you encountered on the GitHub Issues page.
• Submit a Pull Request: If you've already implemented a change or a new skill, feel free to open a Pull Request on the GitHub Repository.

Please refer to the CONTRIBUTING.md file in the repository for detailed guidelines on how to contribute.