create-vasvibe 2.3.1 → 2.5.0

package/template/schemas/workspace-registry.json

@@ -1,94 +1,94 @@
-{
-  "version": 1,
-  "description": "Curated registry for the Toolsmith agent. Maps project needs (tech stack / phase) to recommended skills + MCP servers, and encodes how to write MCP config for each AI tool platform. Toolsmith reads this as the DEFAULT catalog, then may augment via requirements + find-skills.",
-
-  "stackMappings": {
-    "_comment": "tech-stack / capability keyword -> recommended skills + mcp ids. Match loosely (case-insensitive substring) against project_overview tech stack & key features.",
-    "ui|frontend|react|next|nextjs|vue|svelte|tailwind|shadcn": { "skills": ["ui-ux-pro-max"], "mcp": ["shadcn"] },
-    "postgres|postgresql|prisma|sql|database": { "skills": [], "mcp": ["postgres"] },
-    "e2e|test|testing|playwright|qa": { "skills": [], "mcp": ["playwright"] },
-    "security|auth|oauth|pentest|owasp": { "skills": ["penetration-testing"], "mcp": [] },
-    "*": { "skills": ["find-skills"], "mcp": ["filesystem", "git", "fetch"] }
-  },
-
-  "mcpCatalog": {
-    "_comment": "Common, safe MCP servers. command/args are indicative starting points — Toolsmith MUST verify the current invocation against the live MCP registry (or each server's README) before applying, since package names drift. `runtime` notes whether it ships via npx (Node) or uvx (Python).",
-    "filesystem": {
-      "description": "Read/write files within allowed roots — grounds the agent in the workspace.",
-      "runtime": "npx",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
-      "env": {}
-    },
-    "git": {
-      "description": "Inspect git history, diffs, and status — context for code-aware agents.",
-      "runtime": "uvx",
-      "command": "uvx",
-      "args": ["mcp-server-git"],
-      "env": {}
-    },
-    "fetch": {
-      "description": "Fetch and convert web content (docs, references) into agent-readable text.",
-      "runtime": "uvx",
-      "command": "uvx",
-      "args": ["mcp-server-fetch"],
-      "env": {}
-    },
-    "postgres": {
-      "description": "Query a Postgres database (schema introspection, read queries). Set POSTGRES_URL.",
-      "runtime": "npx",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres", "${POSTGRES_URL}"],
-      "env": { "POSTGRES_URL": "${POSTGRES_URL}" }
-    },
-    "playwright": {
-      "description": "Drive a real browser for E2E testing & verification (Tester agent).",
-      "runtime": "npx",
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest"],
-      "env": {}
-    },
-    "shadcn": {
-      "description": "Search & pull shadcn/ui component examples — pairs with ui-ux-pro-max skill. Verify current invocation (e.g. `npx shadcn@latest mcp`) before applying.",
-      "runtime": "npx",
-      "command": "npx",
-      "args": ["-y", "shadcn@latest", "mcp"],
-      "env": {}
-    }
-  },
-
-  "platformTargets": {
-    "_comment": "How to write MCP config declaratively for each tool. `file` is project-relative. `topLevelKey` is the JSON key holding servers. `entryShape` documents the per-server object shape; substitute command/args/env from mcpCatalog.",
-    "claude-code": {
-      "detect": [".claude/", ".mcp.json"],
-      "file": ".mcp.json",
-      "topLevelKey": "mcpServers",
-      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
-      "skillsDir": ".claude/skills/"
-    },
-    "opencode": {
-      "detect": [".opencode/", "opencode.json"],
-      "file": "opencode.json",
-      "topLevelKey": "mcp",
-      "entryShape": { "type": "local", "command": ["<command>", "<args>"], "enabled": true, "environment": {} },
-      "skillsDir": ".opencode/skills/",
-      "note": "OpenCode merges command+args into a single `command` array and uses `environment` (not `env`). Include \"$schema\": \"https://opencode.ai/config.json\" at the root."
-    },
-    "antigravity": {
-      "detect": [".agents/"],
-      "file": ".agents/mcp.json",
-      "topLevelKey": "mcpServers",
-      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
-      "skillsDir": ".agents/skills/",
-      "note": "Antigravity uses an mcpServers-shaped config. Confirm the exact path your Antigravity build reads (workspace vs global) with the human; .agents/mcp.json is the project-local default."
-    },
-    "github-copilot": {
-      "detect": [".github/prompts/", ".vscode/"],
-      "file": ".vscode/mcp.json",
-      "topLevelKey": "servers",
-      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
-      "skillsDir": null,
-      "note": "Copilot/VS Code uses the `servers` key (not `mcpServers`). Copilot has no skills dir — skills are Claude/OpenCode/Antigravity only."
-    }
-  }
-}
+{
+  "version": 1,
+  "description": "Curated registry for the Toolsmith agent. Maps project needs (tech stack / phase) to recommended skills + MCP servers, and encodes how to write MCP config for each AI tool platform. Toolsmith reads this as the DEFAULT catalog, then may augment via requirements + find-skills.",
+
+  "stackMappings": {
+    "_comment": "tech-stack / capability keyword -> recommended skills + mcp ids. Match loosely (case-insensitive substring) against project_overview tech stack & key features.",
+    "ui|frontend|react|next|nextjs|vue|svelte|tailwind|shadcn": { "skills": ["ui-ux-pro-max"], "mcp": ["shadcn"] },
+    "postgres|postgresql|prisma|sql|database": { "skills": [], "mcp": ["postgres"] },
+    "e2e|test|testing|playwright|qa": { "skills": [], "mcp": ["playwright"] },
+    "security|auth|oauth|pentest|owasp": { "skills": ["penetration-testing"], "mcp": [] },
+    "*": { "skills": ["find-skills"], "mcp": ["filesystem", "git", "fetch"] }
+  },
+
+  "mcpCatalog": {
+    "_comment": "Common, safe MCP servers. command/args are indicative starting points — Toolsmith MUST verify the current invocation against the live MCP registry (or each server's README) before applying, since package names drift. `runtime` notes whether it ships via npx (Node) or uvx (Python).",
+    "filesystem": {
+      "description": "Read/write files within allowed roots — grounds the agent in the workspace.",
+      "runtime": "npx",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "env": {}
+    },
+    "git": {
+      "description": "Inspect git history, diffs, and status — context for code-aware agents.",
+      "runtime": "uvx",
+      "command": "uvx",
+      "args": ["mcp-server-git"],
+      "env": {}
+    },
+    "fetch": {
+      "description": "Fetch and convert web content (docs, references) into agent-readable text.",
+      "runtime": "uvx",
+      "command": "uvx",
+      "args": ["mcp-server-fetch"],
+      "env": {}
+    },
+    "postgres": {
+      "description": "Query a Postgres database (schema introspection, read queries). Set POSTGRES_URL.",
+      "runtime": "npx",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "${POSTGRES_URL}"],
+      "env": { "POSTGRES_URL": "${POSTGRES_URL}" }
+    },
+    "playwright": {
+      "description": "Drive a real browser for E2E testing & verification (Tester agent).",
+      "runtime": "npx",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "env": {}
+    },
+    "shadcn": {
+      "description": "Search & pull shadcn/ui component examples — pairs with ui-ux-pro-max skill. Verify current invocation (e.g. `npx shadcn@latest mcp`) before applying.",
+      "runtime": "npx",
+      "command": "npx",
+      "args": ["-y", "shadcn@latest", "mcp"],
+      "env": {}
+    }
+  },
+
+  "platformTargets": {
+    "_comment": "How to write MCP config declaratively for each tool. `file` is project-relative. `topLevelKey` is the JSON key holding servers. `entryShape` documents the per-server object shape; substitute command/args/env from mcpCatalog.",
+    "claude-code": {
+      "detect": [".claude/", ".mcp.json"],
+      "file": ".mcp.json",
+      "topLevelKey": "mcpServers",
+      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
+      "skillsDir": ".claude/skills/"
+    },
+    "opencode": {
+      "detect": [".opencode/", "opencode.json"],
+      "file": "opencode.json",
+      "topLevelKey": "mcp",
+      "entryShape": { "type": "local", "command": ["<command>", "<args>"], "enabled": true, "environment": {} },
+      "skillsDir": ".opencode/skills/",
+      "note": "OpenCode merges command+args into a single `command` array and uses `environment` (not `env`). Include \"$schema\": \"https://opencode.ai/config.json\" at the root."
+    },
+    "antigravity": {
+      "detect": [".agents/"],
+      "file": ".agents/mcp.json",
+      "topLevelKey": "mcpServers",
+      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
+      "skillsDir": ".agents/skills/",
+      "note": "Antigravity uses an mcpServers-shaped config. Confirm the exact path your Antigravity build reads (workspace vs global) with the human; .agents/mcp.json is the project-local default."
+    },
+    "github-copilot": {
+      "detect": [".github/prompts/", ".vscode/"],
+      "file": ".vscode/mcp.json",
+      "topLevelKey": "servers",
+      "entryShape": { "command": "<command>", "args": ["<args>"], "env": {} },
+      "skillsDir": null,
+      "note": "Copilot/VS Code uses the `servers` key (not `mcpServers`). Copilot has no skills dir — skills are Claude/OpenCode/Antigravity only."
+    }
+  }
+}

package/template/skills-lock.json

@@ -1,11 +1,11 @@
-{
-  "version": 1,
-  "skills": {
-    "find-skills": {
-      "source": "vercel-labs/skills",
-      "sourceType": "github",
-      "skillPath": "skills/find-skills/SKILL.md",
-      "computedHash": "9e1c8b3103f92fa8092568a44fe64858de7c5c9dc65ce4bea8f168080e889cfd"
-    }
-  }
-}
+{
+  "version": 1,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "computedHash": "9e1c8b3103f92fa8092568a44fe64858de7c5c9dc65ce4bea8f168080e889cfd"
+    }
+  }
+}

package/template/specifications/.gitkeep

@@ -1 +1 @@
-# Place specification documents here. The contents of this folder are gitignored by default.
+# Place specification documents here. The contents of this folder are gitignored by default.

package/template/state/knowledge_base/.gitkeep

@@ -1 +1 @@
-# Keep this directory for storing agent bug-fixes patterns and learnings.
+# Keep this directory for storing agent bug-fixes patterns and learnings.

package/template/state/knowledge_base/requirements/.gitkeep

@@ -1 +1 @@
-# Keep this folder tracked by git
+# Keep this folder tracked by git

package/template/tests/.gitkeep

@@ -1 +1 @@
-# Place test files here. The contents of this folder are gitignored by default.
+# Place test files here. The contents of this folder are gitignored by default.

package/template/.agents/workflows/explorer.md

@@ -1,78 +0,0 @@
-# Explorer Agent — Workflow Detail
-
-**Role:** Senior Software Architect & Code Analyst  
-**Trigger:** `/explore-codebase` atau dipanggil Orchestrator sebelum `/build-feature` pada project existing.  
-**Input:** Codebase yang sudah ada di folder `codes/`  
-**Output:** `project_overview.md`, `state/knowledge_base/codebase/inventory.md`, `state/context.json`
-
----
-
-## Kapan Menggunakan Explorer?
-
-Gunakan Explorer (bukan Discovery + Initiator) ketika:
-- Kamu **bergabung ke project yang sudah berjalan** dan perlu memahami kondisinya sebelum mengerjakan fitur baru.
-- Ada **handover codebase** dari tim lain dan tidak ada dokumentasi overview.
-- Kamu ingin **memverifikasi** apakah `project_overview.md` yang ada masih akurat dengan kode terkini.
-- Sebelum menjalankan `/build-feature` atau `/start-fix` pada project existing yang belum punya state.
-
----
-
-## Alur Kerja
-
-```
-codes/ exists?
-     │
-     ├─ YES → Explorer baca kode → tulis project_overview.md + inventory + context.json
-     │              │
-     │              └─ Human review → lanjut ke /build-feature atau /start-fix
-     │
-     └─ NO  → Arahkan ke /plan-project (project baru, mulai dari Discovery)
-```
-
----
-
-## Dokumen yang Dihasilkan
-
-| Dokumen | Path | Deskripsi |
-|---------|------|-----------|
-| Project Overview | `project_overview.md` | Tech stack, fitur, design system — disintesis dari kode |
-| Codebase Inventory | `state/knowledge_base/codebase/inventory.md` | Daftar API endpoints, data models, file penting |
-| Context State | `state/context.json` | Status project saat ini untuk kontinuitas antar-session |
-
----
-
-## Panduan Membaca Kode per Stack
-
-### Node.js / TypeScript (Next.js, Express, NestJS)
-- Root: `package.json`, `tsconfig.json`, `.env.example`
-- Routes: `src/routes/`, `src/app/api/`, `pages/api/`, `src/controllers/`
-- Models: `prisma/schema.prisma`, `src/models/`, `src/entities/`
-- Config: `src/config/`, `next.config.js`, `nest-cli.json`
-
-### Python (FastAPI, Django, Flask)
-- Root: `pyproject.toml`, `requirements.txt`, `setup.py`
-- Routes: `app/routers/`, `app/views.py`, `urls.py`
-- Models: `app/models.py`, `alembic/versions/`
-- Config: `app/config.py`, `settings.py`
-
-### Go
-- Root: `go.mod`, `go.sum`
-- Routes: `internal/handler/`, `internal/api/`, `cmd/`
-- Models: `internal/domain/`, `internal/model/`
-- DB: `internal/repository/`, migration files
-
-### Mobile (Flutter, React Native)
-- Root: `pubspec.yaml` atau `package.json`
-- Screens: `lib/screens/`, `src/screens/`
-- State: `lib/providers/`, `lib/bloc/`, `src/store/`
-- API: `lib/services/`, `src/api/`
-
----
-
-## Output Quality Rules
-
-1. **Jangan berasumsi** — setiap klaim HARUS dari file yang dibaca. Tandai dengan `[confirmed]`, `[inferred]`, atau `[unknown]`.
-2. **Inventarisasi endpoints lengkap** — jangan skip; ini akan dipakai Analyst untuk API Contract.
-3. **Tandai incomplete features** — gunakan `[~]` untuk partial, `[ ]` untuk planned/TODO.
-4. **Catat technical debt** — tulis di `notes` field `context.json` agar agent berikutnya tahu.
-5. **Jangan timpa state yang masih valid** — jika `state/context.json` sudah ada dan masih relevan, merge informasi baru ke dalamnya.

package/template/.agents/workflows/logger.md

@@ -1,117 +0,0 @@
-# Logger Agent — Workflow Detail
-
-**Role:** Technical Change Recorder & Analyst  
-**Trigger:** Dipanggil kapan saja oleh human — *"catat perubahan ini"*, *"log apa yang baru saja terjadi"*, atau cukup *"logger"*.  
-**Input:** Deskripsi perubahan dari human, dan/atau analisa sesi / kode secara mandiri  
-**Output:** Entry baru di `task/[TASK-ID]/dev_log.md` + baris baru di Status Log task detail file
-
----
-
-## Kapan Memanggil Logger?
-
-| Situasi | Cara panggil |
-|---------|--------------|
-| Baru selesai fix bug secara manual | *"Logger, catat: fix bug validasi di form login"* |
-| Selesai coding satu sesi, ingin rekap tercatat | *"Logger, analisa apa yang baru saja dikerjakan dan catat"* |
-| Mau pastikan enhancement tercatat sebelum tutup sesi | *"Logger"* (tanpa argumen — logger akan tanya / analisa sendiri) |
-| Ingin log lintas beberapa task | *"Logger, tadi ada 3 perubahan: ..."* |
-
----
-
-## Tipe Perubahan & Klasifikasinya
-
-```
-Sesuatu yang salah/rusak diperbaiki?
-    └─ YES → fix
-
-Kemampuan baru ditambahkan?
-    └─ YES → enhancement
-
-Kode diubah tanpa ubah perilaku?
-    └─ YES → refactor
-
-Config, dependency, atau dokumentasi?
-    └─ YES → chore
-```
-
-**Aturan tie-breaker:** Jika satu perubahan bisa fix DAN enhancement (mis. memperbaiki cara feature bekerja sambil menambah field baru), buat **dua entry terpisah** — satu fix, satu enhancement.
-
----
-
-## Struktur Dokumen yang Diisi
-
-### 1. Task Detail File — Status Log
-**Path:** `task/[TASK-ID]_[nama-task]/[TASK-ID]_[nama-task].md`
-
-Logger menambahkan baris baru di tabel Status Log yang sudah ada:
-```markdown
-| [timestamp] | logger | [tipe] | [deskripsi 1 baris] |
-```
-
-### 2. Dev Log File
-**Path:** `task/[TASK-ID]_[nama-task]/dev_log.md`
-
-Logger membuat file ini jika belum ada, atau menambah entry di Revision History:
-```markdown
-## [timestamp] — [tipe]: [judul]
-
-**Type:** fix / enhancement / refactor / chore
-**Changed by:** [human / agent]
-
-### What Changed
-[Narasi singkat]
-
-### Files Affected
-- `path/file` — apa yang berubah
-
-### Notes
-[Catatan teknis jika ada]
-```
-
-### 3. Fallback — Untracked Changes
-Jika tidak ada task yang cocok, tulis ke:
-**Path:** `task/untracked/[YYYY-MM-DD]_untracked_changes.md`
-
-```markdown
-# Untracked Changes — [YYYY-MM-DD]
-
-## [HH:MM] — [tipe]: [judul]
-[Deskripsi perubahan]
-**Suggested Task:** [nama task yang mungkin relevan, atau "belum ada task terdaftar"]
-```
-
----
-
-## Alur Keputusan Logger
-
-```
-Human panggil logger
-        │
-        ├─ Ada deskripsi eksplisit? ──→ Gunakan sebagai basis
-        │
-        ├─ Tidak ada info? ──────────→ Tanya 1-2 pertanyaan ringkas
-        │
-        └─ Minta analisa mandiri? ───→ Periksa file yang berubah / konteks sesi
-                    │
-                    ▼
-        Klasifikasi tipe perubahan
-                    │
-                    ▼
-        Cari task yang cocok di task_list.md
-                    │
-                    ├─ Ketemu → tulis log di task tersebut
-                    ├─ Lintas task → tulis di semua task relevan
-                    └─ Tidak ketemu → tulis di task/untracked/
-                    │
-                    ▼
-        Konfirmasi ringkasan ke human
-```
-
----
-
-## Aturan Kualitas Log
-
-1. **Deskripsi konkret** — bukan *"fix bug"* tapi *"fix: email tidak divalidasi saat domain kosong"*
-2. **Satu entry per perubahan logis** — 3 perubahan berbeda = 3 entry
-3. **Tidak mengarang** — jika tidak yakin apa yang berubah, tanya dulu
-4. **Timestamp real** — selalu gunakan waktu saat ini, bukan placeholder

package/template/.claude/settings.local.json

@@ -1,35 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__visualize__read_me",
-      "mcp__visualize__show_widget",
-      "Bash(grep -n '```prompt' agent/workflows/pm.md)",
-      "Bash(grep -n \"^\\\\`\\\\`\\\\`$\" agent/workflows/pm.md)",
-      "Bash(grep -n \"^\\\\`\\\\`\\\\`$\" .opencode/agents/pm.md)",
-      "Bash(grep -n \"Developer Agent\\\\|^\\\\`\\\\`\\\\`$\" packages/create-vasvibe/template/.opencode/agents/fixer.md)",
-      "Bash(grep -n \"^\\\\`\\\\`\\\\`$\" packages/create-vasvibe/template/.opencode/agents/pm.md)",
-      "Bash(grep '```prompt\\\\|```$' agent/workflows/pm.md .opencode/agents/pm.md .claude/agents/pm.md packages/create-vasvibe/template/.opencode/agents/pm.md)",
-      "Bash(grep -n \"^.\\\\`\\\\`\\\\`prompt\\\\|^.\\\\`\\\\`\\\\`$\" agent/workflows/pm.md .opencode/agents/pm.md .claude/agents/pm.md packages/create-vasvibe/template/.opencode/agents/pm.md)",
-      "Bash(git add *)",
-      "Bash(git commit -m ' *)",
-      "Bash(node -e \"const pkg = require\\('/Users/admin/Development/vas_vibe/.opencode/node_modules/@opencode-ai/plugin/package.json'\\); console.log\\(pkg.version\\)\")",
-      "Bash(npm run *)",
-      "Bash(curl -s https://code.claude.com/docs/en/sub-agents.md)",
-      "Bash(git push *)",
-      "WebFetch(domain:opencode.ai)",
-      "WebSearch",
-      "WebFetch(domain:atamel.dev)",
-      "Bash(xargs -I {} basename {} .prompt.md)",
-      "Bash(xargs -I{} basename {} .md)",
-      "Bash(sed -i '' 's/Invoke \\\\*\\\\*Developer\\\\*\\\\* \\(fullstack tunggal\\)/Invoke **Fullstack** \\(fullstack tunggal\\)/g' agent/workflows/orchestrator.md)",
-      "Bash(sed -i '' 's/Developer fullstack; skip/Fullstack; skip/g' agent/workflows/orchestrator.md)",
-      "Bash(python3 -)",
-      "Bash(python3 -c \"import json; json.load\\(open\\('schemas/workspace-registry.json'\\)\\); print\\('registry OK'\\)\")",
-      "Bash(python3 -c \"import json; json.load\\(open\\('schemas/workspace-manifest.template.json'\\)\\); print\\('manifest OK'\\)\")",
-      "Bash(python3 -c \"import json; json.load\\(open\\('.agents/agents/toolsmith/agent.json'\\)\\); print\\('agent.json OK'\\)\")",
-      "Bash(node scripts/sync-template.mjs)",
-      "Bash(cp /Users/admin/Development/vas_vibe/packages/create-vasvibe/template/.claude/agents/explorer.md /Users/admin/Development/vas_vibe/.opencode/agents/explorer.md && cp /Users/admin/Development/vas_vibe/packages/create-vasvibe/template/agent/workflows/explorer.md /Users/admin/Development/vas_vibe/.agents/workflows/explorer.md)",
-      "Bash(cp /Users/admin/Development/vas_vibe/packages/create-vasvibe/template/.claude/agents/logger.md /Users/admin/Development/vas_vibe/.opencode/agents/logger.md && cp /Users/admin/Development/vas_vibe/packages/create-vasvibe/template/agent/workflows/logger.md /Users/admin/Development/vas_vibe/.agents/workflows/logger.md && echo \"done\")"
-    ]
-  }
-}

package/template/.claude/skills/find-skills/SKILL.md

@@ -1,142 +0,0 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Check the Leaderboard First
-
-Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
-
-For example, top skills for web development include:
-- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
-- `anthropics/skills` — Frontend design, document processing (100K+ installs)
-
-### Step 3: Search for Skills
-
-If the leaderboard doesn't cover the user's need, run the find command:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-### Step 4: Verify Quality Before Recommending
-
-**Do not recommend a skill based solely on search results.** Always verify:
-
-1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
-2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
-3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
-
-### Step 5: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install count and source
-3. The install command they can run
-4. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-(185K installs)
-
-To install it:
-npx skills add vercel-labs/agent-skills@react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
-```
-
-### Step 6: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```