@cangurel81/skill-router 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Gurel
+
+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

@@ -1,3 +1,254 @@
-# Temporary Holding Version
+# skill-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/cangurel81/skill-router/actions/workflows/test.yml/badge.svg)](https://github.com/cangurel81/skill-router/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@cangurel81/skill-router.svg)](https://www.npmjs.com/package/@cangurel81/skill-router)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
+
+Index, classify and search a large agent-skill catalogue — so the agent stops guessing which of
+your 900 skills applies, and so you notice when most of the catalogue is duplicated.
+
+Zero dependencies. Node 18+. One file. No config required.
+
+```bash
+npx @cangurel81/skill-router --search expo
+```
+
+---
+
+## The problem it solves
+
+Once a machine has more than a few dozen installed skills, two failures appear and neither one is
+visible:
+
+**1. The agent guesses.** It names a skill that does not exist, or writes from scratch something
+already installed forty times over, because it cannot tell which of a thousand descriptions
+matches the task.
+
+**2. The catalogue silently fills with copies.** A repository ships `skills/` plus
+`docs/ja-JP/skills`, `docs/zh-CN/skills` and a mirrored `pi/core/skills` tree. Every one is
+discovered as a separate capability. Your inventory says 966 skills; 651 of them are the same 315
+translated or mirrored. Every search returns duplicates, and the counts you reason from are wrong.
+
+`skill-router` measures both and answers the routing question with paths, not vibes.
+
+## What it does
+
+| Step | Detail |
+|---|---|
+| Finds roots | `--root` flags, `SKILL_ROOTS`, or well-known install locations |
+| Walks | up to 5 levels deep, skips `node_modules`, `.git`, `dist`, `build`, `vendor` |
+| Parses | `SKILL.md` YAML frontmatter without a YAML dependency (block scalars included) |
+| Classifies | 13 domain groups by weighted keyword match on name + description |
+| De-duplicates | two detectors: `docs/<locale>/` trees, and byte-identical files via SHA-1 |
+| Reports | inventory, per-domain counts, duplicate names, unusable descriptions |
+| Searches | ranked matches, word-boundary aware, with full file paths |
+
+It never edits, deletes or installs anything. It reads and reports.
+
+## Install
+
+Pick one. They all run the same three files.
+
+**npm — recommended**
+
+```bash
+npx @cangurel81/skill-router --root ~/.claude/skills --search testing   # no install
+npm i -g @cangurel81/skill-router                                       # global command
+```
+
+The package installs the command `skill-router`, so after a global install you can drop the
+`npx @cangurel81/` prefix:
+
+```bash
+skill-router --search expo
+```
+
+**Clone and run directly**
+
+```bash
+git clone https://github.com/cangurel81/skill-router.git
+cd skill-router
+node bin/skill-router.mjs
+```
+
+**Use as an agent skill**
+
+Register the repo's `skills/` folder as a skill root, in whichever harness you use:
+
+```jsonc
+// opencode.jsonc
+{ "skills": ["~/code/skill-router/skills"] }
+```
+
+```bash
+# Claude Code
+ln -s ~/code/skill-router/skills/skill-router ~/.claude/skills/skill-router
+```
+
+The skill file at `skills/skill-router/SKILL.md` teaches the agent the routing procedure: name the
+domain, search two or three words, read the path, then open only the winner.
+
+**Copy the script**
+
+```bash
+curl -O https://raw.githubusercontent.com/cangurel81/skill-router/main/bin/skill-router.mjs
+node skill-router.mjs --root ~/.claude/skills --search testing
+```
+
+## Usage
+
+```bash
+node bin/skill-router.mjs                       # inventory of every root
+node bin/skill-router.mjs --search expo         # ranked matches
+node bin/skill-router.mjs --search video --group video
+node bin/skill-router.mjs --groups              # domain keys and counts
+node bin/skill-router.mjs --dupes               # same name, different folders
+node bin/skill-router.mjs --weak                # descriptions too short to route on
+node bin/skill-router.mjs --json                # machine-readable, all records
+node bin/skill-router.mjs --write ./index       # write index/skills.json
+node bin/skill-router.mjs --help
+```
+
+Exit codes: `0` success, `1` no skill root found.
+
+### Choosing roots
+
+```bash
+node bin/skill-router.mjs --root ./skills --root ~/.claude/skills
+SKILL_ROOTS=~/.claude/skills:./skills node bin/skill-router.mjs   # ';' on Windows
+```
+
+`--root` wins over `SKILL_ROOTS`, which wins over the defaults:
+
+```
+./.agents/skills        ./.opencode/skill       ./.claude/skills      ./skills
+~/.claude/skills        ~/.codex/skills         ~/.kimi-code/skills
+~/.config/opencode/skills        ~/.config/opencode/local-skills
+```
+
+## Real output
+
+Run against a real repository that registers its root instead of its `skills/` folder:
+
+```console
+$ node bin/skill-router.mjs --root ~/.config/opencode/vendor/affaan-m__ecc
+
+SKILL CATALOGUE
+================================================================
+Roots with skills : 1
+  /home/me/.config/opencode/vendor/affaan-m__ecc
+    966 files, 315 genuine
+
+Total SKILL.md files      : 966
+  genuine                 : 315
+  copies                  : 651 (67%)  [locale 518, identical 133]
+  unique names (genuine)  : 315
+  duplicate names         : 0
+  weak descriptions       : 0
+
+By group (genuine only):
+  Agent / LLM / orchestration             105
+  Other                                    45
+  Code quality / testing / process         30
+  Backend / API / databases                28
+  Mobile / Expo / React Native             20
+  Frontend / UI / design systems           18
+  Infra / DevOps / network                 16
+  Marketing / content / social             12
+  Video / motion / audio                   12
+  Data / research / analytics              10
+  Security / compliance                     9
+  Desktop / documents / office              7
+  SEO / GEO / search                        3
+```
+
+The honest reading: 315 real capabilities, 651 files that only exist because the same skills were
+translated into six languages and mirrored once. Register `.../ECC-main/skills` instead of
+`.../ECC-main` and 966 becomes 315.
+
+Searching is where it earns its place:
+
+```console
+$ node bin/skill-router.mjs --search caption
+
+"caption" -> 1 match(es)
+
+* remotion-video-creation  [Video / motion / audio]
+  Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D,
+  animations, audio, captions, charts, transitions, and more...
+  /home/me/.config/opencode/vendor/affaan-m__ecc/ECC-main/skills/remotion-video-creation/SKILL.md
+```
+
+The path is not decoration. Two skills can share a name and differ completely; the path is the only
+thing that says which repository you are actually loading.
+
+## Reading the report
+
+Every number has an action attached:
+
+| Signal | Means | Do this |
+|---|---|---|
+| `copies` above 10% | a root points at a repository, not at its `skills/` folder | point it at the real skill folder |
+| `duplicate names` high | two repos ship the same skill; the agent may load either | drop one root, or accept the newer repo |
+| `weak descriptions` | description under 25 chars, cannot be routed to | extend it, or treat the skill as absent |
+| `Other` group large | descriptions too vague to classify | the same skills are also unroutable |
+| a domain at `0` | genuine capability gap | this is where a new skill is justified |
+
+`--dupes` prints both paths for every collision, so you can diff them before deciding.
+`--weak` prints the character count, so "too short" is a number and not an opinion.
+
+## When a new skill is justified
+
+All three must hold:
+
+1. `--search` over three plausible terms returns nothing relevant.
+2. The gap is knowledge no public repository could ship — local toolchain, local traps, private
+   systems.
+3. The knowledge repeats. It has already cost time twice.
+
+Otherwise extend an existing skill or fix its description. A fourth near-duplicate makes the
+catalogue worse, not more capable.
+
+## How duplicate detection works
+
+Two independent detectors, because the two failure modes look different:
+
+**Locale trees.** Any path matching `docs/<lang>/…` where `<lang>` is a locale slug (`tr`, `ja-JP`,
+`zh-CN`, `pt_BR`) is a translated copy. This catches translations, which are *not* byte-identical
+and would otherwise look like 183 new skills.
+
+**Identical files.** Skills sharing a name whose `SKILL.md` has the same SHA-1 are the same file
+copied. This catches mirrored trees (`pi/core/skills`, a vendored second copy) with no naming
+convention to key on. The copy inside a real `skills/` directory wins as canonical, then the
+shortest path, then lexicographic order — so the reported path never sends you to the mirror, and
+the result is stable across runs and platforms.
+
+Nothing is auto-deleted. Deleting skill folders is a decision with consequences; the tool hands you
+the list and the path.
+
+## Development
+
+```bash
+npm test        # syntax check + smoke test
+node test/smoke.mjs
+```
+
+The smoke test builds a throwaway catalogue containing one genuine pair, one translated locale
+copy and one byte-identical mirror, runs the real CLI, and asserts the counts, the canonical path,
+the miss path and the exit codes. CI runs it on Linux, macOS and Windows across Node 18, 20 and 22 —
+the script must behave identically on all three, since path separators are the main portability
+risk here.
+
+## Limits
+
+- It indexes discoverability, not quality. A short description is a routing failure, not a bad
+  skill.
+- It reads frontmatter only. It does not open skill bodies — that is a separate review pass.
+- Classification is keyword-based and will occasionally land a skill in the wrong group. Search
+  covers all groups by default, so this only costs you when you filter with `--group`.
+- It does not fetch, install or update skills.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/skill-router.mjs

@@ -0,0 +1,420 @@
+#!/usr/bin/env node
+/**
+ * skill-router - index, classify and search a large agent-skill catalogue.
+ *
+ * Once a machine has more than a few dozen skills, two things break:
+ * the agent cannot tell which skill applies, and nobody notices when the
+ * catalogue is half full of duplicated or translated copies.
+ *
+ * This tool scans every skill root, reads each SKILL.md frontmatter, groups
+ * skills by domain, separates real capabilities from locale/duplicate trees,
+ * and answers "which skill fits this job?" with ranked matches and paths.
+ *
+ * Zero dependencies. Node 18+.
+ *
+ *   node bin/skill-router.mjs                     summary of every root
+ *   node bin/skill-router.mjs --search expo       ranked matches
+ *   node bin/skill-router.mjs --search video --group video
+ *   node bin/skill-router.mjs --groups            group keys and counts
+ *   node bin/skill-router.mjs --dupes             same name, different folders
+ *   node bin/skill-router.mjs --weak              unusable descriptions
+ *   node bin/skill-router.mjs --json              machine-readable output
+ *
+ * Roots come from, in order:
+ *   1. --root <path>            (repeatable, wins over everything)
+ *   2. SKILL_ROOTS env var      (paths separated by the OS path delimiter)
+ *   3. well-known locations     (see DEFAULT_ROOTS)
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, dirname, basename, resolve, delimiter } from 'node:path';
+import { homedir } from 'node:os';
+
+const HOME = homedir();
+const SKIP_DIRS = new Set(['node_modules', '.git', '.cache', 'cache', 'dist', 'build', 'vendor']);
+const MAX_DEPTH = 5;
+const WEAK_DESCRIPTION = 25;
+
+const DEFAULT_ROOTS = [
+  join(process.cwd(), '.agents', 'skills'),
+  join(process.cwd(), '.opencode', 'skill'),
+  join(process.cwd(), '.claude', 'skills'),
+  join(process.cwd(), 'skills'),
+  join(HOME, '.config', 'opencode', 'skills'),
+  join(HOME, '.config', 'opencode', 'local-skills'),
+  join(HOME, '.config', 'opencode', 'skill'),
+  join(HOME, '.claude', 'skills'),
+  join(HOME, '.codex', 'skills'),
+  join(HOME, '.kimi-code', 'skills'),
+];
+
+/* ------------------------------------------------------------------ groups */
+
+const GROUPS = [
+  { key: 'seo', label: 'SEO / GEO / search', words: ['seo', 'serp', 'backlink', 'hreflang', 'sitemap', 'schema markup', 'keyword research', 'ai overview', 'citability', 'llms.txt', 'local seo', 'search console', 'core web vitals'] },
+  { key: 'video', label: 'Video / motion / audio', words: ['video', 'remotion', 'animation', 'motion graphic', 'ffmpeg', 'caption', 'subtitle', 'lottie', 'audiogram', 'music', 'text-to-speech', 'tts', 'voiceover', 'shorts', 'reels', 'waveform', 'slideshow', 'lower third', 'countdown'] },
+  { key: 'wordpress', label: 'WordPress / WooCommerce', words: ['wordpress', 'woocommerce', 'wp-cli', 'elementor', 'gutenberg', 'custom post type', 'plugin header'] },
+  { key: 'mobile', label: 'Mobile / Expo / React Native', words: ['expo', 'react native', 'android', 'ios', 'swift', 'kotlin', 'flutter', 'dart', 'app store', 'play store', 'eas build'] },
+  { key: 'frontend', label: 'Frontend / UI / design systems', words: ['react', 'next.js', 'vue', 'nuxt', 'svelte', 'angular', 'css', 'tailwind', 'frontend', 'design system', 'accessibility', 'a11y', 'gsap', 'three.js', 'd3.js', 'component library'] },
+  { key: 'backend', label: 'Backend / API / databases', words: ['laravel', 'symfony', 'spring boot', 'quarkus', 'mybatis', 'jpa', 'hibernate', 'php', 'django', 'fastapi', 'nestjs', 'express', 'rails', 'api design', 'rest api', 'graphql', 'microservice', 'postgres', 'mysql', 'redis', 'database', 'orm', 'query optimization', 'schema design'] },
+  { key: 'marketing', label: 'Marketing / content / social', words: ['marketing', 'content strategy', 'social media', 'linkedin', 'twitter', 'newsletter', 'copywriting', 'brand voice', 'campaign', 'carousel', 'content brief', 'blog post', 'outreach', 'sales'] },
+  { key: 'agent', label: 'Agent / LLM / orchestration', words: ['agent', 'llm', 'prompt', 'mcp', 'subagent', 'orchestrat', 'harness', 'eval', 'rag', 'memory', 'autonomous', 'skill', 'claude code', 'context window'] },
+  { key: 'security', label: 'Security / compliance', words: ['security', 'vulnerab', 'pentest', 'hipaa', 'gdpr', 'compliance', 'phi', 'secret', 'threat model', 'access control'] },
+  { key: 'infra', label: 'Infra / DevOps / network', words: ['docker', 'kubernetes', 'deploy', 'ci/cd', 'github actions', 'nginx', 'network', 'vlan', 'dns', 'vpn', 'homelab', 'wireguard', 'cloud'] },
+  { key: 'data', label: 'Data / research / analytics', words: ['data pipeline', 'analytics', 'research', 'scrap', 'crawl', 'etl', 'sql', 'pandas', 'statistic', 'dashboard', 'benchmark'] },
+  { key: 'code', label: 'Code quality / testing / process', words: ['test-driven', 'unit test', 'tdd', 'code review', 'debug', 'refactor', 'coding standard', 'typescript', 'python', 'golang', 'rust', 'java', 'lint', 'codebase', 'architecture decision'] },
+  { key: 'desktop', label: 'Desktop / documents / office', words: ['windows', 'desktop', 'pywinauto', 'uiautomation', 'screenshot', 'excel', 'pdf', 'pandoc', 'document', 'slides', 'presentation'] },
+];
+
+function classify(name, description) {
+  const text = `${name} ${description}`.toLowerCase();
+  let best = null;
+  let bestScore = 0;
+  for (const g of GROUPS) {
+    let score = 0;
+    for (const w of g.words) if (text.includes(w)) score += w.includes(' ') || w.includes('-') ? 3 : 1;
+    if (score > bestScore) {
+      bestScore = score;
+      best = g;
+    }
+  }
+  return best ?? { key: 'other', label: 'Other' };
+}
+
+/* ------------------------------------------------------------------- roots */
+
+function rootsFromArgs(argv) {
+  const roots = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root' && argv[i + 1]) roots.push(resolve(argv[i + 1]));
+  }
+  if (roots.length) return roots;
+
+  const env = process.env.SKILL_ROOTS;
+  if (env) {
+    const fromEnv = env.split(delimiter).map((p) => p.trim()).filter(Boolean).map(resolve);
+    if (fromEnv.length) return fromEnv;
+  }
+  return DEFAULT_ROOTS;
+}
+
+function findSkillFiles(root) {
+  const found = [];
+  const stack = [{ path: root, depth: 0 }];
+  while (stack.length) {
+    const { path, depth } = stack.pop();
+    if (depth > MAX_DEPTH) continue;
+    let entries;
+    try {
+      entries = readdirSync(path, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = join(path, e.name);
+      if (!e.isDirectory()) {
+        if (e.name === 'SKILL.md') found.push(full);
+        continue;
+      }
+      if (SKIP_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+      try {
+        if (statSync(full).isDirectory()) stack.push({ path: full, depth: depth + 1 });
+      } catch {
+        /* unreadable */
+      }
+    }
+  }
+  return found;
+}
+
+/* -------------------------------------------------------------- frontmatter */
+
+function parseFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') return {};
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end < 0) return {};
+
+  const fields = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([A-Za-z_-]+):\s*(.*)$/);
+    if (!m) continue;
+    const [, key, raw] = m;
+    const value = raw.trim();
+    if (['', '|', '>', '|-', '>-', '|+', '>+'].includes(value)) {
+      const cont = [];
+      while (i + 1 < end && /^\s+\S/.test(lines[i + 1])) cont.push(lines[++i].trim());
+      fields[key] = cont.join(' ').trim();
+    } else {
+      fields[key] = value.replace(/^["']|["']$/g, '').trim();
+    }
+  }
+  return fields;
+}
+
+/* --------------------------------------------------------------- copy trees */
+
+/**
+ * Translated documentation trees are the most common source of phantom
+ * skills: a repo ships docs/<locale>/skills alongside the real ones and every
+ * locale is discovered as a separate capability. They add no reach.
+ */
+const LOCALE_SEGMENT = /^[a-z]{2}(?:[-_][A-Za-z]{2,4})?$/;
+
+function isLocaleCopy(path) {
+  const parts = path.split(/[\\/]/);
+  for (let i = 0; i < parts.length - 1; i++) {
+    if ((parts[i] === 'docs' || parts[i] === 'doc') && LOCALE_SEGMENT.test(parts[i + 1])) return true;
+  }
+  return false;
+}
+
+/* -------------------------------------------------------------------- scan */
+
+function scan(roots) {
+  const records = [];
+  const seen = new Set();
+
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const file of findSkillFiles(root)) {
+      if (seen.has(file)) continue;
+      seen.add(file);
+      let fm = {};
+      let text = '';
+      try {
+        text = readFileSync(file, 'utf8');
+        fm = parseFrontmatter(text);
+      } catch {
+        /* unreadable */
+      }
+      const name = fm.name || basename(dirname(file));
+      const description = (fm.description || '').replace(/\s+/g, ' ').trim();
+      const group = classify(name, description);
+      const localeCopy = isLocaleCopy(file);
+      records.push({
+        name,
+        description,
+        group: group.key,
+        groupLabel: group.label,
+        path: file,
+        root,
+        copy: localeCopy,
+        origin: localeCopy ? 'locale' : null,
+        hash: createHash('sha1').update(text).digest('hex'),
+        disabled: String(fm['disable-model-invocation'] ?? '').toLowerCase() === 'true',
+        weak: description.length < WEAK_DESCRIPTION,
+      });
+    }
+  }
+
+  // Second detector: byte-identical files. Repos often ship a mirrored tree
+  // (a second copy of skills/ under another folder) that is not a locale copy
+  // and therefore escapes the path rule.
+  //
+  // Canonical selection matters: a file under a real `skills/` directory always
+  // beats a mirror, otherwise a folder named "mirror" can win on path length and
+  // the reported path sends the reader to the copy.
+  const canonicalScore = (r) => [/[\\/]skills[\\/]/i.test(r.path) ? 0 : 1, r.path.length];
+  const canonical = (a, b) => {
+    const [ax, ay] = canonicalScore(a);
+    const [bx, by] = canonicalScore(b);
+    return ax - bx || ay - by || a.path.localeCompare(b.path);
+  };
+
+  const byContent = new Map();
+  for (const r of records) {
+    if (r.copy) continue;
+    const key = `${r.name.toLowerCase()}|${r.hash}`;
+    const list = byContent.get(key) ?? [];
+    list.push(r);
+    byContent.set(key, list);
+  }
+  for (const list of byContent.values()) {
+    if (list.length < 2) continue;
+    list.sort(canonical);
+    for (const r of list.slice(1)) {
+      r.copy = true;
+      r.origin = 'duplicate';
+    }
+  }
+
+  for (const r of records) delete r.hash;
+  records.sort((a, b) => a.name.localeCompare(b.name));
+  return records;
+}
+
+/* ----------------------------------------------------------------- reports */
+
+function stat(records) {
+  const genuine = records.filter((r) => !r.copy);
+  const copies = records.length - genuine.length;
+  const byGroup = new Map();
+  for (const r of genuine) byGroup.set(r.groupLabel, (byGroup.get(r.groupLabel) || 0) + 1);
+
+  const byName = new Map();
+  for (const r of genuine) {
+    const list = byName.get(r.name.toLowerCase()) || [];
+    list.push(r);
+    byName.set(r.name.toLowerCase(), list);
+  }
+  const dupes = [...byName.values()].filter((l) => l.length > 1);
+
+  return {
+    total: records.length,
+    genuine: genuine.length,
+    copies,
+    localeCopies: records.filter((r) => r.origin === 'locale').length,
+    duplicateCopies: records.filter((r) => r.origin === 'duplicate').length,
+    uniqueNames: new Set(genuine.map((r) => r.name.toLowerCase())).size,
+    byGroup,
+    dupes,
+    weak: genuine.filter((r) => r.weak),
+    disabled: genuine.filter((r) => r.disabled).length,
+    roots: [...new Set(records.map((r) => r.root))],
+  };
+}
+
+function summary(records) {
+  const s = stat(records);
+  const out = [];
+  out.push('SKILL CATALOGUE');
+  out.push('='.repeat(64));
+  out.push(`Roots with skills : ${s.roots.length}`);
+  for (const root of s.roots) {
+    const all = records.filter((r) => r.root === root).length;
+    const real = records.filter((r) => r.root === root && !r.copy).length;
+    out.push(`  ${root}`);
+    out.push(`    ${all} files, ${real} genuine`);
+  }
+  out.push('');
+  out.push(`Total SKILL.md files      : ${s.total}`);
+  out.push(`  genuine                 : ${s.genuine}`);
+  out.push(
+    `  copies                  : ${s.copies}${s.total ? ` (${Math.round((s.copies / s.total) * 100)}%)` : ''}` +
+      `  [locale ${s.localeCopies}, identical ${s.duplicateCopies}]`,
+  );
+  out.push(`  unique names (genuine)  : ${s.uniqueNames}`);
+  out.push(`  duplicate names         : ${s.dupes.length}`);
+  out.push(`  weak descriptions       : ${s.weak.length}`);
+  out.push('');
+  out.push('By group (genuine only):');
+  for (const [label, n] of [...s.byGroup.entries()].sort((a, b) => b[1] - a[1])) {
+    out.push(`  ${label.padEnd(38)} ${String(n).padStart(4)}`);
+  }
+  return out.join('\n');
+}
+
+function search(records, query, groupFilter) {
+  const q = query.toLowerCase().trim();
+  if (!q) return 'Error: --search needs a query.';
+  const pool = records.filter(
+    (r) => !r.copy && (!groupFilter || r.group === groupFilter || r.groupLabel.toLowerCase().includes(groupFilter)),
+  );
+
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Plural tolerance so "captions" still finds "caption".
+  const forms = new Set([q, q.endsWith('s') ? q.slice(0, -1) : `${q}s`]);
+  const alts = [...forms].map(escape).join('|');
+  // A match must sit on real word boundaries: "expo" must not match "exposed".
+  const wordRe = new RegExp(`(^|[^a-z0-9])(${alts})(?![a-z0-9])`);
+
+  const scored = pool
+    .map((r) => {
+      const name = r.name.toLowerCase();
+      const segments = name.split(/[^a-z0-9+#.]+/).filter(Boolean);
+      let score = 0;
+      if (name === q) score += 100;
+      if (segments.some((s) => forms.has(s))) score += 60;
+      else if (name.includes(q)) score += 15; // weak: tie-breaker only
+      if (wordRe.test(name)) score += 20;
+      if (wordRe.test(r.description.toLowerCase())) score += 25;
+      return { r, score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score || a.r.name.localeCompare(b.r.name));
+
+  if (!scored.length) return `No skill matches "${query}".`;
+  const out = [`"${query}" -> ${scored.length} match(es)`, ''];
+  for (const { r } of scored.slice(0, 25)) {
+    out.push(`* ${r.name}  [${r.groupLabel}]`);
+    if (r.description) out.push(`  ${r.description.slice(0, 220)}${r.description.length > 220 ? '...' : ''}`);
+    out.push(`  ${r.path}`);
+  }
+  return out.join('\n');
+}
+
+function groupList(records) {
+  const s = stat(records);
+  const rows = [...s.byGroup.entries()].sort((a, b) => b[1] - a[1]);
+  const out = rows.map(([label, n]) => {
+    const key = GROUPS.find((g) => g.label === label)?.key ?? 'other';
+    return `${key.padEnd(12)} ${label.padEnd(38)} ${n}`;
+  });
+  if (rows.length) out.unshift('key          label                                  count');
+  return out.join('\n');
+}
+
+function dupes(records) {
+  const s = stat(records);
+  if (!s.dupes.length) return 'No duplicate names.';
+  const out = [`${s.dupes.length} duplicate name(s):`];
+  for (const list of s.dupes) {
+    out.push('');
+    out.push(`${list[0].name} (${list.length})`);
+    for (const r of list) out.push(`  ${r.path}`);
+  }
+  return out.join('\n');
+}
+
+function weak(records) {
+  const s = stat(records);
+  if (!s.weak.length) return 'No weak descriptions.';
+  return s.weak.map((r) => `${r.name}  (${r.description.length} chars)  ${r.path}`).join('\n');
+}
+
+/* --------------------------------------------------------------------- cli */
+
+const argv = process.argv.slice(2);
+const valueOf = (flag) => {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+};
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(readFileSync(new URL(import.meta.url), 'utf8').split('*/')[0].replace(/^#!.*\n/, ''));
+  process.exit(0);
+}
+
+const roots = rootsFromArgs(argv);
+const records = scan(roots);
+
+if (!roots.some((r) => existsSync(r))) {
+  console.error('No skill root found. Pass --root <path> or set SKILL_ROOTS.');
+  process.exit(1);
+}
+
+if (argv.includes('--json')) {
+  console.log(JSON.stringify(records, null, 2));
+} else if (argv.includes('--search') || argv.includes('--grep')) {
+  console.log(search(records, valueOf('--search') ?? valueOf('--grep') ?? '', valueOf('--group')));
+} else if (argv.includes('--groups')) {
+  console.log(groupList(records));
+} else if (argv.includes('--dupes')) {
+  console.log(dupes(records));
+} else if (argv.includes('--weak')) {
+  console.log(weak(records));
+} else {
+  console.log(summary(records));
+  const outDir = valueOf('--write');
+  if (outDir) {
+    try {
+      mkdirSync(resolve(outDir), { recursive: true });
+      writeFileSync(join(resolve(outDir), 'skills.json'), JSON.stringify(records, null, 2), 'utf8');
+      console.log(`\nWrote ${join(resolve(outDir), 'skills.json')}`);
+    } catch (e) {
+      console.error(`Could not write index: ${e.message}`);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@cangurel81/skill-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Index, classify and search a large agent-skill catalogue. Answers \"which skill fits this job?\" and reports catalogue bloat caused by duplicated locale trees.",
+  "type": "module",
+  "bin": {
+    "skill-router": "bin/skill-router.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent",
+    "skills",
+    "skill-router",
+    "claude-code",
+    "opencode",
+    "codex",
+    "ai-agents",
+    "tooling",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Can Gürel (https://webadhere.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cangurel81/skill-router.git"
+  },
+  "homepage": "https://github.com/cangurel81/skill-router#readme",
+  "bugs": {
+    "url": "https://github.com/cangurel81/skill-router/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/skill-router.mjs",
+    "test": "node --check bin/skill-router.mjs && node test/smoke.mjs"
+  }
+}

package/skills/skill-router/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: skill-router
+description: Use when a task may already be covered by one of the hundreds of installed agent skills and you need the right one instead of guessing — "which skill for this", "do we already have a skill for X", "is there a skill that does Y", "my skill folder is a mess", "too many skills", or when two installed skills overlap and one must be picked. Scans every configured skill root, classifies skills by domain, separates genuine skills from translated locale copies, and returns ranked matches with file paths plus a measured bloat report. Do not use for authoring a new skill (use writing-skills) or for installing a repository of skills.
+version: 1.0.0
+---
+
+# Skill Router
+
+A large skill catalogue fails in two directions. The agent picks a skill that does not exist,
+or it writes from scratch something already installed forty times over. Both come from guessing
+instead of looking.
+
+**Rule: never claim "no skill covers this" and never name a skill without running the router.**
+
+## Run it
+
+From the repository that contains this skill:
+
+```bash
+node bin/skill-router.mjs                      # full catalogue inventory
+node bin/skill-router.mjs --search expo        # ranked matches with paths
+node bin/skill-router.mjs --search video --group video
+node bin/skill-router.mjs --groups             # domain keys and counts
+node bin/skill-router.mjs --dupes              # same name, different folders
+node bin/skill-router.mjs --weak               # descriptions too short to route on
+node bin/skill-router.mjs --json               # machine-readable
+```
+
+Point it somewhere explicit:
+
+```bash
+node bin/skill-router.mjs --root ~/.claude/skills --search testing
+node bin/skill-router.mjs --root ./vendor/skills --root ./skills
+SKILL_ROOTS=~/.claude/skills:./skills node bin/skill-router.mjs
+```
+
+`--root` (repeatable) beats `SKILL_ROOTS`, which beats the built-in defaults
+(`./.claude/skills`, `./.agents/skills`, `./skills`, `~/.claude/skills`, `~/.config/opencode/skills`,
+`~/.codex/skills`, `~/.kimi-code/skills`).
+
+Read the **path** in every result before trusting the name. Two skills can share a name and differ
+completely; the path is the only thing that says which repo you are actually loading.
+
+## Routing procedure
+
+1. **Name the domain first.** `--groups` gives the keys. Searching inside a domain beats searching
+   the whole catalogue, because generic words like "review", "audit" or "data" match hundreds.
+2. **Search two or three different words**, not one. A skill whose name says `tts` may only
+   mention "voiceover" in its description; the ranker searches both.
+3. **Read the description, then the path.** Description tells you if it fits. Path tells you which
+   repo and whether it is a locale copy.
+4. **Only then open the SKILL.md.** Opening every candidate is what the index exists to avoid.
+5. **If two match and overlap**, pick one, and check `--dupes` to see whether your catalogue carries
+   both permanently.
+
+## Domain keys
+
+| Key | Domain | Example search terms |
+|---|---|---|
+| `seo` | SEO / GEO / search | `geo`, `citability`, `backlink`, `schema`, `llms.txt` |
+| `video` | Video / motion / audio | `remotion`, `ffmpeg`, `caption`, `tts`, `shorts` |
+| `frontend` | Frontend / UI / design system | `react`, `vue`, `tailwind`, `gsap`, `a11y` |
+| `backend` | Backend / API / databases | `laravel`, `fastapi`, `postgres`, `graphql` |
+| `mobile` | Mobile / native app work | `expo`, `flutter`, `swift`, `app store` |
+| `marketing` | Marketing / content / social | `linkedin`, `carousel`, `hook`, `campaign` |
+| `agent` | Agent / LLM / orchestration | `harness`, `subagent`, `eval`, `memory` |
+| `security` | Security / compliance | `audit`, `hardening`, `threat model` |
+| `infra` | Infra / DevOps / network | `docker`, `ci/cd`, `dns`, `vpn` |
+| `data` | Data / research / analytics | `scrape`, `sql`, `dashboard`, `benchmark` |
+| `code` | Code quality / testing | `tdd`, `review`, `refactor`, `lint` |
+| `desktop` | Desktop / documents | `pdf`, `pandoc`, `screenshot` |
+| `wordpress` | WordPress / WooCommerce | `plugin`, `woocommerce`, `wp-cli` |
+| `other` | Unclassified | fix the description |
+
+`other` being large is a finding, not a category. Skills land there because their description is
+too vague to classify, which also means no agent can route to them.
+
+## Reading the inventory
+
+The summary reports five numbers. Each one has an action attached:
+
+| Number | Means | Action |
+|---|---|---|
+| `locale doc copies` above ~10% | repos are registered at their root, so `docs/<locale>/skills` are scanned as skills | register the real `skills/` folder instead |
+| `duplicate names` high | two repos ship the same skill; the agent may load either | pick one and drop the other root, or accept the newer repo |
+| `weak descriptions` | description under 25 chars, unusable for routing | extend the description or treat the skill as absent |
+| `genuine` far below `total` | most of the catalogue is copies | fix roots before adding anything |
+| one domain with 0 | real capability gap | this is where a new skill is justified |
+
+The tool never deletes anything and never edits a skill. It measures and reports.
+
+## When a new skill is actually justified
+
+All three must hold:
+
+1. `--search` over three plausible terms returns nothing relevant.
+2. The gap is knowledge no public repository could ship — local toolchain, local traps, local
+   decisions, private systems.
+3. The knowledge repeats. It has already cost time twice.
+
+Otherwise extend an existing skill or fix its description. A fourth near-duplicate skill makes the
+catalogue worse, not more capable.
+
+## What this does not do
+
+- It does not install, fetch or update skills.
+- It does not validate that a `SKILL.md` is correct — only that it is discoverable.
+- It does not judge quality. A short description is a routing failure, not necessarily a bad skill.
+- It does not read the skill body. Content review is a separate pass.