claude-plugins/awesome-skills/scripts/generate-indexes.py

#!/usr/bin/env python3
"""
Generates 9 category-based SKILL.md files from antigravity-awesome-skills catalog.json.

Usage:
    python3 generate-indexes.py [--catalog PATH] [--output DIR]

Defaults:
    --catalog /home/n8n/plugins/antigravity-awesome-skills/data/catalog.json
    --output  /home/n8n/plugins/claude-plugins/awesome-skills/skills/
"""

import json
import os
import sys
import argparse

# Category descriptions for auto-invocation (these are the keywords Claude Code matches against)
CATEGORY_DESCRIPTIONS = {
    "architecture": (
        "Software architecture patterns, system design, microservices, event sourcing, "
        "DDD, domain-driven design, CQRS, C4 diagrams, API design principles, monorepo, "
        "hexagonal architecture, clean architecture, ADR, architectural decision records, "
        "distributed systems, modular design, design patterns, scalability, code refactoring, "
        "Angular, component architecture, state management. "
        "Use when designing systems, reviewing architecture, planning infrastructure patterns, "
        "refactoring codebases, or choosing architectural approaches."
    ),
    "business": (
        "Business strategy, competitive analysis, pricing models, conversion rate optimization, "
        "SEO, search engine optimization, content marketing, copywriting, growth hacking, "
        "product management, A/B testing setup, customer journey mapping, marketplace strategy, "
        "retention analysis, user onboarding, go-to-market, HR operations, sales automation. "
        "Use when analyzing business metrics, planning marketing, optimizing conversions, "
        "writing copy, or developing product strategy."
    ),
    "data-ai": (
        "AI engineering, machine learning, LLM applications, RAG pipelines, retrieval augmented generation, "
        "vector search, embeddings, AI agent frameworks, CrewAI, autonomous agents, data pipelines, "
        "NLP, natural language processing, computer vision, fine-tuning, MLOps, data analytics, "
        "prompt engineering, Azure AI, OpenAI SDK, voice agents, data scientist, data engineer, "
        "model evaluation, observability, AI safety. "
        "Use when building AI applications, designing ML pipelines, implementing RAG, "
        "working with LLMs, or engineering data systems."
    ),
    "development": (
        "Software development, React, Vue, Angular, Svelte, Next.js, Python, TypeScript, JavaScript, "
        "Rust, Go, Golang, Java, C#, C++, Ruby, PHP, Elixir, Haskell, Kotlin, Swift, "
        "API development, REST, GraphQL, WebSocket, full-stack, mobile development, "
        "NestJS, FastAPI, Django, Express, database patterns, authentication, design systems, "
        "Tailwind CSS, Radix UI, state management, game development, Godot, Unreal Engine, "
        "3D web, Three.js, cross-platform, Electron, Tauri. "
        "Use when writing code, building applications, choosing frameworks, "
        "implementing features, or debugging development issues."
    ),
    "general": (
        "Technical writing, documentation, creative writing, brainstorming, decision frameworks, "
        "communication strategy, knowledge management, leadership coaching, feedback systems, "
        "career development, learning paths, prompt engineering, tool design, productivity, "
        "project planning, research methodology, writing style guides, presentation design, "
        "information architecture, taxonomy, content strategy. "
        "Use when brainstorming ideas, writing documentation, planning projects, "
        "designing communication strategies, or organizing knowledge."
    ),
    "infrastructure": (
        "DevOps, CI/CD, continuous integration, Docker, Kubernetes, K8s, Terraform, "
        "AWS, Amazon Web Services, Azure cloud, GCP, Google Cloud, monitoring, Grafana, Prometheus, "
        "load balancing, infrastructure as code, IaC, serverless, Lambda, database migration, "
        "Linux administration, networking, DNS, observability, logging, Helm, ArgoCD, "
        "GitOps, service mesh, Istio, cloud security, cost optimization. "
        "Use when setting up infrastructure, configuring CI/CD, deploying services, "
        "managing containers, or optimizing cloud resources."
    ),
    "security": (
        "Application security, penetration testing, ethical hacking, OWASP, "
        "authentication patterns, OAuth2, JWT, encryption, TLS, "
        "compliance, GDPR, HIPAA, SOC2, PCI-DSS, secrets management, "
        "web application security, supply chain security, vulnerability assessment, "
        "code audit, binary analysis, malware analysis, threat modeling, "
        "API security, network security, cloud security, incident response, forensics. "
        "Use when securing applications, performing security audits, "
        "implementing authentication, or assessing vulnerabilities."
    ),
    "testing": (
        "Testing strategies, test-driven development, TDD, end-to-end testing, E2E, "
        "Playwright, Cypress, Jest, unit testing, integration testing, load testing, "
        "chaos engineering, API testing, visual regression testing, accessibility testing, "
        "snapshot testing, test data management, QA automation, mutation testing, "
        "contract testing, performance testing, test architecture, mocking, fixtures. "
        "Use when writing tests, designing test strategies, setting up test frameworks, "
        "or implementing quality assurance workflows."
    ),
    "workflow": (
        "Workflow automation, agile ceremonies, sprint planning, incident response playbooks, "
        "change management, continuous delivery practices, documentation workflows, "
        "async communication, onboarding processes, metrics and KPIs, meeting facilitation, "
        "retrospectives, kanban, release management, runbooks, post-mortems, "
        "team collaboration, code review processes, deployment checklists. "
        "Use when designing workflows, planning agile processes, creating runbooks, "
        "managing incidents, or optimizing team collaboration."
    ),
}

SKILL_TEMPLATE = """---
name: awesome-{category}
description: {description}
---

# {title} Skills Router

Routes to {count} specialized {title_lower} skills from antigravity-awesome-skills.

## Instructions

When this skill is invoked:
1. Match the user's request against the skill index below
2. Read the full SKILL.md file using the Read tool from the path shown
3. If multiple skills match, pick the most specific one
4. Apply the loaded skill's guidance to help the user
5. If no clear match exists, list the top 3-5 candidates and ask

**Skill files location** (check in order):
- `/home/n8n/plugins/antigravity-awesome-skills/skills/{{id}}/SKILL.md`
- `~/.claude/antigravity-awesome-skills/skills/{{id}}/SKILL.md`
- `~/antigravity-awesome-skills/skills/{{id}}/SKILL.md`

## Skill Index

| ID | Description |
|----|-------------|
{index_rows}
"""


def truncate_description(desc, max_len=80):
    """Extract first sentence or truncate."""
    # Remove "Use when:" suffix
    if "Use when:" in desc:
        desc = desc[:desc.index("Use when:")].strip().rstrip(".")
    # Take first sentence
    for sep in [". ", ".\n"]:
        if sep in desc:
            desc = desc[:desc.index(sep)]
            break
    if len(desc) > max_len:
        desc = desc[:max_len-3] + "..."
    return desc


def main():
    parser = argparse.ArgumentParser(description="Generate category SKILL.md indexes")
    parser.add_argument("--catalog", default="/home/n8n/plugins/antigravity-awesome-skills/data/catalog.json")
    parser.add_argument("--output", default="/home/n8n/plugins/claude-plugins/awesome-skills/skills")
    args = parser.parse_args()

    if not os.path.exists(args.catalog):
        print(f"ERROR: catalog.json not found at {args.catalog}")
        print("Clone the repo first: git clone https://github.com/sickn33/antigravity-awesome-skills.git")
        sys.exit(1)

    with open(args.catalog) as f:
        data = json.load(f)

    # Group by category
    categories = {}
    for skill in data["skills"]:
        cat = skill.get("category", "uncategorized")
        if cat == "uncategorized":
            continue
        categories.setdefault(cat, []).append(skill)

    # Generate SKILL.md per category
    for cat, skills in sorted(categories.items()):
        if cat not in CATEGORY_DESCRIPTIONS:
            print(f"WARNING: No description for category '{cat}', skipping")
            continue

        skills.sort(key=lambda s: s["id"])

        index_rows = []
        for s in skills:
            short_desc = truncate_description(s.get("description", s["id"]))
            index_rows.append(f"| `{s['id']}` | {short_desc} |")

        title = cat.replace("-", " & ").title()
        content = SKILL_TEMPLATE.format(
            category=cat,
            description=CATEGORY_DESCRIPTIONS[cat],
            title=title,
            title_lower=title.lower(),
            count=len(skills),
            index_rows="\n".join(index_rows),
        )

        out_dir = os.path.join(args.output, cat)
        os.makedirs(out_dir, exist_ok=True)
        out_path = os.path.join(out_dir, "SKILL.md")
        with open(out_path, "w") as f:
            f.write(content)

        print(f"  {cat}: {len(skills)} skills -> {out_path}")

    print(f"\nDone! Generated {len(categories)} category indexes.")


if __name__ == "__main__":
    main()