skills-viewer 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 watanabeyu
+
+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,82 @@
+# skills-viewer
+
+Browse, search and manage your [Claude Code](https://code.claude.com) skills, commands, agents and hooks in the browser.
+
+Scans every project registered in `~/.claude.json` (plus user scope, plugins and built-ins), and serves a local web UI to explore them — with usage stats, AI-generated summaries, full SKILL.md rendering, same-name diffs, and copy/delete management.
+
+```bash
+npx skills-viewer
+```
+
+> Zero runtime dependencies. The published package ships a prebuilt UI; `npx` installs in seconds.
+
+<!-- 相対パス参照: private リポジトリでも GitHub 上で表示でき、npmjs.com は repository フィールドを元に raw URL へ書き換えるため public 化後は npm でも表示される -->
+
+![Skills Viewer — grid view with per-scope grouping, usage stats and AI summaries](docs/screenshot.png)
+
+## Features
+
+- **All scopes in one view** — user (`~/.claude/skills`), every project's `.claude/skills` / `.claude/commands`, installed plugins, and Claude Code built-ins, grouped by source
+- **Search / sort** — incremental search over name + description + usage; sort by name, usage count, last used, or updated date
+- **Usage stats** — invocation counts and last-used dates aggregated from Claude Code session transcripts (`~/.claude/projects/`), covering both user-typed `/skill` calls and model-invoked Skill tool calls
+- **AI summaries** — one-click summarization of each SKILL.md via `claude -p --model haiku`, cached by content hash in `~/.cache/skills-viewer/` so unchanged skills are never re-summarized
+- **Detail pane** — master/detail layout with an Overview tab (description, usage, bundled files) and a rendered SKILL.md tab
+- **Agents & hooks too** — `.claude/agents/*.md` and `hooks` entries from `settings.json` / `settings.local.json` are listed alongside skills with kind badges (hooks are read-only)
+- **Manage** — copy a skill/command/agent to another project or to user scope (`-copy` suffix on name conflicts), or delete it — deletions go to the OS trash, not `rm`. Plugin and built-in entries are read-only
+- **Same-name diff** — when the same skill name exists in multiple scopes, the detail page lists the other definitions and shows a line diff between them
+- **Open in editor** — via URL scheme (VS Code / Cursor / Zed / Windsurf / custom, configurable in the ⚙ settings modal), or the OS default opener
+- **English / 日本語** — UI language auto-detected from the browser and switchable in settings; AI summaries are generated in the selected language (CLI messages follow `LANG`)
+- **URL routing** — `/skills/:id?tab=md`, search/sort/grouping in query params; links are shareable across reloads
+
+## Usage
+
+```bash
+npx skills-viewer              # scan + open browser (default port 4763)
+npx skills-viewer --port 5000  # custom port
+npx skills-viewer --no-open    # don't open the browser
+```
+
+Run it from a project directory to have that project marked as “current” and listed first. Reloading the page rescans the filesystem.
+
+## Security
+
+- Binds to `127.0.0.1` only
+- Mutating APIs require a per-run token that other origins cannot read (same-origin policy), and requests with a non-localhost `Origin` are rejected
+- Copy/delete are restricted to `.claude/skills/` / `.claude/commands/` / `.claude/agents/` paths; plugin directories are never written to; deletions go to the OS trash
+
+## Development
+
+```bash
+pnpm install
+pnpm dev        # tsx watch API server (4763) + Vite dev server (5173, /api proxied)
+pnpm build      # web UI → dist/, server TS → build/
+pnpm typecheck  # web + server
+pnpm start      # serve dist/ + API (what npx users get)
+```
+
+Layout:
+
+```
+src/
+├─ cli.ts         # bin entry
+├─ server/        # zero-dep Node API (scan / usage / summary / manage) — TypeScript
+└─ shared/        # types shared between server and web (single source)
+web/              # React + TypeScript + Vite (devDependencies only — bundled into dist/)
+build/            # compiled server JS shipped in the npm package (generated by prepack)
+dist/             # prebuilt UI shipped in the npm package (generated by prepack)
+```
+
+## Notes
+
+- Usage stats only cover the transcript retention window of Claude Code (`cleanupPeriodDays`, default 30 days)
+- Usage is attributed per calling project (worktrees roll up to their parent project by encoded-path prefix). When scopes share a name, the resolution order project > user > plugin > built-in is assumed
+- The built-in skill list is hardcoded in `server/scan.js` (they live inside the Claude Code binary); check `/skills` inside Claude Code for the authoritative list
+- AI summaries require a logged-in `claude` CLI
+
+## License
+
+MIT
+
+---
+
+This is an unofficial community tool, not affiliated with Anthropic.

package/build/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+const locale_1 = require("./server/locale");
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log((0, locale_1.srvMsg)(`skills-viewer — Claude Code の skills / commands / agents / hooks をブラウザで一望
+
+Usage: skills-viewer [options]
+
+Options:
+  --port <n>   ポート指定 (既定 4763、使用中なら +1)
+  --no-open    ブラウザを自動で開かない
+  -h, --help   このヘルプ`, `skills-viewer — browse your Claude Code skills / commands / agents / hooks
+
+Usage: skills-viewer [options]
+
+Options:
+  --port <n>   port to listen on (default 4763; +1 if in use)
+  --no-open    do not open the browser automatically
+  -h, --help   show this help`));
+    process.exit(0);
+}
+const portIdx = args.indexOf('--port');
+const port = portIdx >= 0 ? Number(args[portIdx + 1]) : 4763;
+if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error((0, locale_1.srvMsg)('--port には 0〜65535 の整数を指定してください', '--port must be an integer between 0 and 65535'));
+    process.exit(1);
+}
+(0, server_1.start)({
+    port,
+    open: !args.includes('--no-open'),
+    cwd: process.cwd(),
+});

package/build/server/errors.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * API エラーは言語非依存のコードで表現し、表示文言はクライアント側の辞書で解決する。
+ * message は code(+detail)そのままなので、curl 等の直接利用でも意味が取れる。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.toErrorBody = toErrorBody;
+class ApiError extends Error {
+    code;
+    detail;
+    constructor(code, detail = '') {
+        super(detail ? code + ': ' + detail : code);
+        this.code = code;
+        this.detail = detail;
+    }
+}
+exports.ApiError = ApiError;
+/* handleApi の catch で使う共通整形 */
+function toErrorBody(e) {
+    if (e instanceof ApiError)
+        return { error: e.code, detail: e.detail };
+    return { error: 'internal', detail: e instanceof Error ? e.message : String(e) };
+}

package/build/server/index.js

@@ -0,0 +1,298 @@
+"use strict";
+/*
+ * HTTP サーバー: /api/* の JSON API + dist/ (SPA) の静的配信。
+ * セキュリティ: 127.0.0.1 バインド + 起動ごとのトークン(/api/token で同一オリジンにのみ配布。
+ * mutation 系はトークン必須。SOP により他オリジンのページはトークンを読めない)。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.start = start;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const http = __importStar(require("node:http"));
+const crypto = __importStar(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+const scan_1 = require("./scan");
+const usage_1 = require("./usage");
+const summary_1 = require("./summary");
+const manage_1 = require("./manage");
+const errors_1 = require("./errors");
+const locale_1 = require("./locale");
+const TOKEN = crypto.randomBytes(16).toString('hex');
+const DIST = path.join(__dirname, '..', '..', 'dist');
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.map': 'application/json',
+    '.woff2': 'font/woff2',
+};
+/*
+ * 使用実績を「正しい定義」に帰属させる。
+ * 呼び出し元プロジェクト(トランスクリプトのディレクトリ)を特定し、そのプロジェクトの
+ * skill → user → plugin → built-in の解決優先順で1つの定義にだけ加算する。
+ * 呼び出し元が未知(worktree・削除済みプロジェクト等)の場合は user 以降にフォールバック。
+ */
+function attributeUsage(sections) {
+    const byDir = (0, usage_1.scanUsageByDir)();
+    const lookupBySec = new Map();
+    for (const s of sections) {
+        const m = new Map();
+        for (const it of s.items) {
+            m.set(it.name, it);
+            const short = it.name.split(':').pop();
+            if (short && !m.has(short))
+                m.set(short, it);
+        }
+        lookupBySec.set(s.id, m);
+    }
+    const dirToProjSec = new Map();
+    for (const s of sections) {
+        if (s.source === 'project')
+            dirToProjSec.set((0, usage_1.encodeProjectPath)(s.note), s);
+    }
+    const globalOrder = ['user', 'plugin', 'builtin']
+        .map((id) => sections.find((s) => s.id === id))
+        .filter((s) => Boolean(s));
+    // worktree(例: monorepo-feat-847-…)は親プロジェクトのエンコード名 + '-' で始まるので、
+    // 完全一致しない場合は最長プレフィックス一致で親プロジェクトに帰属させる
+    const resolveProjSec = (dirName) => {
+        if (dirToProjSec.has(dirName))
+            return dirToProjSec.get(dirName);
+        let best = null, bestLen = 0;
+        for (const [enc, sec] of dirToProjSec) {
+            if (dirName.startsWith(enc + '-') && enc.length > bestLen) {
+                best = sec;
+                bestLen = enc.length;
+            }
+        }
+        return best;
+    };
+    for (const [dirName, names] of Object.entries(byDir)) {
+        const projSec = resolveProjSec(dirName);
+        const order = projSec ? [projSec, ...globalOrder] : globalOrder;
+        for (const [name, u] of Object.entries(names)) {
+            let target;
+            for (const sec of order) {
+                target = lookupBySec.get(sec.id)?.get(name);
+                if (target)
+                    break;
+            }
+            if (!target)
+                continue; // 既知の skill に該当しない(builtin CLI コマンド等)
+            target.typedCount = (target.typedCount || 0) + u.typed;
+            target.autoCount = (target.autoCount || 0) + u.auto;
+            target.useCount = (target.useCount || 0) + u.typed + u.auto;
+            target.lastUsed = Math.max(target.lastUsed || 0, u.last);
+        }
+    }
+}
+function collect(cwd, lang) {
+    const sections = (0, scan_1.scanSections)(cwd, lang);
+    attributeUsage(sections);
+    const summaries = (0, summary_1.loadSummaries)();
+    for (const sec of sections) {
+        for (const it of sec.items) {
+            const cached = summaries[it.path];
+            if (cached &&
+                cached.lang === lang && // 表示言語と違う要約は出さない(aiStale 側にカウントされる)
+                it.path &&
+                fs.existsSync(it.path) &&
+                cached.hash === (0, summary_1.contentHash)(it.path)) {
+                it.aiSummary = cached.summary;
+                if (cached.invocation) {
+                    it.aiInvocation = cached.invocation;
+                    it.aiInvocationReason = cached.invocationReason || '';
+                }
+                // 生成後に照合ルールが厳格化されても、現在の refs に無い関係は表示しない
+                const valid = (cached.relations || []).filter((r) => (it.refs || []).includes(r.name));
+                if (valid.length)
+                    it.aiRelations = valid;
+            }
+        }
+    }
+    const aiStale = (0, summary_1.staleItems)(sections, lang).length;
+    const targets = [
+        { label: 'user skills', sub: '~/.claude/skills/', path: scan_1.HOME },
+        ...(0, scan_1.listProjects)(cwd)
+            .sort((a, b) => path.basename(a).localeCompare(path.basename(b)))
+            .map((p) => ({ label: path.basename(p), sub: p, path: p })),
+    ];
+    return { generatedAt: new Date().toISOString(), cwd, sections, targets, aiStale };
+}
+/* DNS rebinding 対策: same-origin GET には Origin が付かないため Host 側も検証する */
+function hostOk(req) {
+    const host = (req.headers.host || '').replace(/:\d+$/, '');
+    return host === '127.0.0.1' || host === 'localhost';
+}
+/* 同一オリジン以外からの API アクセスを拒否(Origin が付く場合のみ検証) */
+function originOk(req) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true; // same-origin fetch / curl は Origin なし
+    try {
+        const h = new URL(origin).hostname;
+        return h === '127.0.0.1' || h === 'localhost';
+    }
+    catch {
+        return false;
+    }
+}
+/* クライアント指定の表示言語(不明値は 'en' に落とす) */
+function langOf(v) {
+    return v === 'ja' ? 'ja' : 'en';
+}
+function handleApi(req, res, cwd) {
+    const send = (code, obj) => {
+        res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify(obj));
+    };
+    if (!hostOk(req) || !originOk(req))
+        return send(403, { error: 'bad-origin', detail: '' });
+    const url = new URL(req.url || '/', 'http://localhost');
+    if (req.method === 'GET') {
+        try {
+            if (url.pathname === '/api/token')
+                return send(200, { token: TOKEN });
+            if (url.pathname === '/api/skills')
+                return send(200, collect(cwd, langOf(url.searchParams.get('lang'))));
+            if (url.pathname === '/api/summary-status')
+                return send(200, (0, summary_1.summaryStatus)());
+            if (url.pathname === '/api/file') {
+                const real = (0, manage_1.assertReadableMd)(url.searchParams.get('src') || '');
+                return send(200, { content: fs.readFileSync(real, 'utf8') });
+            }
+            throw new errors_1.ApiError('unknown-endpoint', url.pathname);
+        }
+        catch (e) {
+            return send(e instanceof errors_1.ApiError && e.code === 'unknown-endpoint' ? 404 : 400, (0, errors_1.toErrorBody)(e));
+        }
+    }
+    // mutation 系はトークン必須
+    if (req.headers['x-csb-token'] !== TOKEN)
+        return send(403, { error: 'bad-token', detail: '' });
+    let body = '';
+    req.on('data', (c) => {
+        body += c;
+        if (body.length > 1e6)
+            req.destroy();
+    });
+    req.on('end', () => {
+        let data;
+        try {
+            data = JSON.parse(body || '{}');
+        }
+        catch {
+            return send(400, { error: 'bad-json', detail: '' });
+        }
+        const lang = langOf(data.lang);
+        try {
+            if (url.pathname === '/api/copy')
+                return send(200, (0, manage_1.doCopy)(data, cwd));
+            if (url.pathname === '/api/delete')
+                return send(200, (0, manage_1.doDelete)(data));
+            if (url.pathname === '/api/open')
+                return send(200, (0, manage_1.openInEditor)(data));
+            if (url.pathname === '/api/summarize-all')
+                return send(200, (0, summary_1.startSummarizeAll)((0, scan_1.scanSections)(cwd, lang), !!data.force, lang));
+            if (url.pathname === '/api/summarize') {
+                const real = (0, manage_1.assertReadableMd)(data.src);
+                // refs(関係候補)はスキャン結果から復元する
+                const sections = (0, scan_1.scanSections)(cwd, lang);
+                const item = sections.flatMap((s) => s.items).find((x) => x.path === real);
+                const name = data.name || item?.name || path.basename(path.dirname(real));
+                (0, summary_1.summarizeOne)({ path: real, name, refs: item?.refs || [] }, lang)
+                    .then((analysis) => {
+                    (0, summary_1.saveSummary)(real, name, analysis, lang);
+                    send(200, { ok: true, ...analysis });
+                })
+                    .catch((e) => send(400, (0, errors_1.toErrorBody)(e)));
+                return;
+            }
+            throw new errors_1.ApiError('unknown-endpoint', url.pathname);
+        }
+        catch (e) {
+            return send(e instanceof errors_1.ApiError && e.code === 'unknown-endpoint' ? 404 : 400, (0, errors_1.toErrorBody)(e));
+        }
+    });
+}
+function serveStatic(req, res) {
+    const url = new URL(req.url || '/', 'http://localhost');
+    let fp = path.join(DIST, path.normalize(url.pathname));
+    if (!fp.startsWith(DIST)) {
+        res.writeHead(403);
+        return void res.end();
+    }
+    if (!fs.existsSync(fp) || fs.statSync(fp).isDirectory()) {
+        fp = path.join(DIST, 'index.html'); // SPA fallback (/skills/xxx など)
+    }
+    if (!fs.existsSync(fp)) {
+        res.writeHead(503, { 'Content-Type': 'text/plain; charset=utf-8' });
+        // 開発者向けメッセージなので英語固定
+        return void res.end('dist/ not found. Run `pnpm build` first.');
+    }
+    res.writeHead(200, { 'Content-Type': MIME[path.extname(fp)] || 'application/octet-stream' });
+    res.end(fs.readFileSync(fp));
+}
+function start({ port = 4763, open = true, cwd = process.cwd() } = {}, attempt = 0) {
+    const server = http.createServer((req, res) => {
+        if ((req.url || '').startsWith('/api/'))
+            return handleApi(req, res, cwd);
+        serveStatic(req, res);
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE' && attempt < 10) {
+            start({ port: port + 1, open, cwd }, attempt + 1);
+        }
+        else {
+            console.error(err.message);
+            process.exit(1);
+        }
+    });
+    server.listen(port, '127.0.0.1', () => {
+        const url = `http://127.0.0.1:${port}`;
+        console.log(`skills-viewer: ${url}  (cwd: ${cwd})`);
+        console.log((0, locale_1.srvMsg)('Ctrl+C で終了。ページ再読み込みで再スキャンされます。', 'Press Ctrl+C to quit. Reloading the page rescans.'));
+        if (open && process.platform === 'darwin')
+            (0, node_child_process_1.execFile)('open', [url], () => { });
+        if (open && process.platform === 'win32')
+            (0, node_child_process_1.execFile)('cmd', ['/c', 'start', url], () => { });
+        if (open && process.platform === 'linux')
+            (0, node_child_process_1.execFile)('xdg-open', [url], () => { });
+    });
+}

package/build/server/locale.js

@@ -0,0 +1,14 @@
+"use strict";
+/*
+ * CLI・サーバーコンソール出力の言語判定(環境変数ベース)。
+ * web UI の言語はクライアント側(navigator.language + 設定)で独立に管理される。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.srvMsg = exports.serverLang = void 0;
+function detect() {
+    const env = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+    return /^ja([-_]|$)/i.test(env) ? 'ja' : 'en';
+}
+exports.serverLang = detect();
+const srvMsg = (ja, en) => (exports.serverLang === 'ja' ? ja : en);
+exports.srvMsg = srvMsg;