battle-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuocTang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+<div align="center">
+  <img src="assets/images/logo.png" alt="Battle Skills Logo" width="200"/>
+
+# ⚔️ Battle Skills
+
+_Personal collection of battle-tested agentic skills for Claude Code, Cursor, Gemini CLI, Codex CLI, and more._
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+These are **real skills from real projects** — not theoretical patterns. Each one has been used in production and refined through actual use.
+
+---
+
+## 📑 Table of Contents
+
+- [🚀 Quick Start](#-quick-start)
+- [🛠️ Installation](#️-installation)
+- [📦 Features](#-features)
+- [🎯 Available Skills](#-available-skills)
+- [🤝 How to Contribute](#-how-to-contribute)
+- [💬 Community & Support](#-community--support)
+- [👥 Repo Contributors](#-repo-contributors)
+- [⚖️ License](#️-license)
+- [🌟 Star History](#-star-history)
+
+---
+
+## 🚀 Quick Start
+
+1. Install via your AI assistant's directory (`.claude/skills`, `.cursor/skills`, etc.)
+2. Use by naming the skill in the prompt (e.g. `Use awesome-readme to...`)
+3. Validate and build new skills easily with our included scripts.
+
+---
+
+## 🛠️ Installation
+
+**💡 Recommended: Use the CLI Installer**
+
+```bash
+# Install directly to your favorite AI Assistant
+npx battle-skills --cursor       # For Cursor
+npx battle-skills --claude       # For Claude Code
+npx battle-skills --gemini       # For Gemini CLI
+npx battle-skills --antigravity  # For Antigravity
+npx battle-skills --path ./dir   # Custom path (.agent/skills)
+```
+
+**Alternative: Manual Git Clone**
+
+| Tool            | Install Command                                                          |
+| --------------- | ------------------------------------------------------------------------ |
+| **Claude Code** | `git clone https://github.com/QuocTang/battle-skills.git .claude/skills` |
+| **Cursor**      | `git clone https://github.com/QuocTang/battle-skills.git .cursor/skills` |
+| **Gemini CLI**  | `git clone https://github.com/QuocTang/battle-skills.git .gemini/skills` |
+| **Universal**   | `git clone https://github.com/QuocTang/battle-skills.git .agent/skills`  |
+
+**To update:** Rerun the `npx` command or `git -C <your_tool_folder>/skills pull`
+
+---
+
+## 📦 Features
+
+- **✅ Battle-Tested:** Real, production-grade instructions built from hard-earned experience.
+- **🔄 Universal Compatibility:** Works seamlessly with Claude, Cursor, Gemini CLI, and standard AI agent architectures.
+- **🛠️ Self-Validating:** Includes `validate_skills.py` to ensure every skill is formatted perfectly.
+- **📚 Auto-Documentation:** `gen_catalog.py` keeps the `CATALOG.md` and machine-readable `skills_index.json` constantly updated.
+
+---
+
+## 🎯 Available Skills
+
+See the full list of our current capabilities in the 👉 **[CATALOG.md](CATALOG.md)**.
+
+> Check out the `create-skill` guide if you want to understand how the battle skills are structured!
+
+---
+
+## 🤝 How to Contribute
+
+We welcome contributions! Please follow these steps to add your own battle skills:
+
+1. **Fork** the repository.
+2. **Create a new branch** for your feature or skill.
+3. Follow the `create-skill` guide to scaffold your new skill folder and `SKILL.md`.
+4. Run `python3 scripts/validate_skills.py` and `python3 scripts/gen_catalog.py`.
+5. Update `CHANGELOG.md` and **Submit a Pull Request**.
+
+## 💬 Community & Support
+
+If this repository saves you time or levels up your AI coding game, please give it a ⭐️!
+Your support keeps the collection growing.
+
+---
+
+## 👥 Repo Contributors
+
+<a href="https://github.com/QuocTang/battle-skills/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=QuocTang/battle-skills" alt="Repository contributors" />
+</a>
+
+_Made with [contrib.rocks](https://contrib.rocks)._
+
+---
+
+## ⚖️ License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## 🌟 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=QuocTang/battle-skills&type=Date)](https://star-history.com/#QuocTang/battle-skills&Date)

package/bin/install.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const REPO = "https://github.com/QuocTang/battle-skills.git";
+const HOME = process.env.HOME || process.env.USERPROFILE || "";
+
+function resolveDir(p) {
+  if (!p) return null;
+  const s = p.replace(/^~($|\/)/, HOME + "$1");
+  return path.resolve(s);
+}
+
+function parseArgs() {
+  const a = process.argv.slice(2);
+  let pathArg = null;
+  let versionArg = null;
+  let tagArg = null;
+  let cursor = false,
+    claude = false,
+    gemini = false,
+    codex = false,
+    antigravity = false,
+    kiro = 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] === "--antigravity") {
+      antigravity = true;
+      continue;
+    }
+    if (a[i] === "--kiro") {
+      kiro = true;
+      continue;
+    }
+    if (a[i] === "install") continue;
+  }
+
+  return {
+    pathArg,
+    versionArg,
+    tagArg,
+    cursor,
+    claude,
+    gemini,
+    codex,
+    antigravity,
+    kiro,
+  };
+}
+
+function defaultDir(opts) {
+  if (opts.pathArg) return resolveDir(opts.pathArg);
+  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");
+  }
+  if (opts.kiro) return path.join(HOME, ".kiro", "skills");
+  if (opts.antigravity)
+    return path.join(HOME, ".gemini", "antigravity", "skills");
+  return path.join(HOME, ".gemini", "antigravity", "skills");
+}
+
+function printHelp() {
+  console.log(`
+battle-skills — installer
+
+  npx battle-skills [install] [options]
+
+  Clones the skills repo into your agent's skills directory.
+
+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)
+  --kiro         Install to ~/.kiro/skills (Kiro CLI)
+  --antigravity  Install to ~/.gemini/antigravity/skills (Antigravity)
+  --path <dir>   Install to <dir> (default: ~/.gemini/antigravity/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 battle-skills
+  npx battle-skills --cursor
+  npx battle-skills --kiro
+  npx battle-skills --antigravity
+  npx battle-skills --version 4.6.0
+  npx battle-skills --path ./my-skills
+`);
+}
+
+function copyRecursiveSync(src, dest, skipGit = true) {
+  const stats = fs.statSync(src);
+  if (stats.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach((child) => {
+      if (skipGit && child === ".git") return;
+      copyRecursiveSync(path.join(src, child), path.join(dest, child), skipGit);
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/** Copy contents of repo's skills/ into target so each skill is target/skill-name/ (for Claude Code etc.). */
+function installSkillsIntoTarget(tempDir, target) {
+  const repoSkills = path.join(tempDir, "skills");
+  if (!fs.existsSync(repoSkills)) {
+    console.error("Cloned repo has no skills/ directory.");
+    process.exit(1);
+  }
+  fs.readdirSync(repoSkills).forEach((name) => {
+    const src = path.join(repoSkills, name);
+    const dest = path.join(target, name);
+    copyRecursiveSync(src, dest);
+  });
+  const repoDocs = path.join(tempDir, "docs");
+  if (fs.existsSync(repoDocs)) {
+    const docsDest = path.join(target, "docs");
+    if (!fs.existsSync(docsDest)) fs.mkdirSync(docsDest, { recursive: true });
+    copyRecursiveSync(repoDocs, docsDest);
+  }
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { stdio: "inherit", ...opts });
+  if (r.status !== 0) process.exit(r.status == null ? 1 : r.status);
+}
+
+function main() {
+  const opts = parseArgs();
+  const { tagArg, versionArg } = opts;
+
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  const target = defaultDir(opts);
+  if (!target || !HOME) {
+    console.error(
+      "Could not resolve home directory. Use --path <absolute-path>.",
+    );
+    process.exit(1);
+  }
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ag-skills-"));
+  const originalCwd = process.cwd();
+
+  try {
+    if (process.platform === "win32") {
+      run("git", ["-c", "core.symlinks=true", "clone", REPO, tempDir]);
+    } else {
+      run("git", ["clone", REPO, tempDir]);
+    }
+
+    const ref =
+      tagArg ||
+      (versionArg
+        ? versionArg.startsWith("v")
+          ? versionArg
+          : `v${versionArg}`
+        : null);
+    if (ref) {
+      console.log(`Checking out ${ref}…`);
+      process.chdir(tempDir);
+      run("git", ["checkout", ref]);
+      process.chdir(originalCwd);
+    }
+
+    if (fs.existsSync(target)) {
+      const gitDir = path.join(target, ".git");
+      if (fs.existsSync(gitDir)) {
+        console.log("Migrating from full-repo install to skills-only layout…");
+        const entries = fs.readdirSync(target);
+        for (const name of entries) {
+          const full = path.join(target, name);
+          const stat = fs.statSync(full);
+          if (stat.isDirectory()) {
+            if (fs.rmSync) {
+              fs.rmSync(full, { recursive: true, force: true });
+            } else {
+              fs.rmdirSync(full, { recursive: true });
+            }
+          } else {
+            fs.unlinkSync(full);
+          }
+        }
+      } else {
+        console.log(`Updating existing install at ${target}…`);
+      }
+    } else {
+      const parent = path.dirname(target);
+      if (!fs.existsSync(parent)) {
+        try {
+          fs.mkdirSync(parent, { recursive: true });
+        } catch (e) {
+          console.error(`Cannot create parent directory: ${parent}`, e.message);
+          process.exit(1);
+        }
+      }
+      fs.mkdirSync(target, { recursive: true });
+    }
+
+    installSkillsIntoTarget(tempDir, target);
+
+    console.log(`\nInstalled to ${target}`);
+    console.log(
+      "Pick a bundle in docs/BUNDLES.md and use @skill-name in your AI assistant.",
+    );
+  } finally {
+    try {
+      if (fs.existsSync(tempDir)) {
+        if (fs.rmSync) {
+          fs.rmSync(tempDir, { recursive: true, force: true });
+        } else {
+          fs.rmdirSync(tempDir, { recursive: true });
+        }
+      }
+    } catch (e) {
+      // ignore cleanup errors
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "battle-skills",
+    "version": "1.0.0",
+    "description": "Personal collection of battle-tested agentic skills for Claude Code, Cursor, Gemini CLI, Codex CLI, Antigravity and more.",
+    "license": "MIT",
+    "scripts": {
+        "validate": "python3 scripts/validate_skills.py",
+        "catalog": "python3 scripts/gen_catalog.py",
+        "build": "npm run validate && npm run catalog"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/QuocTang/battle-skills.git"
+    },
+    "bin": {
+        "battle-skills": "bin/install.js"
+    },
+    "files": [
+        "bin"
+    ],
+    "keywords": [
+        "claude-code",
+        "cursor",
+        "gemini-cli",
+        "antigravity",
+        "agentic-skills",
+        "ai-coding"
+    ]
+}