# Plugins for Claude Code and Codex

Release `9.0.0` adds first-class plugin distributions for both **Claude Code** and **Codex**.

This page is the canonical explanation of what those plugins are, how they differ from a full library install, and why the repository now ships both a **root plugin** and multiple **bundle plugins**.

## What a plugin is in this repo

In Antigravity Awesome Skills, a plugin is a packaged, installable distribution of skills plus the metadata a host tool needs to expose that distribution through its plugin or marketplace flow.

Plugins are useful when you want:

- a marketplace-style install instead of copying files into `.claude/skills/` or `.codex/skills/`
- a narrower install surface for a team or role
- a safer default distribution for plugin ecosystems

Plugins are **not** different content formats. They still ship `SKILL.md` playbooks. The difference is the packaging, install surface, and filtering.

## Full library install vs plugin install

You now have two valid ways to use this repository with Claude Code or Codex.

### Full library install

Use the installer or clone the repository directly when you want the broadest possible coverage:

```bash
npx antigravity-awesome-skills --claude
npx antigravity-awesome-skills --codex
```

Or clone manually into your preferred skills directory.

Choose the full library when you want:

- the largest available catalog
- repo-only skills that are still being hardened for plugin distribution
- direct filesystem control over the installed tree

### Plugin install

Use the plugin marketplace or repo-local plugin metadata when you want a curated, installable distribution:

- **Claude Code** uses `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json`
- **Codex** uses `.agents/plugins/marketplace.json` and `plugins/antigravity-awesome-skills/.codex-plugin/plugin.json`

Choose the plugin route when you want:

- marketplace-friendly installation
- a cleaner starter surface
- plugin-safe filtering by default
- bundle-specific installs such as `Essentials`, `Security Engineer`, or `Web Wizard`

## What `plugin-safe` means

Not every skill in the repository is immediately suitable for plugin publication.

`plugin-safe` means the published plugin excludes skills that still need hardening, portability cleanup, or explicit setup metadata. In practice, plugin-safe filtering avoids shipping skills that rely on:

- host-specific local paths
- undeclared manual setup
- assumptions that are acceptable in the full repository but too brittle for marketplace distribution

This is why the **full library** can be larger than the **plugin-safe** subset. That difference is expected and intentional.

The important rule is:

- the repository remains the source of truth for the complete library
- plugins publish the hardened subset that is ready for marketplace-style installation

## Root plugin vs bundle plugins

The repository now ships two plugin shapes.

### Root plugin

The root plugin is the broad installable distribution for each host:

- **Claude Code root plugin**: install the plugin-safe Antigravity library through the Claude marketplace entry
- **Codex root plugin**: expose the plugin-safe Antigravity library through the Codex plugin surface

Use the root plugin when you want the widest plugin-safe install without picking a specialty bundle.

### Bundle plugins

Bundle plugins are smaller, role-based distributions generated from the same repository. Examples include:

- `Essentials`
- `Security Engineer`
- `Web Wizard`
- `Full-Stack Developer`

Use a bundle plugin when you want:

- a lighter starting point
- a team-specific plugin install
- a curated subset instead of the broad root plugin

## Claude Code plugin surface

Claude Code uses the repository's root `.claude-plugin` metadata.

Relevant files:

- `.claude-plugin/marketplace.json`
- `.claude-plugin/plugin.json`

Typical install flow:

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

Claude Code bundle plugins are also published through the same marketplace metadata, so you can install a focused bundle instead of the root plugin if you prefer.

## Codex plugin surface

Codex uses repo-local plugin metadata that points at the local plugin folders generated by this repository.

Relevant files:

- `.agents/plugins/marketplace.json`
- `plugins/antigravity-awesome-skills/.codex-plugin/plugin.json`

The Codex root plugin exposes the same plugin-safe library idea as Claude Code, but through Codex's plugin metadata conventions.

Bundle-specific Codex plugins are generated alongside the root plugin so you can install a narrower pack when plugin marketplaces are available in your Codex environment.

## Which path should you choose?

Choose the **full library** if:

- you want the biggest catalog
- you are comfortable installing directly into skills directories
- you want repo-only skills that are not yet published as plugins

Choose the **root plugin** if:

- you want the broad installable plugin-safe distribution
- you prefer marketplace-style installation
- you want a safer default surface for Claude Code or Codex

Choose a **bundle plugin** if:

- you want a smaller role-based install
- you are onboarding a team around one domain
- you want plugin convenience without the breadth of the root plugin

## Related guides

- [Getting Started](getting-started.md)
- [FAQ](faq.md)
- [Claude Code skills](claude-code-skills.md)
- [Codex CLI skills](codex-cli-skills.md)
- [Bundles](bundles.md)
- [Usage](usage.md)