antigravity-skills-reference/docs/users/usage.md

Usage Guide: How to Actually Use These Skills

Confused after installation? This guide walks you through exactly what to do next, step by step.

---

"I just installed the repository. Now what?"

Great question! Here's what just happened and what to do next:

If you came in through a Claude Code or Codex plugin instead of a full library install, the mental model is the same: you still invoke individual skills in prompts. The main difference is that plugins ship the plugin-safe subset. See plugins.md for the install model.

What You Just Did

When you ran npx antigravity-awesome-skills or cloned the repository, you:

✅ Downloaded 1,373+ skill files to your computer (default: ~/.gemini/antigravity/skills/; or a custom path like ~/.agent/skills/ if you used --path)
✅ Made them available to your AI assistant
❌ Did NOT enable them all automatically (they're just sitting there, waiting)

Think of it like installing a toolbox. You have all the tools now, but you need to pick which ones to use for each job.

---

Step 1: Understanding "Bundles" (Recommendations or Focused Installs)

Common confusion: "Do I need to download each skill separately?"

Answer: NO! You do not need to download each skill separately. Here's what bundles actually are:

What Bundles Are

Bundles are curated groups of skills organized by role. They help you decide which skills to start using, and they can also be exposed as focused marketplace plugins for Claude Code and Codex.

Analogy:

• You installed a toolbox with 1,373+ tools (✅ done)
• Bundles are like labeled organizer trays saying: "If you're a carpenter, start with these 10 tools"
• You can either pick skills from the tray or install that tray as a focused marketplace bundle plugin

What Bundles Are NOT

❌ Separate skill downloads
❌ Invokable mega-skills like @essentials or /web-wizard ❌ Something most users need to activate during normal install ❌ A replacement for invoking the individual skills inside the bundle

Example: The "Web Wizard" Bundle

When you see the Web Wizard bundle, it lists:

• frontend-design
• react-best-practices
• tailwind-patterns
• etc.

These are recommendations for which skills a web developer should try first. If you have the full library installed, you just need to use them in your prompts. If you prefer a narrower install surface, you can install the matching bundle plugin in Claude Code or Codex where plugin marketplaces are available.

The key distinction is:

• full library install = broadest catalog
• root plugin = broad plugin-safe distribution
• bundle plugin = curated plugin-safe subset

See plugins.md for the canonical explanation.

If you want only one bundle active at a time in Antigravity, use the activation scripts instead of trying to invoke the bundle name directly:

./scripts/activate-skills.sh --clear Essentials
./scripts/activate-skills.sh --clear "Web Wizard"

---

Step 2: How to Actually Execute/Use a Skill

This is the part that should have been explained better! Here's how to use skills:

The Simple Answer

Just mention the skill name in your conversation with your AI assistant.

Different Tools, Different Syntax

The exact syntax varies by tool, but it's always simple:

Claude Code (CLI)

# In your terminal/chat with Claude Code:
>> Use @brainstorming to help me design a todo app

Cursor (IDE)

# In the Cursor chat panel:
@brainstorming help me design a todo app

Gemini CLI

# In your conversation with Gemini:
Use the brainstorming skill to help me plan my app

If Gemini CLI starts hanging after a few turns, try a fresh conversation and temporarily reduce the active set to just 2-5 skills to rule out context growth.

Codex CLI

# In your conversation with Codex:
Apply @brainstorming to design a new feature

Antigravity IDE

# In agent mode:
Use @brainstorming to plan this feature

Pro Tip: Most modern tools use the @skill-name syntax. When in doubt, try that first!

---

Step 3: What Should My Prompts Look Like?

Here are real-world examples of good prompts:

Example 1: Starting a New Project

Bad Prompt:

"Help me build a todo app"

Good Prompt:

"Use @brainstorming to help me design a todo app with user authentication and cloud sync"

Why it's better: You're explicitly invoking the skill and providing context.

---

Example 2: Reviewing Code

Bad Prompt:

"Check my code"

Good Prompt:

"Use @lint-and-validate to check src/components/Button.tsx for issues"

Why it's better: Specific skill + specific file = precise results.

---

Example 3: Security Audit

Bad Prompt:

"Make my API secure"

Good Prompt:

"Use @api-security-best-practices to review my REST endpoints in routes/api/users.js"

Why it's better: The AI knows exactly which skill's standards to apply.

---

Example 4: Combining Multiple Skills

Good Prompt:

"Use @brainstorming to design a payment flow, then apply @stripe-integration to implement it"

Why it's good: You can chain skills together in a single prompt!

---

Step 4: Your First Skill (Hands-On Tutorial)

Let's actually use a skill right now. Follow these steps:

Scenario: You want to plan a new feature

1. Pick a skill: Let's use brainstorming (from the "Essentials" bundle)

2. Open your AI assistant (Claude Code, Cursor, etc.)

3. Type this exact prompt:

   Use @brainstorming to help me design a user profile page for my app
   

4. Press Enter

5. What happens next:

   • The AI loads the brainstorming skill
   • It will start asking you structured questions (one at a time)
   • It will guide you through understanding, requirements, and design
   • You answer each question, and it builds a complete spec

6. Result: You'll end up with a detailed design document—without writing a single line of code yet!

---

Step 5: Picking Your First Skills (Practical Advice)

Don't try to use all 1,373+ skills at once. Here's a sensible approach:

If you want a tool-specific starting point before choosing skills, use:

• Claude Code skills
• Cursor skills
• Codex CLI skills
• Gemini CLI skills

Start with "The Essentials" (5 skills, everyone needs these)

1. @brainstorming - Plan before you build
2. @lint-and-validate - Keep code clean
3. @git-pushing - Save work safely
4. @systematic-debugging - Fix bugs faster
5. @concise-planning - Organize tasks

How to use them:

• Before writing new code → @brainstorming
• After writing code → @lint-and-validate
• Before committing → @git-pushing
• When stuck → @systematic-debugging

Then Add Role-Specific Skills (5-10 more)

Find your role in bundles.md and pick 5-10 skills from that bundle.

Example for Web Developer:

• @frontend-design
• @react-best-practices
• @tailwind-patterns
• @seo-audit

Example for Security Engineer:

• @api-security-best-practices
• @vulnerability-scanner
• @ethical-hacking-methodology

Finally, Add On-Demand Skills (as needed)

Keep the CATALOG.md open as reference. When you need something specific:

"I need to integrate Stripe payments"
→ Search catalog → Find @stripe-integration → Use it!

---

Complete Example: Building a Feature End-to-End

Let's walk through a realistic scenario:

Task: "Add a blog to my Next.js website"

Step 1: Plan (use @brainstorming)

You: Use @brainstorming to design a blog system for my Next.js site

AI: [Asks structured questions about requirements]
You: [Answer questions]
AI: [Produces detailed design spec]

Step 2: Implement (use @nextjs-best-practices)

You: Use @nextjs-best-practices to scaffold the blog with App Router

AI: [Creates file structure, sets up routes, adds components]

Step 3: Style (use @tailwind-patterns)

You: Use @tailwind-patterns to make the blog posts look modern

AI: [Applies Tailwind styling with responsive design]

Step 4: SEO (use @seo-audit)

You: Use @seo-audit to optimize the blog for search engines

AI: [Adds meta tags, sitemaps, structured data]

Step 5: Test & Deploy

You: Use @test-driven-development to add tests, then @vercel-deployment to deploy

AI: [Creates tests, sets up CI/CD, deploys to Vercel]

Result: Professional blog built with best practices, without manually researching each step!

---

Common Questions

"Which tool should I use? Claude Code, Cursor, Gemini?"

Any of them! Skills work universally. Pick the tool you already use or prefer:

• Claude Code - Best for terminal/CLI workflows
• Cursor - Best for IDE integration
• Gemini CLI - Best for Google ecosystem
• Codex CLI - Best for OpenAI ecosystem

"Can I see all available skills?"

Yes! Three ways:

1. Browse CATALOG.md (searchable list)
2. Run ls ~/.gemini/antigravity/skills/ (or your actual install path)
3. Ask your AI: "What skills do you have for [topic]?"

"Do I need to restart my IDE after installing?"

Usually no, but if your AI doesn't recognize a skill:

1. Try restarting your IDE/CLI
2. Check the installation path matches your tool
3. Try the explicit path: npx antigravity-awesome-skills --claude (or --cursor, --gemini, etc.)

"Can I load all skills into the model at once?"

No. Even though you have 1,373+ skills installed locally, you should not concatenate every SKILL.md into a single system prompt or context block.

The intended pattern is:

• use data/skills_index.json (the manifest) to discover which skills exist; and
• only load the SKILL.md files for the specific @skill-id values you actually use in a conversation.

If you are building your own host/agent (e.g. Jetski/Cortex + Gemini), see:

• docs/integrations/jetski-cortex.md

"Can I create my own skills?"

Yes! Use the @skill-creator skill:

Use @skill-creator to help me build a custom skill for [your task]

"What if a skill doesn't work as expected?"

1. Check the skill's SKILL.md file directly in your installed path, for example: ~/.gemini/antigravity/skills/[skill-name]/SKILL.md
2. Read the description to ensure you're using it correctly
3. Open an issue with details

---

Quick Reference Card

Save this for quick lookup:

Task	Skill to Use	Example Prompt
Plan new feature	@brainstorming	Use @brainstorming to design a login system
Review code	@lint-and-validate	Use @lint-and-validate on src/app.js
Debug issue	@systematic-debugging	Use @systematic-debugging to fix login error
Security audit	@api-security-best-practices	Use @api-security-best-practices on my API routes
SEO check	@seo-audit	Use @seo-audit on my landing page
React component	@react-patterns	Use @react-patterns to build a form component
Deploy app	@vercel-deployment	Use @vercel-deployment to ship this to production

---

Next Steps

Now that you understand how to use skills:

1. ✅ Try one skill right now - Start with @brainstorming on any idea you have
2. 📚 Pick 3-5 skills from your role's bundle in bundles.md
3. 🔖 Bookmark CATALOG.md for when you need something specific
4. 🎯 Try a workflow from workflows.md for a complete end-to-end process

---

Pro Tips for Maximum Effectiveness

Tip 1: Start Every Feature with @brainstorming

Before writing code, use @brainstorming to plan. You'll save hours of refactoring.

Tip 2: Chain Skills in Order

Don't try to do everything at once. Use skills sequentially: Plan → Build → Test → Deploy

Tip 3: Be Specific in Prompts

Bad: "Use @react-patterns"
Good: "Use @react-patterns to build a modal component with animations"

Tip 4: Reference File Paths

Help the AI focus: "Use @security-auditor on routes/api/auth.js"

Tip 5: Combine Skills for Complex Tasks

"Use @brainstorming to design, then @test-driven-development to implement with tests"

---

Still Confused?

If something still doesn't make sense:

1. Check the FAQ
2. See Real-World Examples
3. Open a Discussion
4. File an Issue to help us improve this guide!

Remember: You're not alone! 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 fix it. 🙌