Understanding the Difference Between Bundles and Workflows in Antigravity Awesome Skills

Bundles are high-level catalog entries that define which domain to solve and when to invoke a collection of skills, while workflows are the detailed, step-by-step execution plans inside each bundle that specify exactly how to call those skills phase by phase.

The sickn33/antigravity-awesome-skills repository implements a two-layer architecture to organize AI capabilities. Grasping the difference between bundles and workflows in Antigravity Awesome Skills is essential for leveraging its modular, plug-and-play system effectively.

What Are Bundles?

A bundle is a ready-made package that groups related skills to solve a higher-level problem. It functions as a catalog entry that tells the model when to invoke a specific collection and what domain it belongs to, such as "React/Next.js Development" or "Security Audit."

Bundles are coarse-grained containers. A single bundle may contain numerous phases and dozens of individual skills. According to the source code, bundles are defined in the top-level catalog at skills/workflow_bundles_readme.md. Each bundle includes metadata fields such as name, description, category (granular-workflow-bundle or consolidated-workflow-bundle), risk, source, and a "When to Use" table. Users interact with bundles via a single command selection, enabling hierarchical composition through "Related Workflow Bundles" sections.

What Are Workflows?

A workflow is the procedural script inside a bundle that breaks a task into executable phases. It represents the how of the architecture, providing concrete actions, copy-paste prompts, and quality-gate checkpoints.

Workflows are fine-grained and linear (or sometimes parallel). They are defined inside individual bundle SKILL.md files under the "## Workflow Phases" heading. For example, in skills/react-nextjs-development/SKILL.md, the workflow specifies exact skills to invoke—such as app-builder, senior-fullstack, nextjs-app-router-patterns, and typescript-pro—along with specific actions like "Choose project type" and "Configure TypeScript."

Key Differences Between Bundles and Workflows

• Purpose: Bundles describe what problem domain to address and when to apply the skill set. Workflows describe how to execute the solution through ordered phases.

• Granularity: Bundles are coarse-grained organizational units that may span many phases. Workflows are fine-grained execution plans where each phase lists specific skill invocations and actions.

• File Location: Bundles are cataloged in skills/workflow_bundles_readme.md. Workflows are embedded within individual bundle directories inside SKILL.md files under the "## Workflow Phases" section.

• Reusability: Bundles can reference other bundles via "Related Workflow Bundles" sections, enabling hierarchical composition. Workflows are specific to their owning bundle but can be copied or linked via "Copy-Paste Prompts" to other contexts.

Practical Usage Example

When you select a bundle, you trigger the high-level scope. The model then follows the embedded workflow phases to execute.

Selecting a Bundle

Use @react-nextjs-development to build a new Next.js 14 application

This command selects the bundle, signaling the domain and context.

Executing a Workflow Phase

Inside skills/react-nextjs-development/SKILL.md, the model finds the following workflow phase:

### Phase 1: Project Setup

#### Skills to Invoke

- `app-builder` – Application scaffolding
- `senior-fullstack` – Full-stack guidance
- `nextjs-app-router-patterns` – Next.js 14+ patterns
- `typescript-pro` – TypeScript setup

#### Actions

1. Choose project type (React SPA, Next.js app)
2. Select build tool (Vite, Next.js, Create React App)
3. Scaffold project structure
4. Configure TypeScript
5. Set up ESLint and Prettier

Validating Quality Gates

The workflow concludes with quality-gate checklists that the model must verify:

## Quality Gates

- [ ] TypeScript compiles without errors
- [ ] All tests passing
- [ ] Linting clean
- [ ] Performance metrics met (LCP, CLS, FID)
- [ ] Accessibility checked (WCAG 2.1)
- [ ] Responsive design verified

Key Files in the Repository

Role	File Path	Significance
Bundle Catalog	skills/workflow_bundles_readme.md	Lists all available bundles, categories, and high-level purposes.
Bundle Definition	skills/react-nextjs-development/SKILL.md	Contains bundle metadata and embedded workflow phases.
Workflow Phases	The "## Workflow Phases" section within any SKILL.md file	Provides detailed step-by-step actions, skill invocations, and quality gates.

Summary

• Bundles act as discoverable catalog entries that define the scope and composition of skills for specific domains.
• Workflows provide actionable, phase-by-phase execution scripts residing inside bundle SKILL.md files.
• The separation enables both high-level guidance (bundles in workflow_bundles_readme.md) and low-level reproducibility (workflows with specific skill calls).
• Users select bundles with commands like Use @react-nextjs-development, while the model executes the corresponding workflow phases and quality gates.

Frequently Asked Questions

How do I select and activate a bundle?

You activate a bundle by issuing a natural language command that references the bundle identifier, such as Use @react-nextjs-development to build a new Next.js 14 application. This tells the system to load the bundle's metadata and begin executing its embedded workflow phases sequentially.

Can a workflow exist independently of a bundle?

No. According to the repository structure, workflows are always contained within bundle SKILL.md files under the "## Workflow Phases" heading. The workflow defines the execution logic for that specific bundle's domain, while the bundle provides the container and metadata required for discovery and selection.

What distinguishes granular from consolidated workflow bundles?

Granular workflow bundles target specific, narrow domains (like a single framework or audit type), while consolidated workflow bundles combine multiple granular bundles into larger orchestrations. Both types are defined in skills/workflow_bundles_readme.md and contain embedded workflows, but consolidated bundles provide broader, end-to-end solutions by composing smaller units.

How do quality gates function within a workflow?

Quality gates are checklists defined at the end of a bundle's SKILL.md file (under "## Quality Gates") that specify validation criteria such as "TypeScript compiles without errors" or "All tests passing." The model treats these as mandatory checkpoints, optionally asking the user to confirm each gate before proceeding to the next workflow phase, ensuring reproducible output standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}