opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/docs/users/usage.md

@@ -1,465 +0,0 @@
-# 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 2,111+ 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 2,111+ 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 2,111+ 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. 🙌