From 434e0f2c8b84a38ba65930250cfdf62275674309 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Tue, 17 Feb 2026 23:28:04 +0100 Subject: [PATCH] Add comprehensive usage guide addressing post-installation confusion (#93) * Initial plan * Add comprehensive USAGE.md guide addressing confusion after installation Co-authored-by: sickn33 <184072420+sickn33@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: sickn33 <184072420+sickn33@users.noreply.github.com> --- README.md | 39 +++-- docs/FAQ.md | 2 + docs/GETTING_STARTED.md | 2 + docs/USAGE.md | 362 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 391 insertions(+), 14 deletions(-) create mode 100644 docs/USAGE.md diff --git a/README.md b/README.md index 9e9e11f..18d4ec9 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ This repository provides essential skills to transform your AI assistant into a ## Table of Contents - [πŸš€ New Here? Start Here!](#new-here-start-here) +- [πŸ“– Complete Usage Guide](docs/USAGE.md) - **Start here if confused after installation!** - [πŸ”Œ Compatibility & Invocation](#compatibility--invocation) - [πŸ› οΈ Installation](#installation) - [🧯 Troubleshooting](#troubleshooting) @@ -94,7 +95,9 @@ Once installed, just ask your agent naturally: > "Use the **@brainstorming** skill to help me plan a SaaS." > "Run **@lint-and-validate** on this file." -πŸ‘‰ **[Read the Full Getting Started Guide](docs/GETTING_STARTED.md)** +πŸ‘‰ **NEW:** [**Complete Usage Guide - Read This First!**](docs/USAGE.md) (answers: "What do I do after installation?", "How do I execute skills?", "What should prompts look like?") + +πŸ‘‰ **[Full Getting Started Guide](docs/GETTING_STARTED.md)** --- @@ -219,26 +222,34 @@ npx antigravity-awesome-skills **Bundles** are curated groups of skills for a specific role or goal (for example: `Web Wizard`, `Security Engineer`, `OSS Maintainer`). -They help you avoid picking from 700+ skills one by one. +They help you avoid picking from 860+ skills one by one. -What bundles are: +### ⚠️ Important: Bundles Are NOT Separate Installations! -- Recommended starting sets for common workflows. -- A shortcut for onboarding and faster execution. +**Common confusion:** "Do I need to install each bundle separately?" -What bundles are not: +**Answer: NO!** Here's what bundles actually are: -- Not a separate install. -- Not a locked preset. +**What bundles ARE:** +- βœ… Recommended skill lists organized by role +- βœ… Curated starting points to help you decide what to use +- βœ… Time-saving shortcuts for discovering relevant skills -How to use bundles: +**What bundles are NOT:** +- ❌ Separate installations or downloads +- ❌ Different git commands +- ❌ Something you need to "activate" -1. Install the repository once. -2. Pick one bundle in [docs/BUNDLES.md](docs/BUNDLES.md). -3. Start with 3-5 skills from that bundle in your prompt. -4. Add more only when needed. +### How to use bundles: -Examples: +1. **Install the repository once** (you already have all skills) +2. **Browse bundles** in [docs/BUNDLES.md](docs/BUNDLES.md) to find your role +3. **Pick 3-5 skills** from that bundle to start using in your prompts +4. **Reference them in your conversations** with your AI (e.g., "Use @brainstorming...") + +For detailed examples of how to actually use skills, see the [**Usage Guide**](docs/USAGE.md). + +### Examples: - Building a SaaS MVP: `Essentials` + `Full-Stack Developer` + `QA & Testing`. - Hardening production: `Security Developer` + `DevOps & Cloud` + `Observability & Monitoring`. diff --git a/docs/FAQ.md b/docs/FAQ.md index a0942bc..0c982c2 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -114,6 +114,8 @@ git pull origin main ## πŸ› οΈ Using Skills +> **πŸ’‘ For a complete guide with examples, see [USAGE.md](USAGE.md)** + ### How do I invoke a skill? Use the `@` symbol followed by the skill name: diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 08db5da..dc5975a 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -2,6 +2,8 @@ **New here? This guide will help you supercharge your AI Agent in 5 minutes.** +> **πŸ’‘ Confused about what to do after installation?** Check out the [**Complete Usage Guide**](USAGE.md) for detailed explanations and examples! + --- ## πŸ€” What Are "Skills"? diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..1a6fab0 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,362 @@ +# πŸ“– 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: + +### What You Just Did + +When you ran `npx antigravity-awesome-skills` or cloned the repository, you: + +βœ… **Downloaded 860+ skill files** to your computer (usually in `~/.agent/skills/`) +βœ… **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" (This is NOT Another Install!) + +**Common confusion:** "Do I need to download each skill separately?" + +**Answer: NO!** Here's what bundles actually are: + +### What Bundles Are + +Bundles are **recommended lists** of skills grouped by role. They help you decide which skills to start using. + +**Analogy:** +- You installed a toolbox with 860 tools (βœ… done) +- Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools" +- You don't install bundlesβ€”you **pick skills from them** + +### What Bundles Are NOT + +❌ Separate installations +❌ Different download commands +❌ Something you need to "activate" + +### Example: The "Web Wizard" Bundle + +When you see the [Web Wizard bundle](BUNDLES.md#-the-web-wizard-pack), it lists: +- `frontend-design` +- `react-best-practices` +- `tailwind-patterns` +- etc. + +These are **recommendations** for which skills a web developer should try first. They're already installedβ€”you just need to **use them in your prompts**. + +--- + +## πŸš€ 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) +```bash +# In your terminal/chat with Claude Code: +>> Use @brainstorming to help me design a todo app +``` + +#### Cursor (IDE) +```bash +# In the Cursor chat panel: +@brainstorming help me design a todo app +``` + +#### Gemini CLI +```bash +# In your conversation with Gemini: +Use the brainstorming skill to help me plan my app +``` + +#### Codex CLI +```bash +# In your conversation with Codex: +Apply @brainstorming to design a new feature +``` + +#### Antigravity IDE +```bash +# 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 860 skills! Here's a sensible approach: + +### 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](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](../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](../CATALOG.md) (searchable list) +2. Run `ls ~/.agent/skills/` (if installed there) +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 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: `~/.agent/skills/[skill-name]/SKILL.md` +2. Read the description to ensure you're using it correctly +3. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) 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](BUNDLES.md) +3. πŸ”– **Bookmark** [CATALOG.md](../CATALOG.md) for when you need something specific +4. 🎯 **Try a workflow** from [WORKFLOWS.md](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](FAQ.md) +2. See [Real-World Examples](EXAMPLES.md) +3. [Open a Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) +4. [File an Issue](https://github.com/sickn33/antigravity-awesome-skills/issues) 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. πŸ™Œ