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

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 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 (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 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, which crawls the skills/ tree and extracts metadata from each SKILL.md file.

Bundle Definitions Layer

Logical groupings such as Web Wizard or Security Engineer are stored declaratively in 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 script consolidates the skill index, bundle definitions, and additional metadata (aliases, category hierarchies) into two public-facing artifacts: data/catalog.json (machine-readable) and 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 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. The workflow executes 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 file containing front-matter, "When to Use" guidance, and implementation details.

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 to update skills_index.json
2. Executes tools/scripts/build-catalog.js to regenerate data/catalog.json and CATALOG.md
3. Validates that any bundle references in 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:

# 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:

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

# Output: ✅ Enabled: youtube-summarizer

Updating Bundles

Edit data/bundles.json to create or modify logical groupings. Each bundle entry follows this structure:

{
  "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) 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:

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 used by the documentation site.

Key Implementation Files

• tools/scripts/skills_manager.py — CLI utility for local enable/disable operations
• tools/lib/skill-utils.js — Core library containing parseFrontmatter and skill enumeration logic
• tools/scripts/generate_index.py — Generates skills_index.json from the filesystem
• tools/scripts/build-catalog.js — Consolidates indexes and bundles into public artifacts
• tools/scripts/validate_references.py — CI validation ensuring bundle integrity
• data/bundles.json — Declarative bundle definitions mapping roles to skill arrays
• skills_index.json — Generated flat list enabling fast runtime lookups

Programmatic Examples

Reading the Skill Index in Node.js:

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:

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 files
• Pre-generated indexes (skills_index.json) eliminate runtime filesystem scanning for 1,000+ items, providing O(1) lookups
• Declarative bundles in data/bundles.json enable role-based collections without file duplication
• Local activation control via 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 script crawls the skills/ directory tree during CI and writes a flat 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 CI pipeline runs tools/scripts/validate_references.py on every pull request. This script cross-references every skill slug listed in 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 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 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.

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