Initial plan

- P0: Catalog includes nested skills (listSkillIdsRecursive), 626 skills
- P0: update_readme.py regex fixes 'high-performance agentic skills'
- P1: SKILL_ANATOMY risk values aligned to none|safe|critical|offensive (EN + vi)
- P1: requirements.txt + CONTRIBUTING Python setup
- P1: data/package.json version 4.6.0
- P2: npm run test + CI test step; validator docs + validation-baseline in .gitignore
- P3: Installer --version/--tag support; CI npm audit; __pycache__ in .gitignore

.github/ISSUE_49_COMMENT.md

@@ -0,0 +1,15 @@
+Suggested comment for [Issue #49](https://github.com/sickn33/antigravity-awesome-skills/issues/49). Paste this on the issue:
+
+---
+
+The 404 happens because the package wasn’t published to npm yet. We’ve addressed it in two ways:
+
+1. **Publish to npm** – We’re set up to publish so `npx antigravity-awesome-skills` will work after the first release. You can also trigger a manual publish via the “Publish to npm” workflow (Actions tab) if you have `NPM_TOKEN` configured.
+
+2. **Fallback** – Until then (or if you hit a 404 for any reason), use:
+   ```bash
+   npx github:sickn33/antigravity-awesome-skills
+   ```
+   The README, GETTING_STARTED, and FAQ now mention this fallback.
+
+Thanks for reporting.

.github/MAINTENANCE.md

@@ -173,12 +173,22 @@ When cutting a new version (e.g., V4):
 
 1.  **Run Full Validation**: `python3 scripts/validate_skills.py --strict`
 2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
-3.  **Bump Version**: Update header in `README.md`.
+3.  **Bump Version**:
+    - Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
+    - Update version header in `README.md` if it displays the number.
+    - One-liner: `npm version patch` (or `minor`/`major`) — bumps `package.json` and creates a git tag; then amend if you need to tag after release.
 4.  **Tag Release**:
     ```bash
     git tag -a v4.0.0 -m "V4 Enterprise Edition"
     git push origin v4.0.0
     ```
+5.  **Publish to npm** (so `npx antigravity-awesome-skills` works):
+    - **Option A (manual):** From repo root, with npm logged in and 2FA/token set up:
+      ```bash
+      npm publish
+      ```
+      You cannot republish the same version; always bump `package.json` before publishing.
+    - **Option B (CI):** On GitHub, create a **Release** (tag e.g. `v4.6.1`). The workflow [Publish to npm](.github/workflows/publish-npm.yml) runs on **Release published** and runs `npm publish` if the repo secret `NPM_TOKEN` is set (npm → Access Tokens → Granular token with Publish, then add as repo secret `NPM_TOKEN`).
 
 ### 📋 Changelog Entry Template
 

.github/workflows/ci.yml

@@ -45,6 +45,13 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Audit npm dependencies
+        run: npm audit --audit-level=high
+        continue-on-error: true
+
+      - name: Run tests
+        run: npm run test
+
       - name: 📦 Build catalog
         run: npm run catalog
 

.github/workflows/publish-npm.yml

@@ -0,0 +1,28 @@
+# Publish antigravity-awesome-skills to npm on release.
+# Requires NPM_TOKEN secret (npm → Access Tokens → Granular token with Publish).
+# Before creating a Release: bump package.json "version" (npm forbids republishing the same version).
+# Release tag (e.g. v4.6.1) should match package.json version.
+
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,4 +1,6 @@
 node_modules/
+__pycache__/
+.worktrees/
 
 walkthrough.md
 .agent/rules/
@@ -24,3 +26,6 @@ scripts/*voltagent*.py
 scripts/*html*.py
 scripts/*similar*.py
 scripts/*count*.py
+
+# Optional baseline for legacy JS validator (scripts/validate-skills.js)
+validation-baseline.json

CATALOG.md

@@ -1,10 +1,10 @@
 # Skill Catalog
 
-Generated at: 2026-02-01T07:22:00.871Z
+Generated at: 2026-02-03T09:20:12.539Z
 
-Total skills: 619
+Total skills: 626
 
-## architecture (59)
+## architecture (60)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -36,6 +36,7 @@ Total skills: 619
 | `error-handling-patterns` | Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applicatio... | error, handling | error, handling, languages, including, exceptions, result, types, propagation, graceful, degradation, resilient, applications |
 | `event-sourcing-architect` | Expert in event sourcing, CQRS, and event-driven architecture patterns. Masters event store design, projection building, saga orchestration, and eventual con... | event, sourcing | event, sourcing, architect, cqrs, driven, architecture, masters, store, projection, building, saga, orchestration |
 | `event-store-design` | Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implement... | event, store | event, store, stores, sourced, building, sourcing, infrastructure, choosing, technologies, implementing, persistence |
+| `game-development/multiplayer` | Multiplayer game development principles. Architecture, networking, synchronization. | game, development/multiplayer | game, development/multiplayer, multiplayer, development, principles, architecture, networking, synchronization |
 | `godot-gdscript-patterns` | Master Godot 4 GDScript patterns including signals, scenes, state machines, and optimization. Use when building Godot games, implementing game systems, or le... | godot, gdscript | godot, gdscript, including, signals, scenes, state, machines, optimization, building, games, implementing, game |
 | `haskell-pro` | Expert Haskell engineer specializing in advanced type systems, pure functional design, and high-reliability software. Use PROACTIVELY for type-level programm... | haskell | haskell, pro, engineer, specializing, type, pure, functional, high, reliability, software, proactively, level |
 | `i18n-localization` | Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support. | i18n, localization | i18n, localization, internationalization, detecting, hardcoded, strings, managing, translations, locale, files, rtl |
@@ -110,7 +111,7 @@ Total skills: 619
 | `startup-financial-modeling` | This skill should be used when the user asks to "create financial projections", "build a financial model", "forecast revenue", "calculate burn rate", "estima... | startup, financial, modeling | startup, financial, modeling, skill, should, used, user, asks, projections, model, forecast, revenue |
 | `team-composition-analysis` | This skill should be used when the user asks to "plan team structure", "determine hiring needs", "design org chart", "calculate compensation", "plan equity a... | team, composition | team, composition, analysis, skill, should, used, user, asks, plan, structure, determine, hiring |
 
-## data-ai (93)
+## data-ai (92)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -205,10 +206,9 @@ Total skills: 619
 | `voice-ai-development` | Expert in building voice AI applications - from real-time voice agents to voice-enabled apps. Covers OpenAI Realtime API, Vapi for voice agents, Deepgram for... | voice, ai | voice, ai, development, building, applications, real, time, agents, enabled, apps, covers, openai |
 | `voice-ai-engine-development` | Build real-time conversational AI voice engines using async worker pipelines, streaming transcription, LLM agents, and TTS synthesis with interrupt handling ... | voice, ai, engine | voice, ai, engine, development, real, time, conversational, engines, async, worker, pipelines, streaming |
 | `web-artifacts-builder` | Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use ... | web, artifacts, builder | web, artifacts, builder, suite, creating, elaborate, multi, component, claude, ai, html, frontend |
-| `xlsx` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx | xlsx, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work, spreadsheets |
 | `xlsx-official` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx, official | xlsx, official, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work |
 
-## development (80)
+## development (81)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -241,6 +241,7 @@ Total skills: 619
 | `frontend-developer` | Build React components, implement responsive layouts, and handle client-side state management. Masters React 19, Next.js 15, and modern frontend architecture... | frontend | frontend, developer, react, components, responsive, layouts, handle, client, side, state, masters, 19 |
 | `frontend-mobile-development-component-scaffold` | You are a React component architecture expert specializing in scaffolding production-ready, accessible, and performant components. Generate complete componen... | frontend, mobile, component | frontend, mobile, component, development, scaffold, react, architecture, specializing, scaffolding, accessible, performant, components |
 | `frontend-slides` | Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a... | frontend, slides | frontend, slides, stunning, animation, rich, html, presentations, scratch, converting, powerpoint, files, user |
+| `game-development/mobile-games` | Mobile game development principles. Touch input, battery, performance, app stores. | game, development/mobile, games | game, development/mobile, games, mobile, development, principles, touch, input, battery, performance, app, stores |
 | `go-concurrency-patterns` | Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or de... | go, concurrency | go, concurrency, goroutines, channels, sync, primitives, context, building, concurrent, applications, implementing, worker |
 | `golang-pro` | Master Go 1.21+ with modern patterns, advanced concurrency, performance optimization, and production-ready microservices. Expert in the latest Go ecosystem i... | golang | golang, pro, go, 21, concurrency, performance, optimization, microservices, latest, ecosystem, including, generics |
 | `hubspot-integration` | Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers... | hubspot, integration | hubspot, integration, crm, including, oauth, authentication, objects, associations, batch, operations, webhooks, custom |
@@ -294,7 +295,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `viral-generator-builder` | Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers t... | viral, generator, builder | viral, generator, builder, building, shareable, go, name, generators, quiz, makers, avatar, creators |
 | `webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing... | webapp | webapp, testing, toolkit, interacting, local, web, applications, playwright, supports, verifying, frontend, functionality |
 
-## general (122)
+## general (128)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -304,6 +305,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `angular-migration` | Migrate from AngularJS to Angular using hybrid mode, incremental component rewriting, and dependency injection updates. Use when upgrading AngularJS applicat... | angular, migration | angular, migration, migrate, angularjs, hybrid, mode, incremental, component, rewriting, dependency, injection, updates |
 | `anti-reversing-techniques` | Understand anti-reversing, obfuscation, and protection techniques encountered during software analysis. Use when analyzing protected binaries, bypassing anti... | anti, reversing, techniques | anti, reversing, techniques, understand, obfuscation, protection, encountered, during, software, analysis, analyzing, protected |
 | `app-builder` | Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordina... | app, builder | app, builder, main, application, building, orchestrator, creates, full, stack, applications, natural, language |
+| `app-builder/templates` | Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks. | app, builder/templates | app, builder/templates, scaffolding, new, applications, creating, scratch, contains, 12, various, tech, stacks |
 | `arm-cortex-expert` | Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD). Decades of ... | arm, cortex | arm, cortex, senior, embedded, software, engineer, specializing, firmware, driver, development, microcontrollers, teensy |
 | `avalonia-layout-zafiro` | Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy. | avalonia, layout, zafiro | avalonia, layout, zafiro, guidelines, ui, emphasizing, shared, styles, generic, components, avoiding, xaml |
 | `avalonia-zafiro-development` | Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit. | avalonia, zafiro | avalonia, zafiro, development, mandatory, skills, conventions, behavioral, rules, ui, toolkit |
@@ -345,7 +347,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `debugging-toolkit-smart-debug` | Use when working with debugging toolkit smart debug | debugging, debug | debugging, debug, toolkit, smart, working |
 | `design-md` | Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files | md | md, analyze, stitch, synthesize, semantic, files |
 | `dispatching-parallel-agents` | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | dispatching, parallel, agents | dispatching, parallel, agents, facing, independent, tasks, worked, without, shared, state, sequential, dependencies |
-| `docx` | Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude ... | docx | docx, document, creation, editing, analysis, tracked, changes, comments, formatting, preservation, text, extraction |
 | `docx-official` | Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude ... | docx, official | docx, official, document, creation, editing, analysis, tracked, changes, comments, formatting, preservation, text |
 | `dx-optimizer` | Developer Experience specialist. Improves tooling, setup, and workflows. Use PROACTIVELY when setting up new projects, after team feedback, or when developme... | dx, optimizer | dx, optimizer, developer, experience, improves, tooling, setup, proactively, setting, up, new, after |
 | `environment-setup-guide` | Guide developers through setting up development environments with proper tools, dependencies, and configurations | environment, setup | environment, setup, developers, through, setting, up, development, environments, proper, dependencies, configurations |
@@ -360,6 +361,13 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `fix-review` | Verify fix commits address audit findings without new bugs | fix | fix, review, verify, commits, address, audit, findings, without, new, bugs |
 | `framework-migration-code-migrate` | You are a code migration expert specializing in transitioning codebases between frameworks, languages, versions, and platforms. Generate comprehensive migrat... | framework, migration, code, migrate | framework, migration, code, migrate, specializing, transitioning, codebases, between, frameworks, languages, versions, platforms |
 | `game-development` | Game development orchestrator. Routes to platform-specific skills based on project needs. | game | game, development, orchestrator, routes, platform, specific, skills |
+| `game-development/2d-games` | 2D game development principles. Sprites, tilemaps, physics, camera. | game, development/2d, games | game, development/2d, games, 2d, development, principles, sprites, tilemaps, physics, camera |
+| `game-development/3d-games` | 3D game development principles. Rendering, shaders, physics, cameras. | game, development/3d, games | game, development/3d, games, 3d, development, principles, rendering, shaders, physics, cameras |
+| `game-development/game-audio` | Game audio principles. Sound design, music integration, adaptive audio systems. | game, development/game, audio | game, development/game, audio, principles, sound, music, integration, adaptive |
+| `game-development/game-design` | Game design principles. GDD structure, balancing, player psychology, progression. | game, development/game | game, development/game, principles, gdd, structure, balancing, player, psychology, progression |
+| `game-development/pc-games` | PC and console game development principles. Engine selection, platform features, optimization strategies. | game, development/pc, games | game, development/pc, games, pc, console, development, principles, engine, selection, platform, features, optimization |
+| `game-development/vr-ar` | VR/AR development principles. Comfort, interaction, performance requirements. | game, development/vr, ar | game, development/vr, ar, vr, development, principles, comfort, interaction, performance, requirements |
+| `game-development/web-games` | Web browser game development principles. Framework selection, WebGPU, optimization, PWA. | game, development/web, games | game, development/web, games, web, browser, development, principles, framework, selection, webgpu, optimization, pwa |
 | `git-advanced-workflows` | Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use... | git, advanced | git, advanced, including, rebasing, cherry, picking, bisect, worktrees, reflog, maintain, clean, history |
 | `git-pr-workflows-onboard` | You are an **expert onboarding specialist and knowledge transfer architect** with deep experience in remote-first organizations, technical team integration, ... | git, pr, onboard | git, pr, onboard, onboarding, knowledge, transfer, architect, deep, experience, remote, first, organizations |
 | `git-pr-workflows-pr-enhance` | You are a PR optimization expert specializing in creating high-quality pull requests that facilitate efficient code reviews. Generate comprehensive PR descri... | git, pr, enhance | git, pr, enhance, optimization, specializing, creating, high, quality, pull, requests, facilitate, efficient |
@@ -386,7 +394,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `plan-writing` | Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work. | plan, writing | plan, writing, structured, task, planning, clear, breakdowns, dependencies, verification, criteria, implementing, features |
 | `planning-with-files` | Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks,... | planning, with, files | planning, with, files, implements, manus, style, file, complex, tasks, creates, task, plan |
 | `posix-shell-pro` | Expert in strict POSIX sh scripting for maximum portability across Unix-like systems. Specializes in shell scripts that run on any POSIX-compliant shell (das... | posix, shell | posix, shell, pro, strict, sh, scripting, maximum, portability, unix, like, specializes, scripts |
-| `pptx` | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying o... | pptx | pptx, presentation, creation, editing, analysis, claude, work, presentations, files, creating, new, modifying |
 | `pptx-official` | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying o... | pptx, official | pptx, official, presentation, creation, editing, analysis, claude, work, presentations, files, creating, new |
 | `privilege-escalation-methods` | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploi... | privilege, escalation, methods | privilege, escalation, methods, skill, should, used, user, asks, escalate, privileges, get, root |
 | `prompt-library` | Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use... | prompt, library | prompt, library, curated, collection, high, quality, prompts, various, cases, includes, role, task |
@@ -421,7 +428,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `writing-skills` | Use when creating, updating, or improving agent skills. | writing, skills | writing, skills, creating, updating, improving, agent |
 | `x-article-publisher-skill` | Publish articles to X/Twitter | x, article, publisher, skill | x, article, publisher, skill, publish, articles, twitter |
 
-## infrastructure (77)
+## infrastructure (78)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -458,6 +465,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `expo-deployment` | Deploy Expo apps to production | expo, deployment | expo, deployment, deploy, apps |
 | `file-uploads` | Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle l... | file, uploads | file, uploads, handling, cloud, storage, covers, s3, cloudflare, r2, presigned, urls, multipart |
 | `flutter-expert` | Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment. Handles state management, animations, testing, and performance optim... | flutter | flutter, development, dart, widgets, multi, platform, deployment, state, animations, testing, performance, optimization |
+| `game-development/game-art` | Game art principles. Visual style selection, asset pipeline, animation workflow. | game, development/game, art | game, development/game, art, principles, visual, style, selection, asset, pipeline, animation |
 | `gcp-cloud-run` | Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven)... | gcp, cloud, run | gcp, cloud, run, specialized, skill, building, serverless, applications, covers, containerized, functions, event |
 | `git-pr-workflows-git-workflow` | Orchestrate a comprehensive git workflow from code review through PR creation, leveraging specialized agents for quality assurance, testing, and deployment r... | git, pr | git, pr, orchestrate, code, review, through, creation, leveraging, specialized, agents, quality, assurance |
 | `github-actions-templates` | Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, ... | github, actions | github, actions, automated, testing, building, deploying, applications, setting, up, ci, cd, automating |
@@ -647,7 +655,7 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `unit-testing-test-generate` | Generate comprehensive, maintainable unit tests across languages with strong coverage and edge case focus. | unit, generate | unit, generate, testing, test, maintainable, tests, languages, strong, coverage, edge, case |
 | `web3-testing` | Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, ... | web3 | web3, testing, test, smart, contracts, comprehensively, hardhat, foundry, unit, tests, integration, mainnet |
 
-## workflow (17)
+## workflow (16)
 
 | Skill | Description | Tags | Triggers |
 | --- | --- | --- | --- |
@@ -664,7 +672,6 @@ TRIGGER: "shopify", "shopify app", "checkout extension",... | shopify | shopify,
 | `git-pushing` | Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to... | git, pushing | git, pushing, stage, commit, push, changes, conventional, messages, user, wants, mentions, remote |
 | `kaizen` | Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss proce... | kaizen | kaizen, continuous, improvement, error, proofing, standardization, skill, user, wants, improve, code, quality |
 | `mermaid-expert` | Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling. Use PROACTIVELY for visual docu... | mermaid | mermaid, diagrams, flowcharts, sequences, erds, architectures, masters, syntax, all, diagram, types, styling |
-| `pdf` | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs ... | pdf | pdf, manipulation, toolkit, extracting, text, tables, creating, new, pdfs, merging, splitting, documents |
 | `pdf-official` | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs ... | pdf, official | pdf, official, manipulation, toolkit, extracting, text, tables, creating, new, pdfs, merging, splitting |
 | `team-collaboration-issue` | You are a GitHub issue resolution expert specializing in systematic bug investigation, feature implementation, and collaborative development workflows. Your ... | team, collaboration, issue | team, collaboration, issue, github, resolution, specializing, systematic, bug, investigation, feature, collaborative, development |
 | `track-management` | Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan... | track | track, skill, creating, managing, working, conductor, tracks, logical, work, units, features, bugs |

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.7.0] - 2026-02-03 - "Installer Fix & OpenCode Docs"
+
+> Critical installer fix for Windows and OpenCode documentation completion.
+
+### Fixed
+
+- **Installer**: Resolved `ReferenceError` for `tagArg` variable in `bin/install.js` ensuring correct execution on Windows/PowerShell (PR #53).
+
+### Documentation
+
+- **OpenCode**: Completed documentation for OpenCode integration in `README.md`.
+
+---
+
 ## [4.6.0] - 2026-02-01 - "SPDD & Radix UI Design System"
 
 > Agent workflow docs (SPDD) and Radix UI design system skill.

CONTRIBUTING.md

@@ -48,6 +48,23 @@ You don't need to be an expert! Here are ways anyone can help:
 
 ---
 
+## Local development setup
+
+To run validation, index generation, and README updates locally:
+
+1. **Node.js** (for catalog and installer): `npm ci`
+2. **Python 3** (for validate, index, readme scripts): install dependencies with
+   ```bash
+   pip install -r requirements.txt
+   ```
+   Then you can run `npm run chain` (validate → index → readme) and `npm run catalog`.
+
+**Validation:** The canonical validator is **Python** (`scripts/validate_skills.py`). Use `npm run validate` (or `npm run validate:strict` for CI-style checks). The JavaScript validator (`scripts/validate-skills.js`) is legacy/optional and uses a different schema; CI and PR checks rely on the Python validator only.
+
+**npm audit:** CI runs `npm audit --audit-level=high`. To fix issues locally: run `npm audit`, then `npm update` or `npm audit fix` as appropriate; for breaking changes, update dependencies manually and run tests.
+
+---
+
 ## How to Create a New Skill
 
 ### Step-by-Step Guide

README.md

@@ -1,6 +1,6 @@
 # 🌌 Antigravity Awesome Skills: 626+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
 
-> **The Ultimate Collection of 626+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
+> **The Ultimate Collection of 626+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai)
@@ -10,6 +10,7 @@
 [![Copilot](https://img.shields.io/badge/GitHub%20Copilot-VSCode-lightblue)](https://github.com/features/copilot)
 [![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray)](https://github.com/opencode-ai/opencode)
 [![Antigravity](https://img.shields.io/badge/Antigravity-DeepMind-red)](https://github.com/sickn33/antigravity-awesome-skills)
+[![AdaL](https://img.shields.io/badge/AdaL-Self--evolving%20Agent-pink)](https://github.com/HumanSignal/Adala)
 
 **Antigravity Awesome Skills** is a curated, battle-tested library of **626 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
 
@@ -20,6 +21,7 @@
 - 🩵 **GitHub Copilot** (VSCode Extension)
 - 🟠 **Cursor** (AI-native IDE)
 - ⚪ **OpenCode** (Open-source CLI)
+- 🌸 **AdaL** (Self-evolving AI Agent)
 
 This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, **Supabase**, and **Vercel Labs**.
 
@@ -55,6 +57,7 @@ AI Agents (like Claude Code, Cursor, or Gemini) are smart, but they lack **speci
 Install once (clone or npx); then use our **Starter Packs** in [docs/BUNDLES.md](docs/BUNDLES.md) to see which skills fit your role. You get the full repo; Starter Packs are curated lists, not a separate install.
 
 1.  **Install** (pick one):
+
     ```bash
     # Easiest: npx installer (clones to ~/.agent/skills by default)
     npx antigravity-awesome-skills
@@ -62,6 +65,7 @@ Install once (clone or npx); then use our **Starter Packs** in [docs/BUNDLES.md]
     # Or clone manually
     git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
     ```
+
 2.  **Pick your persona** (See [docs/BUNDLES.md](docs/BUNDLES.md)):
     - **Web Dev?** use the `Web Wizard` pack.
     - **Hacker?** use the `Security Engineer` pack.
@@ -82,13 +86,16 @@ Once installed, just ask your agent naturally:
 
 These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills.
 
-| Tool            | Type | Invocation Example                | Path              |
-| :-------------- | :--- | :-------------------------------- | :---------------- |
-| **Claude Code** | CLI  | `>> /skill-name help me...`       | `.claude/skills/` |
-| **Gemini CLI**  | CLI  | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
-| **Antigravity** | IDE  | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
-| **Cursor**      | IDE  | `@skill-name (in Chat)`           | `.cursor/skills/` |
-| **Copilot**     | Ext  | `(Paste content manually)`        | N/A               |
+| Tool            | Type  | Invocation Example                | Path              |
+| :-------------- | :---- | :-------------------------------- | :---------------- |
+| **Claude Code** | CLI   | `>> /skill-name help me...`       | `.claude/skills/` |
+| **Gemini CLI**  | CLI   | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
+| **Codex CLI**   | CLI   | `(User Prompt) Use skill-name...` | `.codex/skills/`  |
+| **Antigravity** | IDE   | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
+| **Cursor**      | IDE   | `@skill-name (in Chat)`           | `.cursor/skills/` |
+| **Copilot**     | Ext   | `(Paste content manually)`        | N/A               |
+| **OpenCode**    | CLI   | `opencode run @skill-name`        | `.agent/skills/`  |
+| **AdaL**        | Agent | `(Agent Mode) Use skill...`       | `.agent/skills/`  |
 
 > [!TIP]
 > **Universal Path**: We recommend cloning to `.agent/skills/`. Most modern tools (Antigravity, recent CLIs) look here by default.
@@ -100,7 +107,7 @@ These skills follow the universal **SKILL.md** format and work with any AI codin
 
 ---
 
-Whether you are using **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, or **OpenCode**, these skills are designed to drop right in and supercharge your AI agent.
+Whether you are using **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, **OpenCode**, or **AdaL**, these skills are designed to drop right in and supercharge your AI agent.
 
 This repository aggregates the best capabilities from across the open-source community, transforming your AI assistant into a full-stack digital agency capable of Engineering, Design, Security, Marketing, and Autonomous Operations.
 
@@ -108,17 +115,17 @@ This repository aggregates the best capabilities from across the open-source com
 
 The repository is organized into specialized domains to transform your AI into an expert across the entire software development lifecycle:
 
-| Category | Focus | Example skills |
-| :--- | :--- | :--- |
-| Architecture (52) | System design, ADRs, C4, and scalable patterns | `architecture`, `c4-context`, `senior-architect` |
-| Business (35) | Growth, pricing, CRO, SEO, and go-to-market | `copywriting`, `pricing-strategy`, `seo-audit` |
-| Data & AI (81) | LLM apps, RAG, agents, observability, analytics | `rag-engineer`, `prompt-engineer`, `langgraph` |
-| Development (72) | Language mastery, framework patterns, code quality | `typescript-expert`, `python-patterns`, `react-patterns` |
-| General (95) | Planning, docs, product ops, writing, guidelines | `brainstorming`, `doc-coauthoring`, `writing-plans` |
-| Infrastructure (72) | DevOps, cloud, serverless, deployment, CI/CD | `docker-expert`, `aws-serverless`, `vercel-deployment` |
-| Security (107) | AppSec, pentesting, vuln analysis, compliance | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` |
-| Testing (21) | TDD, test design, fixes, QA workflows | `test-driven-development`, `testing-patterns`, `test-fixing` |
-| Workflow (17) | Automation, orchestration, jobs, agents | `workflow-automation`, `inngest`, `trigger-dev` |
+| Category            | Focus                                              | Example skills                                                                  |
+| :------------------ | :------------------------------------------------- | :------------------------------------------------------------------------------ |
+| Architecture (52)   | System design, ADRs, C4, and scalable patterns     | `architecture`, `c4-context`, `senior-architect`                                |
+| Business (35)       | Growth, pricing, CRO, SEO, and go-to-market        | `copywriting`, `pricing-strategy`, `seo-audit`                                  |
+| Data & AI (81)      | LLM apps, RAG, agents, observability, analytics    | `rag-engineer`, `prompt-engineer`, `langgraph`                                  |
+| Development (72)    | Language mastery, framework patterns, code quality | `typescript-expert`, `python-patterns`, `react-patterns`                        |
+| General (95)        | Planning, docs, product ops, writing, guidelines   | `brainstorming`, `doc-coauthoring`, `writing-plans`                             |
+| Infrastructure (72) | DevOps, cloud, serverless, deployment, CI/CD       | `docker-expert`, `aws-serverless`, `vercel-deployment`                          |
+| Security (107)      | AppSec, pentesting, vuln analysis, compliance      | `api-security-best-practices`, `sql-injection-testing`, `vulnerability-scanner` |
+| Testing (21)        | TDD, test design, fixes, QA workflows              | `test-driven-development`, `testing-patterns`, `test-fixing`                    |
+| Workflow (17)       | Automation, orchestration, jobs, agents            | `workflow-automation`, `inngest`, `trigger-dev`                                 |
 
 ## Curated Collections
 
@@ -132,7 +139,7 @@ We have moved the full skill registry to a dedicated catalog to keep this README
 
 ## Installation
 
-To use these skills with **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, or **OpenCode**:
+To use these skills with **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, **OpenCode**, or **AdaL**:
 
 ### Option A: npx (recommended)
 
@@ -149,12 +156,20 @@ npx antigravity-awesome-skills --claude
 # Gemini CLI
 npx antigravity-awesome-skills --gemini
 
+# Codex CLI
+npx antigravity-awesome-skills --codex
+
+# OpenCode (Universal)
+npx antigravity-awesome-skills
+
 # Custom path
 npx antigravity-awesome-skills --path ./my-skills
 ```
 
 Run `npx antigravity-awesome-skills --help` for all options. If the directory already exists, the installer runs `git pull` to update.
 
+> **If you see a 404 error:** the package may not be published to npm yet. Use: `npx github:sickn33/antigravity-awesome-skills`
+
 ### Option B: git clone
 
 ```bash
@@ -167,8 +182,14 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skil
 # Gemini CLI specific
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills
 
+# Codex CLI specific
+git clone https://github.com/sickn33/antigravity-awesome-skills.git .codex/skills
+
 # Cursor specific
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills
+
+# OpenCode specific (Universal path)
+git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
 ```
 
 ---
@@ -267,34 +288,47 @@ ai-developer-tools, ai-pair-programming, vibe-coding, skill, skills, SKILL.md, r
 
 ## Repo Contributors
 
+<a href="https://github.com/sickn33/antigravity-awesome-skills/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=sickn33/antigravity-awesome-skills" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
 We officially thank the following contributors for their help in making this repository awesome!
 
-- [mvanhorn](https://github.com/mvanhorn)
-- [rookie-ricardo](https://github.com/rookie-ricardo)
-- [sck_0](https://github.com/sck_0)
-- [Munir Abbasi](https://github.com/munirabbasi)
-- [Mohammad Faiz](https://github.com/mohdfaiz2k9)
-- [Ianj332](https://github.com/Ianj332)
+- [sck_0](https://github.com/sck000)
+- [Munir Abbasi](https://github.com/munir-abbasi)
 - [sickn33](https://github.com/sickn33)
+- [Mohammad Faiz](https://github.com/Mohammad-Faiz-Cloud-Engineer)
+- [Đỗ Khắc Gia Khoa](https://github.com/Dokhacgiakhoa)
+- [Ianj332](https://github.com/IanJ332)
 - [GuppyTheCat](https://github.com/GuppyTheCat)
 - [Tiger-Foxx](https://github.com/Tiger-Foxx)
 - [arathiesh](https://github.com/arathiesh)
 - [1bcMax](https://github.com/1bcMax)
+- [ALEKGG1](https://github.com/ALEKGG1)
 - [Ahmed Rehan](https://github.com/ar27111994)
 - [BenedictKing](https://github.com/BenedictKing)
+- [whatiskadudoing](https://github.com/whatiskadudoing)
 - [Nguyen Huu Loc](https://github.com/LocNguyenSGU)
 - [Owen Wu](https://github.com/yubing744)
 - [SuperJMN](https://github.com/SuperJMN)
+- [Truong Nguyen](https://github.com/truongnmt)
 - [Viktor Ferenczi](https://github.com/viktor-ferenczi)
-- [Đỗ Khắc Gia Khoa](https://github.com/Dokhacgiakhoa)
-- [evandro-miguel](https://github.com/evandro-miguel)
+- [c1c3ru](https://github.com/c1c3ru)
+- [ckdwns9121](https://github.com/ckdwns9121)
 - [junited31](https://github.com/junited31)
-- [krisnasantosa15](https://github.com/krisnasantosa15)
-- [raeef1001](https://github.com/raeef1001)
+- [liyin2015](https://github.com/liyin2015)
+- [krisnasantosa15](https://github.com/KrisnaSantosa15)
+- [sstklen](https://github.com/sstklen)
 - [taksrules](https://github.com/taksrules)
 - [zebbern](https://github.com/zebbern)
 - [vuth-dogo](https://github.com/vuth-dogo)
-- [whatiskadudoing](https://github.com/whatiskadudoing)
+- [mvanhorn](https://github.com/mvanhorn)
+- [rookie-ricardo](https://github.com/rookie-ricardo)
+- [evandro-miguel](https://github.com/evandro-miguel)
+- [raeef1001](https://github.com/raeef1001)
+- [devchangjun](https://github.com/devchangjun)
 
 ## Star History
 

bin/install.js

@@ -16,18 +16,23 @@ function resolveDir(p) {
 function parseArgs() {
   const a = process.argv.slice(2);
   let pathArg = null;
-  let cursor = false, claude = false, gemini = false;
+  let versionArg = null;
+  let tagArg = null;
+  let cursor = false, claude = false, gemini = false, codex = false;
 
   for (let i = 0; i < a.length; i++) {
     if (a[i] === '--help' || a[i] === '-h') return { help: true };
     if (a[i] === '--path' && a[i + 1]) { pathArg = a[++i]; continue; }
+    if (a[i] === '--version' && a[i + 1]) { versionArg = a[++i]; continue; }
+    if (a[i] === '--tag' && a[i + 1]) { tagArg = a[++i]; continue; }
     if (a[i] === '--cursor') { cursor = true; continue; }
     if (a[i] === '--claude') { claude = true; continue; }
     if (a[i] === '--gemini') { gemini = true; continue; }
+    if (a[i] === '--codex') { codex = true; continue; }
     if (a[i] === 'install') continue;
   }
 
-  return { pathArg, cursor, claude, gemini };
+  return { pathArg, versionArg, tagArg, cursor, claude, gemini, codex };
 }
 
 function defaultDir(opts) {
@@ -35,6 +40,11 @@ function defaultDir(opts) {
   if (opts.cursor) return path.join(HOME, '.cursor', 'skills');
   if (opts.claude) return path.join(HOME, '.claude', 'skills');
   if (opts.gemini) return path.join(HOME, '.gemini', 'skills');
+  if (opts.codex) {
+    const codexHome = process.env.CODEX_HOME;
+    if (codexHome) return path.join(codexHome, 'skills');
+    return path.join(HOME, '.codex', 'skills');
+  }
   return path.join(HOME, '.agent', 'skills');
 }
 
@@ -50,11 +60,15 @@ Options:
   --cursor    Install to ~/.cursor/skills (Cursor)
   --claude    Install to ~/.claude/skills (Claude Code)
   --gemini    Install to ~/.gemini/skills (Gemini CLI)
+  --codex     Install to ~/.codex/skills (Codex CLI)
   --path <dir> Install to <dir> (default: ~/.agent/skills)
+  --version <ver>  After clone, checkout tag v<ver> (e.g. 4.6.0 -> v4.6.0)
+  --tag <tag>      After clone, checkout this tag (e.g. v4.6.0)
 
 Examples:
   npx antigravity-awesome-skills
   npx antigravity-awesome-skills --cursor
+  npx antigravity-awesome-skills --version 4.6.0
   npx antigravity-awesome-skills --path ./my-skills
 `);
 }
@@ -66,6 +80,8 @@ function run(cmd, args, opts = {}) {
 
 function main() {
   const opts = parseArgs();
+  const { tagArg, versionArg } = opts;
+  
   if (opts.help) {
     printHelp();
     return;
@@ -106,6 +122,13 @@ function main() {
     run('git', ['clone', REPO, target]);
   }
 
+  const ref = tagArg || (versionArg ? (versionArg.startsWith('v') ? versionArg : `v${versionArg}`) : null);
+  if (ref) {
+    console.log(`Checking out ${ref}…`);
+    process.chdir(target);
+    run('git', ['checkout', ref]);
+  }
+
   console.log(`\nInstalled to ${target}`);
   console.log('Pick a bundle in docs/BUNDLES.md and use @skill-name in your AI assistant.');
 }

data/aliases.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-02-01T07:22:00.871Z",
+  "generatedAt": "2026-02-03T09:20:12.539Z",
   "aliases": {
     "accessibility-compliance-audit": "accessibility-compliance-accessibility-audit",
     "active directory attacks": "active-directory-attacks",
@@ -7,6 +7,7 @@
     "agent-orchestration-optimize": "agent-orchestration-multi-agent-optimize",
     "api fuzzing for bug bounty": "api-fuzzing-bug-bounty",
     "api-testing-mock": "api-testing-observability-api-mock",
+    "templates": "app-builder/templates",
     "application-performance-optimization": "application-performance-performance-optimization",
     "aws penetration testing": "aws-penetration-testing",
     "backend-development-feature": "backend-development-feature-development",
@@ -45,6 +46,7 @@
     "deployment-validation-validate": "deployment-validation-config-validate",
     "distributed-debugging-trace": "distributed-debugging-debug-trace",
     "documentation-generation-generate": "documentation-generation-doc-generate",
+    "docx": "docx-official",
     "error-debugging-analysis": "error-debugging-error-analysis",
     "error-debugging-review": "error-debugging-multi-agent-review",
     "error-diagnostics-analysis": "error-diagnostics-error-analysis",
@@ -59,6 +61,16 @@
     "frontend-mobile-scaffold": "frontend-mobile-development-component-scaffold",
     "frontend-mobile-scan": "frontend-mobile-security-xss-scan",
     "full-stack-feature": "full-stack-orchestration-full-stack-feature",
+    "2d-games": "game-development/2d-games",
+    "3d-games": "game-development/3d-games",
+    "game-art": "game-development/game-art",
+    "game-audio": "game-development/game-audio",
+    "game-design": "game-development/game-design",
+    "mobile-games": "game-development/mobile-games",
+    "multiplayer": "game-development/multiplayer",
+    "pc-games": "game-development/pc-games",
+    "vr-ar": "game-development/vr-ar",
+    "web-games": "game-development/web-games",
     "git-pr-workflow": "git-pr-workflows-git-workflow",
     "html injection testing": "html-injection-testing",
     "idor vulnerability testing": "idor-testing",
@@ -79,11 +91,13 @@
     "observability-monitoring-setup": "observability-monitoring-monitor-setup",
     "observability-monitoring-implement": "observability-monitoring-slo-implement",
     "obsidian-clipper-creator": "obsidian-clipper-template-creator",
+    "pdf": "pdf-official",
     "pentest checklist": "pentest-checklist",
     "pentest commands": "pentest-commands",
     "performance-testing-ai": "performance-testing-review-ai-review",
     "performance-testing-agent": "performance-testing-review-multi-agent-review",
     "supabase-postgres-best-practices": "postgres-best-practices",
+    "pptx": "pptx-official",
     "privilege escalation methods": "privilege-escalation-methods",
     "python-development-scaffold": "python-development-python-scaffold",
     "vercel-react-best-practices": "react-best-practices",
@@ -107,6 +121,7 @@
     "windows privilege escalation": "windows-privilege-escalation",
     "wireshark network traffic analysis": "wireshark-analysis",
     "wordpress penetration testing": "wordpress-penetration-testing",
+    "xlsx": "xlsx-official",
     "cross-site scripting and html injection testing": "xss-html-injection"
   }
 }

data/bundles.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-02-01T07:22:00.871Z",
+  "generatedAt": "2026-02-03T09:20:12.539Z",
   "bundles": {
     "core-dev": {
       "description": "Core development skills across languages, frameworks, and backend/frontend fundamentals.",
@@ -55,6 +55,7 @@
         "frontend-mobile-security-xss-scan",
         "frontend-security-coder",
         "frontend-slides",
+        "game-development/mobile-games",
         "go-concurrency-patterns",
         "golang-pro",
         "graphql",
@@ -319,7 +320,6 @@
         "unity-ecs-patterns",
         "using-neon",
         "vector-database-engineer",
-        "xlsx",
         "xlsx-official"
       ]
     },
@@ -357,6 +357,7 @@
         "error-diagnostics-error-trace",
         "expo-deployment",
         "flutter-expert",
+        "game-development/game-art",
         "git-pr-workflows-git-workflow",
         "gitlab-ci-patterns",
         "gitops-workflow",

data/catalog.json

@@ -1,6 +1,6 @@
 {
-  "generatedAt": "2026-02-01T07:22:00.871Z",
-  "total": 619,
+  "generatedAt": "2026-02-03T09:20:12.539Z",
+  "total": 626,
   "skills": [
     {
       "id": "3d-web-experience",
@@ -760,6 +760,31 @@
       ],
       "path": "skills/app-builder/SKILL.md"
     },
+    {
+      "id": "app-builder/templates",
+      "name": "templates",
+      "description": "Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks.",
+      "category": "general",
+      "tags": [
+        "app",
+        "builder/templates"
+      ],
+      "triggers": [
+        "app",
+        "builder/templates",
+        "scaffolding",
+        "new",
+        "applications",
+        "creating",
+        "scratch",
+        "contains",
+        "12",
+        "various",
+        "tech",
+        "stacks"
+      ],
+      "path": "skills/app-builder/templates/SKILL.md"
+    },
     {
       "id": "app-store-optimization",
       "name": "app-store-optimization",
@@ -4778,30 +4803,6 @@
       ],
       "path": "skills/documentation-templates/SKILL.md"
     },
-    {
-      "id": "docx",
-      "name": "docx",
-      "description": "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks",
-      "category": "general",
-      "tags": [
-        "docx"
-      ],
-      "triggers": [
-        "docx",
-        "document",
-        "creation",
-        "editing",
-        "analysis",
-        "tracked",
-        "changes",
-        "comments",
-        "formatting",
-        "preservation",
-        "text",
-        "extraction"
-      ],
-      "path": "skills/docx/SKILL.md"
-    },
     {
       "id": "docx-official",
       "name": "docx",
@@ -6272,6 +6273,245 @@
       ],
       "path": "skills/game-development/SKILL.md"
     },
+    {
+      "id": "game-development/2d-games",
+      "name": "2d-games",
+      "description": "2D game development principles. Sprites, tilemaps, physics, camera.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/2d",
+        "games"
+      ],
+      "triggers": [
+        "game",
+        "development/2d",
+        "games",
+        "2d",
+        "development",
+        "principles",
+        "sprites",
+        "tilemaps",
+        "physics",
+        "camera"
+      ],
+      "path": "skills/game-development/2d-games/SKILL.md"
+    },
+    {
+      "id": "game-development/3d-games",
+      "name": "3d-games",
+      "description": "3D game development principles. Rendering, shaders, physics, cameras.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/3d",
+        "games"
+      ],
+      "triggers": [
+        "game",
+        "development/3d",
+        "games",
+        "3d",
+        "development",
+        "principles",
+        "rendering",
+        "shaders",
+        "physics",
+        "cameras"
+      ],
+      "path": "skills/game-development/3d-games/SKILL.md"
+    },
+    {
+      "id": "game-development/game-art",
+      "name": "game-art",
+      "description": "Game art principles. Visual style selection, asset pipeline, animation workflow.",
+      "category": "infrastructure",
+      "tags": [
+        "game",
+        "development/game",
+        "art"
+      ],
+      "triggers": [
+        "game",
+        "development/game",
+        "art",
+        "principles",
+        "visual",
+        "style",
+        "selection",
+        "asset",
+        "pipeline",
+        "animation"
+      ],
+      "path": "skills/game-development/game-art/SKILL.md"
+    },
+    {
+      "id": "game-development/game-audio",
+      "name": "game-audio",
+      "description": "Game audio principles. Sound design, music integration, adaptive audio systems.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/game",
+        "audio"
+      ],
+      "triggers": [
+        "game",
+        "development/game",
+        "audio",
+        "principles",
+        "sound",
+        "music",
+        "integration",
+        "adaptive"
+      ],
+      "path": "skills/game-development/game-audio/SKILL.md"
+    },
+    {
+      "id": "game-development/game-design",
+      "name": "game-design",
+      "description": "Game design principles. GDD structure, balancing, player psychology, progression.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/game"
+      ],
+      "triggers": [
+        "game",
+        "development/game",
+        "principles",
+        "gdd",
+        "structure",
+        "balancing",
+        "player",
+        "psychology",
+        "progression"
+      ],
+      "path": "skills/game-development/game-design/SKILL.md"
+    },
+    {
+      "id": "game-development/mobile-games",
+      "name": "mobile-games",
+      "description": "Mobile game development principles. Touch input, battery, performance, app stores.",
+      "category": "development",
+      "tags": [
+        "game",
+        "development/mobile",
+        "games"
+      ],
+      "triggers": [
+        "game",
+        "development/mobile",
+        "games",
+        "mobile",
+        "development",
+        "principles",
+        "touch",
+        "input",
+        "battery",
+        "performance",
+        "app",
+        "stores"
+      ],
+      "path": "skills/game-development/mobile-games/SKILL.md"
+    },
+    {
+      "id": "game-development/multiplayer",
+      "name": "multiplayer",
+      "description": "Multiplayer game development principles. Architecture, networking, synchronization.",
+      "category": "architecture",
+      "tags": [
+        "game",
+        "development/multiplayer"
+      ],
+      "triggers": [
+        "game",
+        "development/multiplayer",
+        "multiplayer",
+        "development",
+        "principles",
+        "architecture",
+        "networking",
+        "synchronization"
+      ],
+      "path": "skills/game-development/multiplayer/SKILL.md"
+    },
+    {
+      "id": "game-development/pc-games",
+      "name": "pc-games",
+      "description": "PC and console game development principles. Engine selection, platform features, optimization strategies.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/pc",
+        "games"
+      ],
+      "triggers": [
+        "game",
+        "development/pc",
+        "games",
+        "pc",
+        "console",
+        "development",
+        "principles",
+        "engine",
+        "selection",
+        "platform",
+        "features",
+        "optimization"
+      ],
+      "path": "skills/game-development/pc-games/SKILL.md"
+    },
+    {
+      "id": "game-development/vr-ar",
+      "name": "vr-ar",
+      "description": "VR/AR development principles. Comfort, interaction, performance requirements.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/vr",
+        "ar"
+      ],
+      "triggers": [
+        "game",
+        "development/vr",
+        "ar",
+        "vr",
+        "development",
+        "principles",
+        "comfort",
+        "interaction",
+        "performance",
+        "requirements"
+      ],
+      "path": "skills/game-development/vr-ar/SKILL.md"
+    },
+    {
+      "id": "game-development/web-games",
+      "name": "web-games",
+      "description": "Web browser game development principles. Framework selection, WebGPU, optimization, PWA.",
+      "category": "general",
+      "tags": [
+        "game",
+        "development/web",
+        "games"
+      ],
+      "triggers": [
+        "game",
+        "development/web",
+        "games",
+        "web",
+        "browser",
+        "development",
+        "principles",
+        "framework",
+        "selection",
+        "webgpu",
+        "optimization",
+        "pwa"
+      ],
+      "path": "skills/game-development/web-games/SKILL.md"
+    },
     {
       "id": "gcp-cloud-run",
       "name": "gcp-cloud-run",
@@ -9604,30 +9844,6 @@
       ],
       "path": "skills/pci-compliance/SKILL.md"
     },
-    {
-      "id": "pdf",
-      "name": "pdf",
-      "description": "Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.",
-      "category": "workflow",
-      "tags": [
-        "pdf"
-      ],
-      "triggers": [
-        "pdf",
-        "manipulation",
-        "toolkit",
-        "extracting",
-        "text",
-        "tables",
-        "creating",
-        "new",
-        "pdfs",
-        "merging",
-        "splitting",
-        "documents"
-      ],
-      "path": "skills/pdf/SKILL.md"
-    },
     {
       "id": "pdf-official",
       "name": "pdf",
@@ -10086,30 +10302,6 @@
       ],
       "path": "skills/powershell-windows/SKILL.md"
     },
-    {
-      "id": "pptx",
-      "name": "pptx",
-      "description": "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks",
-      "category": "general",
-      "tags": [
-        "pptx"
-      ],
-      "triggers": [
-        "pptx",
-        "presentation",
-        "creation",
-        "editing",
-        "analysis",
-        "claude",
-        "work",
-        "presentations",
-        "files",
-        "creating",
-        "new",
-        "modifying"
-      ],
-      "path": "skills/pptx/SKILL.md"
-    },
     {
       "id": "pptx-official",
       "name": "pptx",
@@ -14971,30 +15163,6 @@
       ],
       "path": "skills/x-article-publisher-skill/SKILL.md"
     },
-    {
-      "id": "xlsx",
-      "name": "xlsx",
-      "description": "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas",
-      "category": "data-ai",
-      "tags": [
-        "xlsx"
-      ],
-      "triggers": [
-        "xlsx",
-        "spreadsheet",
-        "creation",
-        "editing",
-        "analysis",
-        "formulas",
-        "formatting",
-        "data",
-        "visualization",
-        "claude",
-        "work",
-        "spreadsheets"
-      ],
-      "path": "skills/xlsx/SKILL.md"
-    },
     {
       "id": "xlsx-official",
       "name": "xlsx",

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-awesome-skills",
-  "version": "4.2.0",
+  "version": "4.6.0",
   "dependencies": {
     "yaml": "^2.8.2"
   }

docs/FAQ.md

@@ -11,7 +11,7 @@
 Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
 **Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.
 
-### Do I need to install all 624+ skills?
+### Do I need to install all 626+ skills?
 
 **No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
 It's like having a library - all books are there, but you only read the ones you need.
@@ -62,7 +62,11 @@ _Always check the Risk label and review the code._
 
 ### Where should I install the skills?
 
-The universal path that works with most tools is `.agent/skills/`:
+The universal path that works with most tools is `.agent/skills/`.
+
+**Using npx:** `npx antigravity-awesome-skills` (or `npx github:sickn33/antigravity-awesome-skills` if you get a 404).
+
+**Using git clone:**
 
 ```bash
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
@@ -72,6 +76,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
 
 - Claude Code: `.claude/skills/`
 - Gemini CLI: `.gemini/skills/`
+- Codex CLI: `.codex/skills/`
 - Cursor: `.cursor/skills/` or project root
 
 ### Does this work with Windows?

docs/GETTING_STARTED.md

@@ -28,7 +28,9 @@ You **install the full repo once** (npx or clone); Starter Packs are curated lis
 npx antigravity-awesome-skills
 ```
 
-This clones to `~/.agent/skills` by default. Use `--cursor`, `--claude`, or `--gemini` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
+This clones to `~/.agent/skills` by default. Use `--cursor`, `--claude`, `--gemini`, or `--codex` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
+
+If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
 
 **Option B — git clone:**
 
@@ -80,6 +82,7 @@ Once installed, just talk to your AI naturally.
 | :-------------- | :-------------- | :---------------- |
 | **Claude Code** | ✅ Full Support | `.claude/skills/` |
 | **Gemini CLI**  | ✅ Full Support | `.gemini/skills/` |
+| **Codex CLI**   | ✅ Full Support | `.codex/skills/`  |
 | **Antigravity** | ✅ Native       | `.agent/skills/`  |
 | **Cursor**      | ✅ Native       | `.cursor/skills/` |
 | **Copilot**     | ⚠️ Text Only    | Manual copy-paste |
@@ -100,7 +103,7 @@ _Check the [Skill Catalog](../CATALOG.md) for the full list._
 
 ## ❓ FAQ
 
-**Q: Do I need to install all 624 skills?**
+**Q: Do I need to install all 626 skills?**
 A: You clone the whole repo once; your AI only _reads_ the skills you invoke (or that are relevant), so it stays lightweight. **Starter Packs** in [BUNDLES.md](BUNDLES.md) are curated lists to help you discover the right skills for your role—they don't change how you install.
 
 **Q: Can I make my own skills?**

docs/QUALITY_BAR.md

@@ -21,6 +21,7 @@ The skill MUST have a section explicitly stating when to trigger it.
 
 - **Good**: "Use when the user asks to debug a React component."
 - **Bad**: "This skill helps you with code."
+Accepted headings: `## When to Use`, `## Use this skill when`, `## When to Use This Skill`.
 
 ### 3. Safety & Risk Classification
 

docs/SKILL_ANATOMY.md

@@ -73,7 +73,7 @@ Some skills include additional metadata:
 ---
 name: my-skill-name
 description: "Brief description"
-risk: "safe" # safe | risk | official
+risk: "safe" # none | safe | critical | offensive (see QUALITY_BAR.md)
 source: "community"
 tags: ["react", "typescript"]
 ---

docs/vietnamese/SKILL_ANATOMY.vi.md

@@ -73,7 +73,7 @@ Một số skill bao gồm thêm siêu dữ liệu bổ sung:
 ---
 name: my-skill-name
 description: "Mô tả ngắn"
-risk: "safe" # safe | risk | official
+risk: "safe" # none | safe | critical | offensive (xem QUALITY_BAR.md)
 source: "community"
 tags: ["react", "typescript"]
 ---

lib/skill-utils.js

@@ -159,8 +159,29 @@ function listSkillIds(skillsDir) {
     .sort();
 }
 
+/**
+ * Recursively list all skill directory paths under skillsDir (relative paths).
+ * Matches generate_index.py behavior so catalog includes nested skills (e.g. game-development/2d-games).
+ */
+function listSkillIdsRecursive(skillsDir, baseDir = skillsDir, acc = []) {
+  const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory()) continue;
+    const dirPath = path.join(baseDir, entry.name);
+    const skillPath = path.join(dirPath, 'SKILL.md');
+    const relPath = path.relative(skillsDir, dirPath);
+    if (fs.existsSync(skillPath)) {
+      acc.push(relPath);
+    }
+    listSkillIdsRecursive(skillsDir, dirPath, acc);
+  }
+  return acc.sort();
+}
+
 module.exports = {
   listSkillIds,
+  listSkillIdsRecursive,
   parseFrontmatter,
   parseInlineList,
   readSkill,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-awesome-skills",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "626+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
   "license": "MIT",
   "scripts": {
@@ -10,17 +10,18 @@
     "readme": "python3 scripts/update_readme.py",
     "chain": "npm run validate && npm run index && npm run readme",
     "catalog": "node scripts/build-catalog.js",
-    "build": "npm run chain && npm run catalog"
+    "build": "npm run chain && npm run catalog",
+    "test": "node scripts/tests/validate_skills_headings.test.js && python3 scripts/tests/test_validate_skills_headings.py"
   },
-  "dependencies": {
+  "devDependencies": {
     "yaml": "^2.8.2"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sickn33/antigravity-awesome-skills.git"
+    "url": "git+https://github.com/sickn33/antigravity-awesome-skills.git"
   },
   "bin": {
-    "antigravity-awesome-skills": "./bin/install.js"
+    "antigravity-awesome-skills": "bin/install.js"
   },
   "files": [
     "bin"

scripts/build-catalog.js

@@ -1,7 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  listSkillIds,
+  listSkillIdsRecursive,
   readSkill,
   tokenize,
   unique,
@@ -297,8 +297,8 @@ function renderCatalogMarkdown(catalog) {
 }
 
 function buildCatalog() {
-  const skillIds = listSkillIds(SKILLS_DIR);
-  const skills = skillIds.map(skillId => readSkill(SKILLS_DIR, skillId));
+  const skillRelPaths = listSkillIdsRecursive(SKILLS_DIR);
+  const skills = skillRelPaths.map(relPath => readSkill(SKILLS_DIR, relPath));
   const catalogSkills = [];
 
   for (const skill of skills) {

scripts/normalize-frontmatter.js

@@ -8,6 +8,8 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 const ALLOWED_FIELDS = new Set([
   'name',
   'description',
+  'risk',
+  'source',
   'license',
   'compatibility',
   'metadata',

scripts/release_cycle.sh

@@ -21,8 +21,12 @@ python3 scripts/generate_index.py
 echo "Running update_readme.py..."
 python3 scripts/update_readme.py
 
-# 2. Stats Consistency Check
-echo -e "\n${YELLOW}Step 2: verifying Stats Consistency...${NC}"
+# 2. Catalog (required for CI)
+echo -e "\n${YELLOW}Step 2: Build catalog...${NC}"
+npm run catalog
+
+# 3. Stats Consistency Check
+echo -e "\n${YELLOW}Step 3: Verifying Stats Consistency...${NC}"
 JSON_COUNT=$(python3 -c "import json; print(len(json.load(open('skills_index.json'))))")
 echo "Skills in Registry (JSON): $JSON_COUNT"
 
@@ -36,8 +40,14 @@ if [[ "$README_CONTENT" != *"$JSON_COUNT high-performance"* ]]; then
 fi
 echo -e "${GREEN}✅ Stats Consistent.${NC}"
 
-# 3. Contributor Check
-echo -e "\n${YELLOW}Step 3: Contributor Check${NC}"
+# 4. Version check (package.json is source of truth for npm)
+echo -e "\n${YELLOW}Step 4: Version check${NC}"
+PKG_VERSION=$(node -p "require('./package.json').version")
+echo "package.json version: $PKG_VERSION"
+echo "Ensure this version is bumped before 'npm publish' (npm forbids republishing the same version)."
+
+# 5. Contributor Check
+echo -e "\n${YELLOW}Step 5: Contributor Check${NC}"
 echo "Recent commits by author (check against README 'Repo Contributors'):"
 git shortlog -sn --since="1 month ago" --all --no-merges | head -n 10
 
@@ -52,4 +62,5 @@ if [ "$CONFIRM_CONTRIB" != "yes" ]; then
 fi
 
 echo -e "\n${GREEN}✅ Release Cycle Checks Passed. You may now commit and push.${NC}"
+echo -e "${YELLOW}After tagging a release: run \`npm publish\` from repo root (or use GitHub Release + NPM_TOKEN for CI).${NC}"
 exit 0

scripts/tests/test_validate_skills_headings.py

@@ -0,0 +1,18 @@
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(__file__)))
+from validate_skills import has_when_to_use_section
+
+SAMPLES = [
+    ("## When to Use", True),
+    ("## Use this skill when", True),
+    ("## When to Use This Skill", True),
+    ("## Overview", False),
+]
+
+for heading, expected in SAMPLES:
+    content = f"\n{heading}\n- item\n"
+    assert has_when_to_use_section(content) is expected, heading
+
+print("ok")

scripts/tests/validate_skills_headings.test.js

@@ -0,0 +1,16 @@
+const assert = require('assert');
+const { hasUseSection } = require('../validate-skills');
+
+const samples = [
+  ['## When to Use', true],
+  ['## Use this skill when', true],
+  ['## When to Use This Skill', true],
+  ['## Overview', false],
+];
+
+for (const [heading, expected] of samples) {
+  const content = `\n${heading}\n- item\n`;
+  assert.strictEqual(hasUseSection(content), expected, heading);
+}
+
+console.log('ok');

scripts/update_readme.py

@@ -36,7 +36,7 @@ def update_readme():
 
     # 3. Update Intro Text Count
     content = re.sub(
-        r"(library of \*\*)\d+( high-performance skills\*\*)",
+        r"(library of \*\*)\d+( high-performance agentic skills\*\*)",
         rf"\g<1>{total_skills}\g<2>",
         content,
     )

scripts/validate-skills.js

@@ -32,12 +32,24 @@ const MAX_SKILL_LINES = 500;
 const ALLOWED_FIELDS = new Set([
   'name',
   'description',
+  'risk',
+  'source',
   'license',
   'compatibility',
   'metadata',
   'allowed-tools',
 ]);
 
+const USE_SECTION_PATTERNS = [
+  /^##\s+When\s+to\s+Use/im,
+  /^##\s+Use\s+this\s+skill\s+when/im,
+  /^##\s+When\s+to\s+Use\s+This\s+Skill/im,
+];
+
+function hasUseSection(content) {
+  return USE_SECTION_PATTERNS.some(pattern => pattern.test(content));
+}
+
 function isPlainObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -99,172 +111,183 @@ function addStrictSectionErrors(label, missing, baselineSet) {
   }
 }
 
-const skillIds = listSkillIds(SKILLS_DIR);
-const baseline = loadBaseline();
-const baselineUse = new Set(baseline.useSection || []);
-const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
-const baselineInstructions = new Set(baseline.instructionsSection || []);
-const baselineLongFile = new Set(baseline.longFile || []);
+function run() {
+  const skillIds = listSkillIds(SKILLS_DIR);
+  const baseline = loadBaseline();
+  const baselineUse = new Set(baseline.useSection || []);
+  const baselineDoNotUse = new Set(baseline.doNotUseSection || []);
+  const baselineInstructions = new Set(baseline.instructionsSection || []);
+  const baselineLongFile = new Set(baseline.longFile || []);
 
-for (const skillId of skillIds) {
-  const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
+  for (const skillId of skillIds) {
+    const skillPath = path.join(SKILLS_DIR, skillId, 'SKILL.md');
 
-  if (!fs.existsSync(skillPath)) {
-    addError(`Missing SKILL.md: ${skillId}`);
-    continue;
-  }
-
-  const content = fs.readFileSync(skillPath, 'utf8');
-  const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
-  const lineCount = content.split(/\r?\n/).length;
-
-  if (!hasFrontmatter) {
-    addError(`Missing frontmatter: ${skillId}`);
-  }
-
-  if (fmErrors && fmErrors.length) {
-    fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
-  }
-
-  if (!NAME_PATTERN.test(skillId)) {
-    addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
-  }
-
-  if (data.name !== undefined) {
-    const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
-    if (nameError) {
-      addError(`${nameError} (${skillId})`);
-    } else {
-      const nameValue = String(data.name).trim();
-      if (!NAME_PATTERN.test(nameValue)) {
-        addError(`name must match ${NAME_PATTERN}: ${skillId}`);
-      }
-      if (nameValue !== skillId) {
-        addError(`name must match folder name: ${skillId} -> ${nameValue}`);
-      }
+    if (!fs.existsSync(skillPath)) {
+      addError(`Missing SKILL.md: ${skillId}`);
+      continue;
     }
-  }
 
-  const descError = data.description === undefined
-    ? 'description is required.'
-    : validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
-  if (descError) {
-    addError(`${descError} (${skillId})`);
-  }
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const { data, errors: fmErrors, hasFrontmatter } = parseFrontmatter(content);
+    const lineCount = content.split(/\r?\n/).length;
 
-  if (data.license !== undefined) {
-    const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
-    if (licenseError) {
-      addError(`${licenseError} (${skillId})`);
+    if (!hasFrontmatter) {
+      addError(`Missing frontmatter: ${skillId}`);
     }
-  }
 
-  if (data.compatibility !== undefined) {
-    const compatibilityError = validateStringField(
-      'compatibility',
-      data.compatibility,
-      { min: 1, max: MAX_COMPATIBILITY_LENGTH },
-    );
-    if (compatibilityError) {
-      addError(`${compatibilityError} (${skillId})`);
+    if (fmErrors && fmErrors.length) {
+      fmErrors.forEach(error => addError(`Frontmatter parse error (${skillId}): ${error}`));
     }
-  }
 
-  if (data['allowed-tools'] !== undefined) {
-    if (typeof data['allowed-tools'] !== 'string') {
-      addError(`allowed-tools must be a space-delimited string. (${skillId})`);
-    } else if (!data['allowed-tools'].trim()) {
-      addError(`allowed-tools cannot be empty. (${skillId})`);
+    if (!NAME_PATTERN.test(skillId)) {
+      addError(`Folder name must match ${NAME_PATTERN}: ${skillId}`);
     }
-  }
 
-  if (data.metadata !== undefined) {
-    if (!isPlainObject(data.metadata)) {
-      addError(`metadata must be a string map/object. (${skillId})`);
-    } else {
-      for (const [key, value] of Object.entries(data.metadata)) {
-        if (typeof value !== 'string') {
-          addError(`metadata.${key} must be a string. (${skillId})`);
+    if (data.name !== undefined) {
+      const nameError = validateStringField('name', data.name, { min: 1, max: MAX_NAME_LENGTH });
+      if (nameError) {
+        addError(`${nameError} (${skillId})`);
+      } else {
+        const nameValue = String(data.name).trim();
+        if (!NAME_PATTERN.test(nameValue)) {
+          addError(`name must match ${NAME_PATTERN}: ${skillId}`);
+        }
+        if (nameValue !== skillId) {
+          addError(`name must match folder name: ${skillId} -> ${nameValue}`);
         }
       }
     }
-  }
 
-  if (data && Object.keys(data).length) {
-    const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
-    if (unknownFields.length) {
-      unknownFieldSkills.push(skillId);
-      addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
+    const descError = data.description === undefined
+      ? 'description is required.'
+      : validateStringField('description', data.description, { min: 1, max: MAX_DESCRIPTION_LENGTH });
+    if (descError) {
+      addError(`${descError} (${skillId})`);
+    }
+
+    if (data.license !== undefined) {
+      const licenseError = validateStringField('license', data.license, { min: 1, max: 128 });
+      if (licenseError) {
+        addError(`${licenseError} (${skillId})`);
+      }
+    }
+
+    if (data.compatibility !== undefined) {
+      const compatibilityError = validateStringField(
+        'compatibility',
+        data.compatibility,
+        { min: 1, max: MAX_COMPATIBILITY_LENGTH },
+      );
+      if (compatibilityError) {
+        addError(`${compatibilityError} (${skillId})`);
+      }
+    }
+
+    if (data['allowed-tools'] !== undefined) {
+      if (typeof data['allowed-tools'] !== 'string') {
+        addError(`allowed-tools must be a space-delimited string. (${skillId})`);
+      } else if (!data['allowed-tools'].trim()) {
+        addError(`allowed-tools cannot be empty. (${skillId})`);
+      }
+    }
+
+    if (data.metadata !== undefined) {
+      if (!isPlainObject(data.metadata)) {
+        addError(`metadata must be a string map/object. (${skillId})`);
+      } else {
+        for (const [key, value] of Object.entries(data.metadata)) {
+          if (typeof value !== 'string') {
+            addError(`metadata.${key} must be a string. (${skillId})`);
+          }
+        }
+      }
+    }
+
+    if (data && Object.keys(data).length) {
+      const unknownFields = Object.keys(data).filter(key => !ALLOWED_FIELDS.has(key));
+      if (unknownFields.length) {
+        unknownFieldSkills.push(skillId);
+        addError(`Unknown frontmatter fields (${skillId}): ${unknownFields.join(', ')}`);
+      }
+    }
+
+    if (lineCount > MAX_SKILL_LINES) {
+      longFiles.push(skillId);
+    }
+
+    if (!hasUseSection(content)) {
+      missingUseSection.push(skillId);
+    }
+
+    if (!content.includes('## Do not use')) {
+      missingDoNotUseSection.push(skillId);
+    }
+
+    if (!content.includes('## Instructions')) {
+      missingInstructionsSection.push(skillId);
     }
   }
 
-  if (lineCount > MAX_SKILL_LINES) {
-    longFiles.push(skillId);
+  if (missingUseSection.length) {
+    addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Use this skill when')) {
-    missingUseSection.push(skillId);
+  if (missingDoNotUseSection.length) {
+    addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Do not use')) {
-    missingDoNotUseSection.push(skillId);
+  if (missingInstructionsSection.length) {
+    addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
   }
 
-  if (!content.includes('## Instructions')) {
-    missingInstructionsSection.push(skillId);
+  if (longFiles.length) {
+    addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
   }
-}
 
-if (missingUseSection.length) {
-  addWarning(`Missing "Use this skill when" section: ${missingUseSection.length} skills (examples: ${missingUseSection.slice(0, 5).join(', ')})`);
-}
-
-if (missingDoNotUseSection.length) {
-  addWarning(`Missing "Do not use" section: ${missingDoNotUseSection.length} skills (examples: ${missingDoNotUseSection.slice(0, 5).join(', ')})`);
-}
-
-if (missingInstructionsSection.length) {
-  addWarning(`Missing "Instructions" section: ${missingInstructionsSection.length} skills (examples: ${missingInstructionsSection.slice(0, 5).join(', ')})`);
-}
-
-if (longFiles.length) {
-  addWarning(`SKILL.md over ${MAX_SKILL_LINES} lines: ${longFiles.length} skills (examples: ${longFiles.slice(0, 5).join(', ')})`);
-}
-
-if (unknownFieldSkills.length) {
-  addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
-}
-
-addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
-addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
-addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
-addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
-
-if (writeBaseline) {
-  const baselineData = {
-    generatedAt: new Date().toISOString(),
-    useSection: [...missingUseSection].sort(),
-    doNotUseSection: [...missingDoNotUseSection].sort(),
-    instructionsSection: [...missingInstructionsSection].sort(),
-    longFile: [...longFiles].sort(),
-  };
-  fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
-  console.log(`Baseline written to ${BASELINE_PATH}`);
-}
-
-if (warnings.length) {
-  console.warn('Warnings:');
-  for (const warning of warnings) {
-    console.warn(`- ${warning}`);
+  if (unknownFieldSkills.length) {
+    addWarning(`Unknown frontmatter fields detected: ${unknownFieldSkills.length} skills (examples: ${unknownFieldSkills.slice(0, 5).join(', ')})`);
   }
-}
 
-if (errors.length) {
-  console.error('\nErrors:');
-  for (const error of errors) {
-    console.error(`- ${error}`);
+  addStrictSectionErrors('Use this skill when', missingUseSection, baselineUse);
+  addStrictSectionErrors('Do not use', missingDoNotUseSection, baselineDoNotUse);
+  addStrictSectionErrors('Instructions', missingInstructionsSection, baselineInstructions);
+  addStrictSectionErrors(`SKILL.md line count <= ${MAX_SKILL_LINES}`, longFiles, baselineLongFile);
+
+  if (writeBaseline) {
+    const baselineData = {
+      generatedAt: new Date().toISOString(),
+      useSection: [...missingUseSection].sort(),
+      doNotUseSection: [...missingDoNotUseSection].sort(),
+      instructionsSection: [...missingInstructionsSection].sort(),
+      longFile: [...longFiles].sort(),
+    };
+    fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineData, null, 2));
+    console.log(`Baseline written to ${BASELINE_PATH}`);
   }
-  process.exit(1);
+
+  if (warnings.length) {
+    console.warn('Warnings:');
+    for (const warning of warnings) {
+      console.warn(`- ${warning}`);
+    }
+  }
+
+  if (errors.length) {
+    console.error('\nErrors:');
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Validation passed for ${skillIds.length} skills.`);
 }
 
-console.log(`Validation passed for ${skillIds.length} skills.`);
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  hasUseSection,
+  run,
+};

scripts/validate_skills.py

@@ -3,6 +3,15 @@ import re
 import argparse
 import sys
 
+WHEN_TO_USE_PATTERNS = [
+    re.compile(r"^##\s+When\s+to\s+Use", re.MULTILINE | re.IGNORECASE),
+    re.compile(r"^##\s+Use\s+this\s+skill\s+when", re.MULTILINE | re.IGNORECASE),
+    re.compile(r"^##\s+When\s+to\s+Use\s+This\s+Skill", re.MULTILINE | re.IGNORECASE),
+]
+
+def has_when_to_use_section(content):
+    return any(pattern.search(content) for pattern in WHEN_TO_USE_PATTERNS)
+
 def parse_frontmatter(content):
     """
     Simple frontmatter parser using regex to avoid external dependencies.
@@ -30,7 +39,6 @@ def validate_skills(skills_dir, strict_mode=False):
     
     # Pre-compiled regex
     security_disclaimer_pattern = re.compile(r"AUTHORIZED USE ONLY", re.IGNORECASE)
-    trigger_section_pattern = re.compile(r"^##\s+When to Use", re.MULTILINE | re.IGNORECASE)
 
     valid_risk_levels = ["none", "safe", "critical", "offensive"]
 
@@ -80,7 +88,7 @@ def validate_skills(skills_dir, strict_mode=False):
                 else: warnings.append(msg)
 
             # 3. Content Checks (Triggers)
-            if not trigger_section_pattern.search(content):
+            if not has_when_to_use_section(content):
                 msg = f"⚠️  {rel_path}: Missing '## When to Use' section"
                 if strict_mode: errors.append(msg.replace("⚠️", "❌"))
                 else: warnings.append(msg)