playbook/antigravity-awesome-skills/docs/users/usage.md

# Usage Guide: Compose and Use an AAS Skill Stack

> **Recommended path:** let Codex or Claude inspect the project, search and read the complete AAS catalog, and choose the exact skills. AAS Core records and validates that agent-owned selection.

## Primary workflow: agent-first composition

After configuring the local AAS MCP, ask your agent to inspect the repository and choose a stack for the outcome you want:

```text
Inspect this repository and enumerate its primary capability areas. For each
capability, search the complete AAS catalog, paginate or refine the query, and
compare multiple plausible candidates with get_skill when available. Select at
least one non-redundant valid skill per capability, explicitly report catalog
gaps, and evaluate architecture/runtime, languages/frameworks, domain behavior,
data/storage, integrations, testing/quality, security/privacy, UX/accessibility,
deployment/operations, and maintenance workflow. Mark dimensions not applicable
instead of silently omitting them. Do not stop at the first few matches or
optimize for the smallest stack. Core has no semantic policy favoring a small
stack; each manifest has a technical maximum of 128 selected skills. Only then
use compose_stack with a project profile, inspect the schema 2 manifest returned
in memory, and do not apply it.
```

The agent must use `search_skills` and `get_skill` across the complete catalog, build a capability-to-skill coverage map, continue searching while a primary capability remains uncovered, choose the exact IDs itself, call `compose_stack`, then check the in-memory proposal with `inspect_stack` before presenting it. Every current catalog skill remains individually searchable, readable, and selectable. A client or the CLI can persist the reviewed `aas-stack.json`; an audit-enabled flow can then call `export_selection_evidence`, validate it with `inspect_selection_evidence`, and atomically publish the manifest and separate `aas-selection-evidence.json` sidecar in an `artifact-dir`. Use `aas stack plan` to preview the exact operations without materializing skills or managed state in the target.

Selection evidence contains the raw `search_skills` queries observed during the MCP session. Do not place secrets, credentials, private source text, or personal data in catalog queries.

Selection belongs to the coding agent. AAS MCP does not inspect the repository itself, rank or exclude skills, install skills, update catalogs, or change configuration. See [AAS Core](aas-core.md) for setup, the exact tool boundary, CLI commands, and preview limitations.

`stack apply` and `stack recover` are experimental, disabled by default, and are not supported or certified preview safety claims.

---

## Alternative workflow: direct skill installation

If you came in through a **Claude Code** or **Codex** plugin instead of AAS Core or a full library install, invoke individual skills in prompts. Plugins ship a fixed plugin-safe subset; AAS Core instead validates and records the exact stack the agent selected from the verified catalog in `aas-stack.json`. See [plugins.md](plugins.md) for the distribution model.

### What direct distribution provides

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

✅ **Downloaded 1,994+ skill files** to your computer (default: `~/.agents/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)

Direct distribution makes skill files available to the host. It does not select a project-specific stack, record desired state, or produce a preview plan; those are AAS Core responsibilities.

---

## Direct-install Step 1: Understanding Bundles

**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.

Bundles provide editorial shortlists. You can either select individual skills from a bundle or install its focused marketplace plugin where supported.

### 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](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. 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](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:

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

---

## Direct-install Step 2: Invoke a Skill

### 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
```

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

```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!

---

## Direct-install Step 3: Write a Focused Prompt

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!

---

## Direct-install Step 4: Your First Skill

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!

---

## Direct-install Step 5: Pick Skills Manually

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

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

- [Claude Code skills](claude-code-skills.md)
- [Cursor skills](cursor-skills.md)
- [Codex CLI skills](codex-cli-skills.md)
- [Gemini CLI skills](gemini-cli-skills.md)

### 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. With AAS Core, ask the agent to call `search_skills` and inspect candidates with `get_skill`. On a direct install, you can also:

1. Browse [CATALOG.md](../../CATALOG.md) (searchable list)
2. Run `ls ~/.agents/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 agentic-awesome-skills --claude` (or `--cursor`, `--gemini`, etc.)

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

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

The intended pattern is:

- use `skills_index.json` (canonical discovery manifest) to discover which skills exist; and
- use `data/skills_index.json` only when your host reads from `data/` for compatibility;
- 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`](../integrations/jetski-cortex.md)

The v1 manifest shape is defined in:

- [`schemas/skills-index.v1.schema.json`](../../schemas/skills-index.v1.schema.json)
- [`discovery-manifest.md`](discovery-manifest.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: `~/.agents/skills/[skill-name]/SKILL.md`
2. Read the description to ensure you're using it correctly
3. [Open an issue](https://github.com/sickn33/agentic-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

For the Core-first path:

1. Configure the local MCP with the [AAS Core guide](aas-core.md).
2. Ask the agent to search the complete catalog, choose exact IDs, and explain its selection.
3. Review `aas-stack.json`, validate it, and preview the plan.

For direct/manual use:

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](../contributors/examples.md)
3. [Open a Discussion](https://github.com/sickn33/agentic-awesome-skills/discussions)
4. [File an Issue](https://github.com/sickn33/agentic-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. 🙌