# How to Manage and Organize a Large Collection of Skills (1000+): The Antigravity Architecture

> Effortlessly manage and organize 1000+ skills using Antigravity Architecture. Discover filesystem conventions, JSON indexes, and CI validation for O(1) lookups.

- Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
- Tags: architecture
- Published: 2026-03-18

---

**The Antigravity Awesome Skills repository handles over a thousand agentic skills by combining strict filesystem conventions with pre-generated JSON indexes, declarative bundle definitions, and automated CI validation to ensure O(1) lookups and zero drift between documentation and code.**

The `sickn33/antigravity-awesome-skills` repository stores more than a thousand reusable markdown-based playbooks that teach AI coding assistants how to perform specific tasks. To manage and organize a large collection of skills at this scale, the project implements a layered architecture that separates skill definitions from metadata indexes, eliminating the need to scan 1,000+ directories at runtime while maintaining strict validation guarantees.

## Core Architecture Layers

The repository organizes its massive corpus through five distinct layers that separate storage, indexing, grouping, generation, and validation concerns.

### Skill Definition Layer

Individual skills live under the `skills/` directory, each in its own subdirectory following the pattern `skills/{skill-slug}/`. Every skill must contain a [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file adhering to a strict schema that includes YAML front-matter, usage instructions, and limitations. Optional helper scripts may reside in a nested `scripts/` folder within the skill directory.

The front-matter is parsed by [`tools/lib/skill-utils.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/lib/skill-utils.js) (specifically the `parseFrontmatter` function) during index generation and validation.

### Skill Index Layer

Rather than scanning the filesystem at runtime, the repository maintains a flat JSON list in [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json) at the repository root. This index enumerates every skill with its filesystem path, title, and categories, enabling constant-time lookups for installers and UI components.

The index is generated by [`tools/scripts/generate_index.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py), which crawls the `skills/` tree and extracts metadata from each [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file.

### Bundle Definitions Layer

Logical groupings such as *Web Wizard* or *Security Engineer* are stored declaratively in [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json). Each bundle maps a human-readable name to an array of skill slugs, allowing role-based collections without duplicating underlying skill files.

### Catalog Generation Layer

The [`tools/scripts/build-catalog.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/build-catalog.js) script consolidates the skill index, bundle definitions, and additional metadata (aliases, category hierarchies) into two public-facing artifacts: [`data/catalog.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/catalog.json) (machine-readable) and [`CATALOG.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/CATALOG.md) (documentation). This script validates cross-references between bundles and skill slugs to ensure integrity.

### Local Activation Management

Users can enable or hide individual skills without modifying the source tree or git history. Disabled skills are moved to `skills/.disabled/`, where they remain in the repository but are ignored by installer scripts.

The [`tools/scripts/skills_manager.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/skills_manager.py) CLI utility provides `list`, `enable`, and `disable` commands that handle the filesystem moves between `skills/` and `skills/.disabled/`.

### Validation and CI

Continuous integration prevents repository drift through [`.github/workflows/skill-review.yml`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/.github/workflows/skill-review.yml). The workflow executes [`tools/scripts/validate_references.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_references.py) to verify that every slug referenced in bundles, workflows, or documentation exists on disk, and that every skill contains valid front-matter.

## Managing Skills in Practice

### Adding a New Skill

Create a new directory under `skills/` and populate it with a properly structured [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) file containing front-matter, "When to Use" guidance, and implementation details.

```bash
mkdir -p skills/youtube-summarizer

# Create skills/youtube-summarizer/SKILL.md with required front-matter

# Optional: add helper scripts under skills/youtube-summarizer/scripts/

```

After committing, the CI pipeline automatically:
1. Runs [`tools/scripts/generate_index.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py) to update [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json)
2. Executes [`tools/scripts/build-catalog.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/build-catalog.js) to regenerate [`data/catalog.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/catalog.json) and [`CATALOG.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/CATALOG.md)
3. Validates that any bundle references in [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json) point to valid skill slugs

### Disabling Skills Locally

Use the skills manager CLI to hide skills you rarely use without deleting them from the repository:

```bash

# List all active skills

python3 tools/scripts/skills_manager.py list

# Disable a specific skill

python3 tools/scripts/skills_manager.py disable youtube-summarizer

```

This moves `skills/youtube-summarizer/` into `skills/.disabled/`. The skill remains available for other users but is excluded from your local environment.

To re-enable a skill:

```bash
python3 tools/scripts/skills_manager.py enable youtube-summarizer

# Output: ✅ Enabled: youtube-summarizer

```

### Updating Bundles

Edit [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json) to create or modify logical groupings. Each bundle entry follows this structure:

```json
{
  "id": "web-wizard",
  "name": "Web Wizard",
  "description": "Essential tools for modern web development.",
  "skills": ["nextjs-best-practices", "tailwind-patterns", "seo-audit"]
}

```

After submitting a PR, the CI job `npm run validate:references` (implemented in [`tools/scripts/validate_references.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_references.py)) ensures every skill slug listed exists under `skills/`.

### Regenerating the Catalog

For bulk changes such as mass renames or category updates, manually trigger the catalog builder:

```bash
npm run build-catalog   # Executes tools/scripts/build-catalog.js

git add data/catalog.json CATALOG.md

```

This recomputes skill categories, alias mappings, and writes a fresh [`CATALOG.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/CATALOG.md) used by the documentation site.

## Key Implementation Files

- **[`tools/scripts/skills_manager.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/skills_manager.py)** — CLI utility for local enable/disable operations
- **[`tools/lib/skill-utils.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/lib/skill-utils.js)** — Core library containing `parseFrontmatter` and skill enumeration logic
- **[`tools/scripts/generate_index.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py)** — Generates [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json) from the filesystem
- **[`tools/scripts/build-catalog.js`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/build-catalog.js)** — Consolidates indexes and bundles into public artifacts
- **[`tools/scripts/validate_references.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_references.py)** — CI validation ensuring bundle integrity
- **[`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json)** — Declarative bundle definitions mapping roles to skill arrays
- **[`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json)** — Generated flat list enabling fast runtime lookups

## Programmatic Examples

**Reading the Skill Index in Node.js:**

```javascript
import { readFileSync } from "fs";
const index = JSON.parse(readFileSync("skills_index.json", "utf8"));
console.log(`Total skills: ${index.length}`);

```

**Generating a Custom Bundle in Python:**

```python
import json
import pathlib

BUNDLES_PATH = pathlib.Path("data/bundles.json")
SKILLS = json.load(open("skills_index.json"))

def create_bundle(name, skill_slugs):
    bundles = json.load(open(BUNDLES_PATH))
    bundles.append({
        "id": name.lower().replace(" ", "-"),
        "name": name,
        "description": f"Custom bundle containing {len(skill_slugs)} skills.",
        "skills": skill_slugs
    })
    json.dump(bundles, open(BUNDLES_PATH, "w"), indent=2)

create_bundle("My Starter Pack", ["youtube-summarizer", "git-automation"])

```

## Summary

- **Filesystem conventions** keep individual skills isolated in `skills/{slug}/` directories with standardized [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) files
- **Pre-generated indexes** ([`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json)) eliminate runtime filesystem scanning for 1,000+ items, providing O(1) lookups
- **Declarative bundles** in [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json) enable role-based collections without file duplication
- **Local activation control** via [`skills_manager.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_manager.py) allows users to disable skills by moving them to `skills/.disabled/`
- **Automated validation** through CI ensures every bundle reference and front-matter schema remains valid as the corpus scales

## Frequently Asked Questions

### How does the repository avoid scanning 1,000+ directories at runtime?

The repository uses a build-time index generation strategy. The [`tools/scripts/generate_index.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py) script crawls the `skills/` directory tree during CI and writes a flat [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json) file containing paths and metadata for every skill. Runtime tools read this single JSON file instead of scanning the filesystem, reducing lookup complexity from O(n) to O(1).

### What prevents broken references when skills are renamed or deleted?

The [`.github/workflows/skill-review.yml`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/.github/workflows/skill-review.yml) CI pipeline runs [`tools/scripts/validate_references.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_references.py) on every pull request. This script cross-references every skill slug listed in [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json) and documentation against the actual directories under `skills/`. If a referenced skill is missing or a skill lacks required front-matter, the build fails before merge.

### Can I create private skill bundles without modifying the public repository?

Yes. While [`data/bundles.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/data/bundles.json) stores public bundles, you can maintain local bundle definitions in a separate JSON file and use the Python pattern shown above to programmatically generate custom collections. The [`skills_manager.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_manager.py) CLI also supports local enable/disable operations that don't affect the shared repository state.

### How do I temporarily hide skills that I never use?

Use the local activation management system. Run `python3 tools/scripts/skills_manager.py disable {skill-slug}` to move the skill directory into `skills/.disabled/`. The skill remains in the repository for other users but is ignored by local installer scripts. You can re-enable it later using the `enable` command without losing any data or history.