# Getting Started with AAS Core

**New here? Start with AAS Core and let your agent choose a reviewable skill stack from the complete catalog.**

> **Product boundary:** Codex or Claude owns skill selection. AAS Core provides complete local catalog access, reproducible composition, validation, and plan preview; apply and recovery remain experimental.

## Start with AAS Core

AAS Core is the primary product path. Codex or Claude inspects your project, searches and reads the complete catalog through the local read-only AAS MCP, chooses the exact skill IDs, and uses `compose_stack` to propose an `aas-stack.json`. You review those IDs before using the `aas` CLI to validate the manifest and preview a plan.

```text
project -> agent -> full local catalog -> agent selection -> compose_stack -> aas-stack.json
        -> human review -> validate -> plan preview
```

Start with the canonical [AAS Core guide](aas-core.md) to configure the MCP and run that flow. The direct installer, plugins, bundles, and manual skill invocation described below remain useful alternatives, especially for hosts without a native AAS MCP adapter.

> **Need more examples after setup?** Continue with the [Complete Usage Guide](usage.md).

---

## What Are "Skills"?

AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lack specific knowledge about your tools.
**Skills** are specialized instruction manuals (markdown files) that teach your AI how to perform specific tasks perfectly, every time.

**Analogy:** Your AI is a brilliant intern. **Skills** are the SOPs (Standard Operating Procedures) that make them a Senior Engineer.

---

## Alternative Path: Direct Skill Distribution and Starter Packs

Don't panic about the size of the repository. You don't need everything at once.
We have curated **Starter Packs** to get you running immediately.

On the direct-install path, you install the library once (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.

If you prefer a marketplace-style install for **Claude Code** or **Codex**, use the new plugin distributions described in [plugins.md](plugins.md).

### 1. Install Skills Directly

**Option A — npx (easiest):**

```bash
npx agentic-awesome-skills --antigravity --skills brainstorming,systematic-debugging --dry-run
```

Antigravity installs to `~/.agents/skills`. Because that host may load enough
installed instructions to exhaust its context or enter a truncation crash loop,
the bare command and `--antigravity` now require `--skills`, a metadata filter,
or the explicit `--all` override. Use `--cursor`, `--claude`, `--gemini`,
`--codex`, `--kiro`, or `--agy` for other tool paths, or `--path <dir>` for a
custom location. Run `npx agentic-awesome-skills --help` for details.
The installer uses a shallow clone by default so you get the current library without paying for the full git history on first install.

For Antigravity, ask a Codex or Claude agent with the read-only AAS Core MCP
configured to inspect the project, search the complete catalog, and choose exact
skill IDs. AAS MCP does not install them; after selection, have the agent run the
preview command above, show you the plan, and repeat it without `--dry-run` only
after review. Other direct-install targets keep the legacy-compatible complete
catalog behavior when no selector is supplied and print a risk summary before
writing. Installed text is not automatically executed, but it can influence an
agent when loaded, so review an exact set first:

```bash
npx agentic-awesome-skills audit --skills brainstorming,backend-dev-guidelines
npx agentic-awesome-skills --skills brainstorming,backend-dev-guidelines --dry-run
```

Use `npx agentic-awesome-skills --antigravity --all` only when you deliberately
accept the full catalog's context, truncation, and crash-loop risk.

You can also ask your agent to read the selected `SKILL.md` and every bundled
file before installation. The static audit reports risky capabilities; it does
not prove that a skill is safe. See [Security, trust, and antivirus alerts](security-and-antivirus.md).

If you see a 404 error, use: `npx github:sickn33/agentic-awesome-skills`

**Option B — git clone:**

```bash
# Universal (works for most agents)
git clone https://github.com/sickn33/agentic-awesome-skills.git .agent/skills
```

**Option C — one exact skill with GitHub CLI (preview):**

```bash
gh skill preview sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md
gh skill install sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md \
  --agent github-copilot --scope user --pin v14.2.0
```

GitHub CLI skill support is currently in preview. In this large repository, use an exact `SKILL.md` path to avoid ambiguous canonical/plugin mirrors and unnecessary full-tree discovery. Avoid `--all` unless you intentionally want every discovered skill.

### 2. Pick Your Persona

Find the bundle that matches your role (see [bundles.md](bundles.md)):

| Persona               | Bundle Name    | What's Inside?                                    |
| :-------------------- | :------------- | :------------------------------------------------ |
| **Web Developer**     | `Web Wizard`   | React Patterns, Tailwind mastery, Frontend Design |
| **Security Engineer** | `Hacker Pack`  | OWASP, Metasploit, Pentest Methodology            |
| **Manager / PM**      | `Product Pack` | Brainstorming, Planning, SEO, Strategy            |
| **Everything**        | `Essentials`   | Clean Code, Planning, Validation (The Basics)     |

---

## Bundles vs Workflows

Bundles and workflows solve different problems:

- **Bundles** = curated sets by role (what to pick).
- **Workflows** = step-by-step playbooks (how to execute).

Start with bundles in [bundles.md](bundles.md), then run a workflow from [workflows.md](workflows.md) when you need guided execution.

Example:

> "Use **@antigravity-workflows** and run `ship-saas-mvp` for my project idea."

---

## How to Use a Skill

Once installed, just talk to your AI naturally.

### Example 1: Planning a Feature (**Essentials**)

> "Use **@brainstorming** to help me design a new login flow."

**What happens:** The AI loads the brainstorming skill, asks you structured questions, and produces a professional spec.

### Example 2: Checking Your Code (**Web Wizard**)

> "Run **@lint-and-validate** on this file and fix errors."

**What happens:** The AI follows strict linting rules defined in the skill to clean your code.

### Example 3: Security Audit (**Hacker Pack**)

> "Use **@api-security-best-practices** to review my API endpoints."

**What happens:** The AI audits your code against OWASP standards.

---

## 🔌 Supported Tools

| Tool            | Status          | Path                                                                  |
| :-------------- | :-------------- | :-------------------------------------------------------------------- |
| **Claude Code** | ✅ Full Support | `.claude/skills/` or install via `/plugin marketplace add sickn33/agentic-awesome-skills` |
| **Gemini CLI**  | ✅ Full Support | `.gemini/skills/`                                                     |
| **Codex CLI**   | ✅ Full Support | `.codex/skills/` or use the repo-local plugin metadata described in [plugins.md](plugins.md) |
| **Kiro CLI**    | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/`                |
| **Kiro IDE**    | ✅ Full Support | Global: `~/.kiro/skills/` · Workspace: `.kiro/skills/`                |
| **Antigravity** | ✅ Native       | Global: `~/.agents/skills/` · Workspace: `.agent/skills/` |
| **Antigravity CLI (`agy`)** | ✅ Full Support | Global slash-command directories: `~/.gemini/antigravity-cli/skills/<skill>/SKILL.md` |
| **Cursor**      | ✅ Native       | `.cursor/skills/`                                                     |
| **OpenCode**    | ✅ Full Support | `.agents/skills/` (prefer reduced installs with `--risk`, `--category`, or `--tags`) |
| **AdaL CLI**    | ✅ Full Support | `.adal/skills/`                                                       |
| **Copilot**     | ✅ Native (preview) | `gh skill install ... --agent github-copilot` at project or user scope |

---

## Trust & Safety

We classify skills so you know what you're running:

- ⚪ **unknown**: legacy/unclassified content that still needs maintainer triage.
- 🟢 **none**: pure text/reasoning guidance.
- 🔵 **safe**: read-only or low-risk operational guidance.
- 🟠 **critical**: state-changing or deployment-impacting guidance.
- 🔴 **offensive**: pentest/red-team guidance with an explicit Authorized Use Only warning.

Community PRs may still submit `risk: unknown`, but maintainers now audit and progressively reconcile those labels using the repo-wide audit/report tooling. High-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release.

_Check the [Skill Catalog](../../CATALOG.md) for the full list._

---

## FAQ

If you prefer a plugin install instead of copying skills into tool directories, start with [plugins.md](plugins.md).

For Claude Code, use:

```text
/plugin marketplace add sickn33/agentic-awesome-skills
/plugin install agentic-awesome-skills
```

For Codex, this repository also ships a root plugin plus bundle plugins through the repo-local metadata described in [plugins.md](plugins.md).

**Q: Do I need to install every skill?**
A: No. With AAS Core, ask the agent to inspect the project and choose exact IDs from the complete catalog. On the legacy direct-install path, you can install the broad library while the host reads only invoked or relevant skills. **Starter Packs** in [bundles.md](bundles.md) remain human-curated discovery aids.

**Q: Can I make my own skills?**
A: Yes! Use the **@skill-creator** skill to build your own.

**Q: What if Antigravity on Windows gets stuck in a truncation crash loop?**
A: Follow the recovery steps in [windows-truncation-recovery.md](windows-truncation-recovery.md). It explains which Antigravity storage folders to back up and clear, and includes an optional batch helper adapted from [issue #274](https://github.com/sickn33/agentic-awesome-skills/issues/274).

**Q: What if Antigravity overloads on Linux or macOS when too many skills are active?**
A: Use the activation flow in [agent-overload-recovery.md](agent-overload-recovery.md). It shows how to run `scripts/activate-skills.sh` from a cloned repo so you can keep the full library archived and activate only the bundles or skills you need in the live Antigravity directory.

**Q: What if `agy` does not show installed skills when I type `/`?**
A: The Antigravity CLI reads skill directories from `~/.gemini/antigravity-cli/skills/<skill>/SKILL.md`. Run `npx agentic-awesome-skills --agy`, restart `agy`, then open `/skills` or type a specific slash command such as `/brainstorming`.

**Q: What if OpenCode or another `.agents/skills` host becomes unstable with a full install?**
A: Start with a reduced install instead of copying the whole library. For example: `npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none`. You can narrow further with `--tags` and use a trailing `-` to exclude values such as `typescript-`. To manage a reproducible exact set, first preview it with `npx agentic-awesome-skills@14.3.0 --path .agents/skills --release 14.3.0 --skills frontend-design,backend-dev-guidelines --dry-run`, then remove `--dry-run` only after reviewing the plan.

**Q: Is this free?**
A: Yes. Original code and tooling are MIT-licensed, and original documentation/non-code written content is CC BY 4.0. See [../../LICENSE](../../LICENSE) and [../../LICENSE-CONTENT](../../LICENSE-CONTENT).

---

## Next Steps

Need a tool-specific starting point first?

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

1. [Configure and use AAS Core](aas-core.md)
2. [Browse the Bundles](bundles.md)
3. [See Real-World Examples](../contributors/examples.md)
4. [Contribute a Skill](../../CONTRIBUTING.md)