@flitzrrr/agent-skills 1.0.3 → 1.2.0

package/README.md

@@ -1,126 +1,218 @@
-# 🧠 Agent Skills Hub
-
-> **121 AI agent skills** from **15 industry-leading sources** — organized, evaluated, and **multiplatform-ready** for all major AI coding IDEs.
-
-## ✅ Supported Platforms
-
-| Platform | Config File | Setup |
-|----------|------------|-------|
-| **Claude Code** | `CLAUDE.md` | Clone repo, skills auto-discovered |
-| **Antigravity** | `skills/` dir | Symlink `skills/` into agent skill dir |
-| **Codex** (OpenAI) | `AGENTS.md` | Clone repo, `AGENTS.md` auto-loaded |
-| **OpenCode** | `AGENTS.md` + `skills/` | Clone repo, reference skills in prompts |
-| **Cursor** | `.cursorrules` | Clone repo into workspace, rules auto-loaded |
-| **Lovable** | `.lovable` | Add as project dependency |
-| **Windsurf** | `AGENTS.md` | Clone repo, reference skill paths |
-| **Generic Agent** | `SKILL.md` per skill | Read `skills/<name>/SKILL.md` |
-
-## Sources (15)
-
-| # | Source | Skills | Focus |
-|---|--------|--------|-------|
-| 1 | [getsentry/skills](https://github.com/getsentry/skills) | 24 | Security, code review, Git workflow, Django |
-| 2 | [Bhanunamikaze/Agentic-SEO-Skill](https://github.com/Bhanunamikaze/Agentic-SEO-Skill) | 16 | Comprehensive SEO auditing |
-| 3 | [DasDigitaleMomentum/opencode-processing-skills](https://github.com/DasDigitaleMomentum/opencode-processing-skills) | 9 | Multi-session planning & docs |
-| 4 | [anthropics/skills](https://github.com/anthropics/skills) | 17 | Document gen, creative design, MCP, API |
-| 5 | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | 5 | React/Next.js, web design, deployment |
-| 6 | [trailofbits/skills](https://github.com/trailofbits/skills) | 30 | Advanced security auditing, static analysis, smart contracts |
-| 7 | [cloudflare/skills](https://github.com/cloudflare/skills) | 9 | Workers, Durable Objects, MCP, web perf |
-| 8 | [stripe/ai](https://github.com/stripe/ai) | 2 | Stripe best practices & SDK upgrades |
-| 9 | [expo/skills](https://github.com/expo/skills) | 3 | Expo app design, deployment, upgrades |
-| 10 | [google-labs-code/stitch-skills](https://github.com/google-labs-code/stitch-skills) | 7 | Design-to-code, shadcn/ui, Remotion |
-| 11 | [hashicorp/agent-skills](https://github.com/hashicorp/agent-skills) | 3 | Terraform code/module/provider generation |
-| 12 | [supabase/agent-skills](https://github.com/supabase/agent-skills) | 1 | Postgres best practices |
-| 13 | [callstackincubator/agent-skills](https://github.com/callstackincubator/agent-skills) | 5 | React Native, GitHub workflows |
-| 14 | [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | 100+ | Science, bioinformatics, ML, chemistry |
-| 15 | [ComposioHQ/skills](https://github.com/ComposioHQ/skills) | 1 | Connect agents to 1000+ external apps |
-
-## Repository Structure
+# Agent Skills Hub
 
-```
-agent-skills/
-├── skills/               ← 121 symlinks (flat access to all skills)
-├── vendor/               ← 15 Git submodules (upstream sources)
-├── AGENTS.md             ← Codex / OpenCode / Windsurf
-├── CLAUDE.md             ← Claude Code
-├── .cursorrules          ← Cursor IDE
-├── .lovable              ← Lovable AI
-├── CHEATSHEET.md         ← Decision guide: which skill when
-└── README.md             ← This file
-```
+[![npm version](https://img.shields.io/npm/v/@flitzrrr/agent-skills?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@flitzrrr/agent-skills)
+[![npm downloads](https://img.shields.io/npm/dm/@flitzrrr/agent-skills?style=flat-square)](https://www.npmjs.com/package/@flitzrrr/agent-skills)
+[![Skills](https://img.shields.io/badge/skills-480-blue?style=flat-square)](skills/)
+[![Sources](https://img.shields.io/badge/sources-20-green?style=flat-square)](vendor/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![Weekly Discovery](https://img.shields.io/badge/auto--discovery-weekly-purple?style=flat-square)](.github/workflows/skill-discovery.yml)
 
-## Quick Start
+**504 curated AI agent skills** from **19 verified sources**. One install, every major coding assistant.
 
-```bash
-# Clone with all submodules
-git clone --recurse-submodules git@github.com:flitzrrr/agent-skills.git
+[Full catalog](https://flitzrrr.github.io/agent-skills/) | [Decision guide](CHEATSHEET.md)
 
-# Update all upstream sources
-git submodule update --remote --merge
-```
+---
 
-## Install via npm
+## Quick Start
 
 ```bash
 npx @flitzrrr/agent-skills install
 ```
 
-## Platform Setup
+Detects installed platforms and provisions skills for each. Target a single platform with:
 
-### Claude Code
 ```bash
-git clone --recurse-submodules git@github.com:flitzrrr/agent-skills.git
-# CLAUDE.md auto-discovered
+npx @flitzrrr/agent-skills install <platform>
 ```
 
-### Antigravity (Gemini)
-```bash
-ln -sf /path/to/agent-skills/skills/* ~/.gemini/antigravity/skills/
-```
+Where `<platform>` is one of: `vscode`, `codex`, `antigravity`, `opencode`.
 
-### Codex (OpenAI)
-```bash
-git clone --recurse-submodules git@github.com:flitzrrr/agent-skills.git
-# AGENTS.md auto-discovered
-```
+<details>
+<summary>Manual setup (git clone)</summary>
 
-### Cursor
 ```bash
 git clone --recurse-submodules git@github.com:flitzrrr/agent-skills.git
-# .cursorrules auto-loaded
+cd agent-skills
+
+# Symlink into target platform(s):
+ln -sf $(pwd)/skills/* ~/.copilot/skills/         # VS Code / GitHub Copilot
+ln -sf $(pwd)/skills/* ~/.codex/skills/            # Codex
+ln -sf $(pwd)/skills/* ~/.gemini/antigravity/skills/ # Antigravity
+ln -sf $(pwd)/skills/* ~/.config/opencode/skills/  # OpenCode
+
+# Pull upstream updates:
+git submodule update --remote --merge
 ```
 
-### OpenCode
-```bash
-# Skills are symlinked — see CHEATSHEET.md for usage
-ln -sf /path/to/agent-skills/skills/* ~/.opencode/skills/
+</details>
+
+<details>
+<summary>All CLI commands</summary>
+
+| Command | Description |
+| --- | --- |
+| `npx @flitzrrr/agent-skills install` | Install for all detected platforms |
+| `npx @flitzrrr/agent-skills install <platform>` | Install for a single platform |
+| `npx @flitzrrr/agent-skills update` | Pull latest upstream skills |
+| `npx @flitzrrr/agent-skills list` | List all available skills |
+
+</details>
+
+---
+
+## Platform Support
+
+| Platform | Discovery Mechanism | Install Method |
+| --- | --- | --- |
+| VS Code (GitHub Copilot) | `.github/copilot-instructions.md` + `~/.copilot/skills/` | `install vscode` |
+| Claude Code | `CLAUDE.md` (project-level) | Clone into project |
+| Codex | `AGENTS.md` | `install codex` |
+| Cursor | `.cursorrules` (project-level) | Clone into workspace |
+| Lovable | `.lovable` | Clone into workspace |
+| Windsurf | `AGENTS.md` | Clone into workspace |
+| Antigravity | `~/.gemini/antigravity/skills/` | `install antigravity` |
+| OpenCode | `AGENTS.md` + `skills/` | `install opencode` |
+| Any agent | Read `skills/<name>/SKILL.md` directly | Manual |
+
+---
+
+## Skill Categories
+
+| Category | Examples | Sources |
+| --- | --- | --- |
+| Security and code review | `security-review`, `code-review`, `find-bugs`, `gha-security-review` | Sentry, Trail of Bits |
+| Git workflow | `commit`, `create-branch`, `pr-writer`, `iterate-pr` | Sentry |
+| Project planning | `create-plan`, `resume-plan`, `execute-work-package`, `generate-handover` | DasDigitaleMomentum |
+| Document generation | `anthropic-pdf`, `anthropic-docx`, `anthropic-pptx`, `anthropic-xlsx` | Anthropic |
+| Frontend and React | `vercel-react-best-practices`, `vercel-web-design-guidelines`, `anthropic-frontend-design` | Vercel, Anthropic |
+| Infrastructure | `aws-lambda`, `terraform-code-generation`, `cloudflare-wrangler` | AWS, HashiCorp, Cloudflare |
+| Finance | `finance-equity-research`, `finance-ib-advisory`, `finance-wealth-mgmt` | Anthropic |
+| Science and ML | `scientific-bioinformatics`, `scientific-alphafold`, `scientific-chembl` | K-Dense-AI |
+| Marketing and SEO | `content-strategy`, `seo-audit`, `product-description-seo` | Coreyhaines, Bhanunamikaze |
+| Developer tools | `anthropic-mcp-builder`, `anthropic-webapp-testing`, `systematic-debugging` | Anthropic, Sentry |
+| Django | `django-access-review`, `django-perf-review` | Sentry |
+| Deployment | `vercel-deploy-to-vercel`, `stitch-shadcn-ui` | Vercel, Google |
+
+See [CHEATSHEET.md](CHEATSHEET.md) for a decision guide on which skill to use for a given task.
+
+---
+
+## Sources
+
+| Source | Skills | Focus |
+| --- | ---: | --- |
+| [K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills) | 175 | Science, bioinformatics, ML, chemistry |
+| [trailofbits/skills](https://github.com/trailofbits/skills) | 60 | Security auditing, static analysis, smart contracts |
+| [anthropics/financial-services-plugins](https://github.com/anthropics/financial-services-plugins) | 56 | Finance: IB, equity research, PE, wealth mgmt |
+| [MoizIbnYousaf/Ai-Agent-Skills](https://github.com/MoizIbnYousaf/Ai-Agent-Skills) | 48 | Database design, debugging, code patterns |
+| [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) | 33 | Marketing: SEO, email, content, analytics |
+| [getsentry/skills](https://github.com/getsentry/skills) | 24 | Security, code review, Git workflow, Django |
+| [itsmostafa/aws-agent-skills](https://github.com/itsmostafa/aws-agent-skills) | 18 | AWS infrastructure and services |
+| [anthropics/skills](https://github.com/anthropics/skills) | 17 | Document gen, creative design, MCP |
+| [hashicorp/agent-skills](https://github.com/hashicorp/agent-skills) | 14 | Terraform generation |
+| [expo/skills](https://github.com/expo/skills) | 11 | Expo design and deployment |
+| [cloudflare/skills](https://github.com/cloudflare/skills) | 9 | Workers, Durable Objects, MCP |
+| [DasDigitaleMomentum/opencode-processing-skills](https://github.com/DasDigitaleMomentum/opencode-processing-skills) | 9 | Multi-session planning |
+| [google-labs-code/stitch-skills](https://github.com/google-labs-code/stitch-skills) | 7 | Design-to-code, shadcn/ui, Remotion |
+| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | 5 | React, Next.js, web design |
+| [callstackincubator/agent-skills](https://github.com/callstackincubator/agent-skills) | 5 | React Native, GitHub workflows |
+| [JackyST0/awesome-agent-skills](https://github.com/JackyST0/awesome-agent-skills) | 5 | General-purpose agent patterns |
+| [stripe/ai](https://github.com/stripe/ai) | 2 | Stripe best practices |
+| [Bhanunamikaze/Agentic-SEO-Skill](https://github.com/Bhanunamikaze/Agentic-SEO-Skill) | 1 | SEO auditing (16 sub-skills) |
+| [supabase/agent-skills](https://github.com/supabase/agent-skills) | 1 | Postgres best practices |
+
+New sources are discovered weekly via [GitHub Actions](.github/workflows/skill-discovery.yml) and security-scanned before integration.
+
+---
+
+## Architecture
+
+```
+agent-skills/
+  skills/            504 entries (symlinks to vendor + local forks)
+  vendor/          20 Git submodules (upstream sources)
+  bin/               CLI and build scripts
+  docs/              GitHub Pages catalog and project documentation
+  .github/           CI workflows and copilot-instructions.md
 ```
 
-### Lovable
-```bash
-git submodule add git@github.com:flitzrrr/agent-skills.git skills
+Skills are exposed as a flat directory under `skills/`. Most entries are symlinks into `vendor/` submodules. Skills with local extensions (e.g., `execute-work-package` with multi-transport support) are maintained as real directories alongside the symlinks.
+
+### Naming Convention
+
+Skills are namespaced by source to avoid collisions: `anthropic-pdf`, `tob-static-analysis`, `cloudflare-wrangler`, `terraform-code-generation`, `scientific-bioinformatics`, `aws-lambda`, `finance-equity-research`, `callstack-react-native-best-practices`. Sentry and marketing skills are un-prefixed (`code-review`, `content-strategy`).
+
+### Automation
+
+| Workflow | Trigger | Purpose |
+| --- | --- | --- |
+| [Skill Discovery](.github/workflows/skill-discovery.yml) | Weekly | Find trending skill repos, security-scan, auto-add |
+| [Submodule Update](.github/workflows/submodule-update.yml) | Weekly | Pull upstream changes, open PR |
+| [MegaLinter](.github/workflows/megalinter.yml) | Push / PR | Lint markdown, YAML, JSON |
+| [npm Publish](.github/workflows/npm-publish.yml) | Tag `v*` | Publish to npm, create GitHub Release |
+
+---
+
+## MCP Execution Backend (l4l-oci)
+
+The [execute-work-package](skills/execute-work-package) skill supports three transport modes for delegating implementation to a sub-agent:
+
+| Transport | Mechanism | When to use |
+| --- | --- | --- |
+| **MCP via l4l-oci** (default) | [l4l-oci](https://github.com/DasDigitaleMomentum/l4l-oci) exposes 10 MCP tools for the gated blueprint-gate-execute lifecycle | Any IDE with MCP support |
+| **Fresh Agent** | IDE spawns a new sub-agent per step (no external server) | Fallback when l4l-oci is not configured |
+| **Stateful Session** | Sub-agent session resumed across steps | OpenCode only |
+
+When l4l-oci MCP tools are available (`create_handle`, `generate_blueprint`, `submit_gate`, `execute_handle`, `get_digest`), the skill uses them automatically. The bundled `scripts/start-l4l-oci.sh` auto-starts the server if needed. See the [l4l-oci setup guide](https://github.com/DasDigitaleMomentum/l4l-oci/blob/main/docs/setup.md) for configuration.
+
+### Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Primary as Primary Agent<br/>(IDE)
+    participant MCP as l4l-oci MCP Server
+    participant Sub as Sub-LLM<br/>(configurable)
+
+    User->>Primary: Task with scope and DoD
+
+    rect rgb(240, 245, 250)
+    Note over Primary,Sub: Blueprint Phase
+    Primary->>MCP: create_handle(project_root)
+    MCP-->>Primary: handle_id
+    Primary->>MCP: generate_blueprint(handle_id, prompt)
+    MCP->>Sub: Generate Execution Blueprint
+    Sub-->>MCP: Blueprint (ordered steps)
+    Primary->>MCP: get_blueprint(handle_id)
+    MCP-->>Primary: Blueprint for review
+    end
+
+    Primary->>User: Present Blueprint for review
+
+    User->>Primary: Approve
+
+    rect rgb(240, 250, 240)
+    Note over Primary,Sub: Gate
+    Primary->>MCP: submit_gate(handle_id, "accept")
+    MCP-->>Primary: Gated
+    end
+
+    rect rgb(250, 245, 240)
+    Note over Primary,Sub: Execute Phase
+    Primary->>MCP: execute_handle(handle_id)
+    MCP->>Sub: Implement Blueprint steps
+    Sub->>Sub: Edit files, run verification
+    Sub-->>MCP: Execution Digest
+    Primary->>MCP: get_digest(handle_id)
+    MCP-->>Primary: Digest (outcome, files, verify result)
+    end
+
+    Primary->>User: Report results
 ```
 
-## Naming Convention
-
-| Source | Prefix | Example |
-|--------|--------|---------|
-| Sentry | *(none)* | `code-review`, `security-review` |
-| SEO | `seo` | `seo` |
-| OpenCode | *(none)* | `create-plan`, `resume-plan` |
-| Anthropic | `anthropic-` | `anthropic-pdf`, `anthropic-mcp-builder` |
-| Vercel | `vercel-` | `vercel-react-best-practices` |
-| Trail of Bits | `tob-` | `tob-static-analysis`, `tob-semgrep-rule-creator` |
-| Cloudflare | `cloudflare-` | `cloudflare-wrangler`, `cloudflare-web-perf` |
-| Stripe | `stripe-` | `stripe-stripe-best-practices` |
-| Expo | `expo` | `expo` |
-| Google Stitch | `stitch-` | `stitch-shadcn-ui`, `stitch-remotion` |
-| HashiCorp | `terraform-` | `terraform-code-generation` |
-| Supabase | `supabase-` | `supabase-postgres` |
-| CallStack | `callstack-` | `callstack-react-native-best-practices` |
-| Scientific | `scientific` | `scientific` (100+ sub-skills) |
-| Composio | `composio` | `composio` |
+---
 
 ## License
 
-Each vendored repository retains its original license. See individual repos for details.
+MIT -- applies to the CLI, workflows, and documentation in this repository.
+Each vendored submodule in `vendor/` retains its own original license.

package/bin/build-catalog.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * Build catalog.json from all SKILL.md frontmatter.
+ * Searches recursively for SKILL.md and generates descriptions
+ * for skills that lack frontmatter descriptions.
+ *
+ * Run: node bin/build-catalog.js
+ * Output: docs/catalog.json
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const SKILLS_DIR = path.join(ROOT, "skills");
+const OUT = path.join(ROOT, "docs", "catalog.json");
+
+function findSkillMd(dir, maxDepth) {
+  if (maxDepth <= 0) return null;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    // Check current directory first
+    for (const e of entries) {
+      if (e.isFile() && e.name.toLowerCase() === "skill.md") {
+        return path.join(dir, e.name);
+      }
+    }
+    // Then recurse into subdirectories
+    for (const e of entries) {
+      if (e.isDirectory() && e.name !== ".git" && e.name !== "node_modules") {
+        const found = findSkillMd(path.join(dir, e.name), maxDepth - 1);
+        if (found) return found;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function extractDescription(skillMdPath) {
+  const content = fs.readFileSync(skillMdPath, "utf8");
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    let desc = null;
+
+    // 1. Quoted description: description: "..."
+    const quotedMatch = fm.match(/description:\s*"([\s\S]*?)"/);
+    if (quotedMatch) {
+      desc = quotedMatch[1];
+    }
+
+    // 2. YAML multi-line (>, >-, |, |-): collect indented lines
+    if (!desc) {
+      const multiMatch = fm.match(/description:\s*[>|]-?\s*\n([\s\S]*?)(?=\n\S|\n*$)/);
+      if (multiMatch) {
+        desc = multiMatch[1]
+          .split("\n")
+          .map((l) => l.replace(/^\s{2,}/, "").trim())
+          .filter(Boolean)
+          .join(" ");
+      }
+    }
+
+    // 3. Single-line description
+    if (!desc) {
+      const singleMatch = fm.match(/description:\s*(.+?)(?:\n|$)/);
+      if (singleMatch) {
+        desc = singleMatch[1];
+      }
+    }
+
+    if (desc) {
+      desc = desc.replace(/\s+/g, " ").trim();
+      // First sentence
+      const sentEnd = desc.match(/[.!?]\s/);
+      if (sentEnd) desc = desc.substring(0, sentEnd.index + 1);
+      if (desc.length > 150) desc = desc.substring(0, 147) + "...";
+      // Reject garbage (too short, only symbols, YAML artifacts)
+      if (desc.length >= 10 && /[a-zA-Z]{3,}/.test(desc)) {
+        return desc;
+      }
+    }
+  }
+  // Fallback: first real paragraph after frontmatter
+  const noFm = content.replace(/^---[\s\S]*?---\s*/, "");
+  const lines = noFm
+    .split("\n")
+    .filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("```") && !l.startsWith("-"));
+  if (lines.length > 0) {
+    let desc = lines[0].trim();
+    const sentEnd = desc.match(/[.!?]\s/);
+    if (sentEnd) desc = desc.substring(0, sentEnd.index + 1);
+    if (desc.length > 150) desc = desc.substring(0, 147) + "...";
+    if (desc.length >= 10 && /[a-zA-Z]{3,}/.test(desc)) {
+      return desc;
+    }
+  }
+  return null;
+}
+
+// Generate a human-readable description from the skill name
+function descFromName(name) {
+  const map = {
+    "expo": "Expo SDK integration for React Native mobile app development.",
+    "scientific": "Scientific computing and research automation toolkit.",
+    // finance
+    "finance-equity-research": "Equity research analysis and investment recommendations.",
+    "finance-financial-analysis": "Financial modeling, valuation, and quantitative analysis.",
+    "finance-investment-banking": "Investment banking deal execution and M&A advisory.",
+    "finance-lseg": "LSEG (London Stock Exchange Group) data integration.",
+    "finance-private-equity": "Private equity deal sourcing and portfolio management.",
+    "finance-spglobal": "S&P Global market intelligence data integration.",
+    "finance-wealth-management": "Wealth management and financial planning advisory.",
+    // terraform
+    "terraform-code-generation": "Generate Terraform HCL code from infrastructure requirements.",
+    "terraform-module-generation": "Create reusable Terraform modules following best practices.",
+    "terraform-provider-development": "Build custom Terraform providers for new infrastructure APIs.",
+    // tob skills without parseable YAML
+    "tob-debug-buttercup": "Debug Buttercup password manager issues and extension failures.",
+    "tob-differential-review": "Security-focused differential code review for pull requests.",
+    "tob-gh-cli": "Automate GitHub workflows using the gh CLI for issues, PRs, and releases.",
+    "tob-static-analysis": "Run and interpret static analysis tools across multiple languages.",
+    "tob-testing-handbook-skills": "Apply Trail of Bits testing handbook best practices.",
+    "tob-workflow-skill-design": "Design and structure new Claude Code skills and workflows.",
+    "tob-yara-authoring": "Author and validate YARA rules for malware detection and threat hunting.",
+    // seo
+    "seo": "Deterministic LLM-first SEO audits for websites, blogs, and repositories.",
+  };
+  if (map[name]) return map[name];
+
+  // Auto-generate from name (strip known prefixes)
+  const cleaned = name
+    .replace(/^(tob|anthropic|agents|cloudflare|sentry|google|finance|terraform)-/, "");
+  const parts = cleaned.split("-");
+  const readable = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(" ");
+  // Make it a full sentence
+  return `${readable} tooling and automation.`;
+}
+
+function main() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error("skills/ directory not found");
+    process.exit(1);
+  }
+
+  const entries = fs.readdirSync(SKILLS_DIR);
+  const catalog = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(SKILLS_DIR, entry);
+    let realDir;
+
+    try {
+      const stats = fs.lstatSync(entryPath);
+      if (stats.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(entryPath);
+        const normalized = linkTarget.replace(/^(\.\.\/)+/, "");
+        realDir = path.join(ROOT, normalized);
+      } else if (stats.isDirectory()) {
+        realDir = entryPath;
+      } else {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+
+    const prefix = entry.split("-")[0];
+    let description = null;
+
+    if (fs.existsSync(realDir) && fs.statSync(realDir).isDirectory()) {
+      // Search recursively for SKILL.md (max depth 4)
+      const skillMd = findSkillMd(realDir, 4);
+      if (skillMd) {
+        description = extractDescription(skillMd);
+      }
+    }
+
+    // Fallback: generate from name
+    if (!description) {
+      description = descFromName(entry);
+    }
+
+    catalog.push({
+      name: entry,
+      source: prefix,
+      description,
+    });
+  }
+
+  catalog.sort((a, b) => a.name.localeCompare(b.name));
+
+  const output = {
+    generated: new Date().toISOString(),
+    total: catalog.length,
+    skills: catalog,
+  };
+
+  fs.mkdirSync(path.dirname(OUT), { recursive: true });
+  fs.writeFileSync(OUT, JSON.stringify(output, null, 2));
+
+  const withDesc = catalog.filter((s) => s.description).length;
+  console.log(`Built catalog: ${output.total} skills, ${withDesc} with descriptions`);
+  console.log(`Output: ${OUT}`);
+}
+
+main();

package/bin/cli.js

@@ -26,6 +26,10 @@ const PLATFORMS = {
     name: "OpenCode",
     dir: path.join(os.homedir(), ".config", "opencode", "skills"),
   },
+  vscode: {
+    name: "VS Code (GitHub Copilot)",
+    dir: path.join(os.homedir(), ".copilot", "skills"),
+  },
   cursor: {
     name: "Cursor",
     dir: null,
@@ -38,7 +42,7 @@ function log(msg) {
 }
 
 function header(msg) {
-  console.log(`\n🧠 ${msg}\n`);
+  console.log(`\n> ${msg}\n`);
 }
 
 function cloneRepo() {
@@ -128,7 +132,7 @@ switch (command) {
       }
     }
 
-    log("\n✅ Done! See CHEATSHEET.md for which skill to use when.");
+    log("\nDone. See CHEATSHEET.md for which skill to use when.");
     log(`   ${SKILL_DIR}/CHEATSHEET.md`);
     break;
   }
@@ -136,7 +140,7 @@ switch (command) {
   case "update": {
     header("Updating Agent Skills...");
     cloneRepo();
-    log("\n✅ All skills updated to latest versions.");
+    log("\nAll skills updated to latest versions.");
     break;
   }