skills-viewer 0.6.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # skills-viewer
 
-Browse, search and manage your [Claude Code](https://code.claude.com) skills, commands, agents and hooks in the browser.
+Browse, search and manage your [Claude Code](https://code.claude.com) skills, commands, agents, hooks and auto memory 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.
 
@@ -19,11 +19,12 @@ npx skills-viewer
 - **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
 - **Purpose grouping (AI)** — one haiku call classifies everything installed by _when you use it_ into 4–8 groups generated for your environment (planning / building / review / release / … as a role-agnostic guide — a designer's or PM's skills get their own groups). Switch the list between by-source, by-purpose and flat views; a frontmatter `category:` pins an item to a manual group that takes precedence
 - **Search / sort** — incremental search over name + description + usage; sort by name, usage count, last used, updated date, or token cost
-- **Diagnostics** — an _unused_ badge (no recorded use within the transcript retention window) with an all / used / unused filter, plus static description lint: missing / too-short / too-long descriptions, missing trigger conditions ("use when …") that make auto-invocation unlikely, and name-echo descriptions
+- **Diagnostics** — a _no recent use_ badge (no recorded use within the transcript retention window) with an all / recent use / no recent use filter, plus static description lint: missing / too-short / too-long descriptions, missing trigger conditions ("use when …") that make auto-invocation unlikely, and name-echo descriptions
 - **Token cost** — since every name + description is injected into each session, the estimated token overhead is shown per item, per scope, and as a per-session total for the current project
 - **AI trigger diagnosis** — one click asks the model whether the description is likely to trigger auto-invocation, lists concrete issues, and proposes an improved description you can apply with one click (cached by content hash)
 - **AI flow diagram** — extract the processing flow of orchestration-style skills (steps, branches, delegations, human gates) from the definition body and render it as a step diagram; delegated skills are clickable
 - **AI model choice** — pick the model behind all AI features (haiku default / sonnet / opus) in settings; aliases are resolved by your claude CLI
+- **Memory triage** — a _Memory_ view lists Claude Code's auto memory (`~/.claude/projects/<project>/memory/`) per project with its context cost split into the always-on part (the `MEMORY.md` index line injected into every session) and the pay-per-use part (the body, read on demand), plus Read / Write counts from transcripts, `[[link]]` resolution and backlinks. **AI triage** reads every memory of a project with the claude CLI (one call, split into a few for very large projects) and proposes a destination per memory — keep / shrink / move to CLAUDE.md / move to docs / move to a skill / delete / wrong project — with the reasoning and a paste-ready instruction for Claude Code (it is asked to always cover removing the `MEMORY.md` index line and re-pointing `[[link]]`s). Each memory is first judged for freshness (current / outdated / historical / obsolete) from mechanical signals — dates in the body, missing paths, merged or deleted branches, references to another project — and a _rewrite the body_ verdict covers memories whose gist still holds; the triage also flags when the `MEMORY.md` index line disagrees with the body. For feedback memories the instruction is built from a fixed template, so it reads the same on every model. The viewer never writes to memory: you paste the instruction into Claude Code, which inspects, asks when unsure, and executes after your approval
 - **Edit in the browser** — inline editor for SKILL.md / commands / agents (project & user scopes) with mtime conflict detection and a one-generation backup in `~/.cache/skills-viewer/backups/`
 - **What's changed** — a banner shows items added / updated / removed since your last launch (baseline advances only when you dismiss it); the CLI prints a one-line summary at startup too
 - **Usage sparkline** — the detail pane charts the last 30 days of per-day usage
@@ -35,7 +36,7 @@ npx skills-viewer
 - **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
+- **URL routing** — `/skills/:id?tab=md`, `/memory/:id`, `/memory/triage/:project`, search/sort/grouping in query params; links are shareable across reloads
 
 ## Usage
 
@@ -77,11 +78,12 @@ 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) — the _unused_ badge has the same limitation
+- Usage stats only cover the transcript retention window of Claude Code (`cleanupPeriodDays`, default 30 days) — the _no recent use_ badge and memory Read counts have the same limitation (projects without transcripts show no usage columns at all)
 - Token costs are heuristic estimates (≈4 chars/token for ASCII, ≈1.5 for CJK), not exact tokenizer counts
 - 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
+- Memory triage sends each memory's body to the claude CLI, together with the project's `MEMORY.md` index, the **headings** of `CLAUDE.md` / `.claude/CLAUDE.md` / `~/.claude/CLAUDE.md` and the names + descriptions of the skills available to that project (never their bodies) so it can spot duplicates and promotion targets. Branch status for the freshness signals comes from local `git` (no network). Results are cached per memory by content hash (plus the index line); memory files themselves are never modified
 
 ## License
 

package/build/server/cache.js

@@ -0,0 +1,53 @@
+"use strict";
+/*
+ * AI 機能のキャッシュ(~/.cache/skills-viewer/*.json)の共通処理。
+ * どのキャッシュも「実パス → エントリ」の形なので、掃除の規則を 1 箇所に置く。
+ */
+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.pruneMissing = pruneMissing;
+const fs = __importStar(require("node:fs"));
+/*
+ * 消えたファイル(削除・リネーム・別プロジェクトの撤去)のエントリを落とす。
+ * 呼ぶのは保存時だけにする — GET(読み取り API)で書き込みを発生させないため。
+ */
+function pruneMissing(store) {
+    const out = {};
+    for (const [key, value] of Object.entries(store)) {
+        if (fs.existsSync(key))
+            out[key] = value;
+    }
+    return out;
+}

package/build/server/diagnose.js

@@ -45,6 +45,7 @@ exports.attachDiagnoses = attachDiagnoses;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const cache_1 = require("./cache");
 const summary_1 = require("./summary");
 const DIAG_FILE = path.join(os.homedir(), '.cache', 'skills-viewer', 'diagnoses.json');
 function loadDiagnoses() {
@@ -57,7 +58,8 @@ function loadDiagnoses() {
 }
 function saveDiagnoses(store) {
     fs.mkdirSync(path.dirname(DIAG_FILE), { recursive: true });
-    fs.writeFileSync(DIAG_FILE, JSON.stringify(store, null, 1));
+    // 保存のついでに死にエントリを掃除する(GET では書き込まないので掃除もしない)
+    fs.writeFileSync(DIAG_FILE, JSON.stringify((0, cache_1.pruneMissing)(store), null, 1));
 }
 function buildPrompt(name, content, lang) {
     if (lang === 'ja') {

package/build/server/flow.js

@@ -45,8 +45,15 @@ exports.attachFlows = attachFlows;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const cache_1 = require("./cache");
 const summary_1 = require("./summary");
 const FLOW_FILE = path.join(os.homedir(), '.cache', 'skills-viewer', 'flows.json');
+/*
+ * 抽出スキーマの世代。branches.to(ループ/スキップ)追加で 2。
+ * 旧世代キャッシュも表示には使い続ける(フローチャート描画は to 無しでも成立し、
+ * ループ矢印だけ出ない)が、再抽出時は stale 扱いして新スキーマで作り直す。
+ */
+const FLOW_SCHEMA_V = 2;
 function loadFlows() {
     try {
         return JSON.parse(fs.readFileSync(FLOW_FILE, 'utf8'));
@@ -57,7 +64,8 @@ function loadFlows() {
 }
 function saveFlows(store) {
     fs.mkdirSync(path.dirname(FLOW_FILE), { recursive: true });
-    fs.writeFileSync(FLOW_FILE, JSON.stringify(store, null, 1));
+    // 保存のついでに死にエントリを掃除する(GET では書き込まないので掃除もしない)
+    fs.writeFileSync(FLOW_FILE, JSON.stringify((0, cache_1.pruneMissing)(store), null, 1));
 }
 function buildPrompt(name, content, lang) {
     if (lang === 'ja') {
@@ -65,12 +73,13 @@ function buildPrompt(name, content, lang) {
             '{"steps": [{"title": "ステップ名(10字程度)", "detail": "何をするか(25字程度)",\n' +
             ' "calls": ["このステップで起動/委譲する他の skill・コマンド名"],\n' +
             ' "gate": "human" | "auto" | null,\n' +
-            ' "branches": [{"when": "分岐条件(15字程度)", "then": "その場合の挙動(20字程度)"}]}]}\n\n' +
+            ' "branches": [{"when": "分岐条件(15字程度)", "then": "その場合の挙動(20字程度)", "to": 行き先ステップ番号}]}]}\n\n' +
             '制約:\n' +
             '- steps は実行順に 4〜8 個(単純な skill なら少なくてよい)\n' +
             '- gate は人間の確認/承認を待つステップだけ "human"(自動で進むなら "auto"、該当なしは null)\n' +
             '- calls は本文に実際に登場する名前のみ(幻覚禁止)\n' +
-            '- branches は中断・フォールバック等の分岐だけ(無ければ省略)\n\n' +
+            '- branches は中断・フォールバック等の分岐だけ(無ければ省略)。when は「テスト失敗」のような判定できる条件文にする\n' +
+            '- to は分岐が別ステップへ移るときだけ 1 始まりの番号で(リトライ/ループで前へ戻る場合が典型)。単なる中断・終了なら省略\n\n' +
             '# skill: ' +
             name +
             '\n\n' +
@@ -80,12 +89,13 @@ function buildPrompt(name, content, lang) {
         '{"steps": [{"title": "step name (2-4 words)", "detail": "what it does (about 10 words)",\n' +
         ' "calls": ["other skill/command names this step invokes or delegates to"],\n' +
         ' "gate": "human" | "auto" | null,\n' +
-        ' "branches": [{"when": "branch condition (about 5 words)", "then": "behavior in that case (about 7 words)"}]}]}\n\n' +
+        ' "branches": [{"when": "branch condition (about 5 words)", "then": "behavior in that case (about 7 words)", "to": target step number}]}]}\n\n' +
         'Constraints:\n' +
         '- 4 to 8 steps in execution order (fewer is fine for simple skills)\n' +
         '- gate is "human" ONLY for steps that wait for human confirmation/approval ("auto" if it proceeds automatically, null otherwise)\n' +
         '- calls may contain only names that actually appear in the body (no hallucination)\n' +
-        '- branches only for aborts / fallbacks / real forks (omit when none)\n\n' +
+        '- branches only for aborts / fallbacks / real forks (omit when none); "when" must be a checkable condition like "tests fail"\n' +
+        '- to is the 1-based step number ONLY when the branch jumps to another step (typically looping back for a retry); omit for plain aborts/exits\n\n' +
         '# skill: ' +
         name +
         '\n\n' +
@@ -116,6 +126,7 @@ function parseFlow(text) {
                 .map((b) => ({
                 when: String(b.when).slice(0, 60),
                 then: String(b.then || '').slice(0, 80),
+                ...(Number.isInteger(b.to) && b.to >= 1 ? { to: b.to } : {}),
             }))
                 .slice(0, 4),
         });
@@ -124,18 +135,30 @@ function parseFlow(text) {
     }
     if (!steps.length)
         throw new Error('no steps in output');
+    // to の上限検証は全 step が出揃ってから(範囲外は to だけ捨てて分岐テキストは残す)
+    for (const st of steps)
+        for (const b of st.branches)
+            if (b.to !== undefined && b.to > steps.length)
+                delete b.to;
     return { steps };
 }
 async function flowOne(realPath, name, lang, model = 'haiku') {
     const hash = (0, summary_1.contentHash)(realPath);
     const store = loadFlows();
     const cached = store[realPath];
-    if (cached && cached.hash === hash && cached.lang === lang) {
+    if (cached && cached.hash === hash && cached.lang === lang && cached.v === FLOW_SCHEMA_V) {
         return { steps: cached.steps };
     }
     const content = fs.readFileSync(realPath, 'utf8').slice(0, 12000);
     const result = parseFlow(await (0, summary_1.runClaude)(buildPrompt(name, content, lang), model));
-    store[realPath] = { ...result, hash, lang, model, generatedAt: new Date().toISOString() };
+    store[realPath] = {
+        ...result,
+        hash,
+        lang,
+        model,
+        v: FLOW_SCHEMA_V,
+        generatedAt: new Date().toISOString(),
+    };
     saveFlows(store);
     return result;
 }

package/build/server/index.js

@@ -46,12 +46,14 @@ 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 memory_1 = require("./memory");
 const summary_1 = require("./summary");
 const manage_1 = require("./manage");
 const edit_1 = require("./edit");
 const diagnose_1 = require("./diagnose");
 const flow_1 = require("./flow");
 const groups_1 = require("./groups");
+const memory_triage_1 = require("./memory-triage");
 const snapshot_1 = require("./snapshot");
 const errors_1 = require("./errors");
 const locale_1 = require("./locale");
@@ -134,6 +136,41 @@ function attributeUsage(sections) {
     }
     return Object.keys(byDir).length > 0;
 }
+/*
+ * memory の Read(参照)/ Write・Edit(作成・更新)実績を付与する。
+ * skill と違って帰属先の解決は不要で、Read の file_path がそのまま実ファイルを指す。
+ * usageAvailable は「そのプロジェクトのトランスクリプトがあるか」= エンコード名で始まる
+ * ディレクトリ(worktree 分を含む)に jsonl が 1 件以上あるか。false なら Read 列は出さない。
+ */
+function attributeMemoryUsage(memory) {
+    if (!memory.length)
+        return;
+    const { byPath, dirsWithTranscripts } = (0, usage_1.scanMemoryUsage)();
+    for (const sec of memory) {
+        sec.usageAvailable = (0, usage_1.hasTranscripts)(dirsWithTranscripts, sec.id);
+        for (const it of sec.items) {
+            const u = byPath[it.path];
+            if (!u)
+                continue;
+            if (u.reads > 0) {
+                it.useCount = u.reads;
+                it.lastUsed = u.lastRead;
+                it.dailyUse = u.daily;
+            }
+            if (u.writes > 0)
+                it.writeCount = u.writes;
+        }
+    }
+}
+/*
+ * 実績付きの memory セクション一覧。/api/skills だけでなく /api/memory-triage からも
+ * 同じ事実(Read / W-E / usageAvailable)をプロンプトに載せる必要があるので共通化する。
+ */
+function memorySections(cwd) {
+    const memory = (0, memory_1.scanMemory)(cwd);
+    attributeMemoryUsage(memory);
+    return memory;
+}
 function collect(cwd, lang) {
     const sections = (0, scan_1.scanSections)(cwd, lang);
     const usageAvailable = attributeUsage(sections);
@@ -162,6 +199,9 @@ function collect(cwd, lang) {
     (0, flow_1.attachFlows)(sections, lang);
     const grp = (0, groups_1.attachGroups)(sections, lang);
     const aiStale = (0, summary_1.staleItems)(sections, lang).length;
+    // memory は「呼び出す」ものではないので sections には混ぜず、別配列で同乗させる
+    const memory = memorySections(cwd);
+    (0, memory_triage_1.attachMemoryTriage)(memory, lang);
     const targets = [
         { label: 'user skills', sub: '~/.claude/skills/', path: scan_1.HOME },
         ...(0, scan_1.listProjects)(cwd)
@@ -178,6 +218,7 @@ function collect(cwd, lang) {
         changes: (0, snapshot_1.computeChanges)(sections),
         ...(grp.groups ? { groups: grp.groups } : {}),
         ...(grp.stale ? { groupsStale: true } : {}),
+        ...(memory.length ? { memory } : {}),
     };
 }
 /* DNS rebinding 対策: same-origin GET には Origin が付かないため Host 側も検証する */
@@ -291,6 +332,26 @@ function handleApi(req, res, cwd) {
                     .catch((e) => send(400, (0, errors_1.toErrorBody)(e)));
                 return;
             }
+            if (url.pathname === '/api/memory-triage') {
+                // 1 プロジェクト分をまとめて 1 回の claude 呼び出しで棚卸しする(結果は再取得で反映)
+                const project = String(data.project || '');
+                const sec = memorySections(cwd).find((s) => s.id === project);
+                if (!sec)
+                    throw new errors_1.ApiError('not-found', project);
+                const files = Array.isArray(data.files)
+                    ? data.files.filter((f) => typeof f === 'string')
+                    : undefined;
+                // sections は「CLAUDE.md / skill に既に書いてある」「skill へ昇格」を判定させる文脈。
+                // AI を呼ぶときだけ要るので、フルスキャンは関数で渡して遅延させる
+                (0, memory_triage_1.triageProject)(sec, lang, model, {
+                    force: !!data.force,
+                    files,
+                    sections: () => (0, scan_1.scanSections)(cwd, lang),
+                })
+                    .then((results) => send(200, { ok: true, results }))
+                    .catch((e) => send(400, (0, errors_1.toErrorBody)(e)));
+                return;
+            }
             if (url.pathname === '/api/summarize') {
                 const real = (0, manage_1.assertReadableMd)(data.src);
                 // refs(関係候補)はスキャン結果から復元する
@@ -332,7 +393,7 @@ function serveStatic(req, res) {
 }
 /*
  * 起動時の1〜2行サマリー(--no-open 運用でも価値が出るように)。
- * 前回からの差分 + セッション注入トークン概算 + 未使用件数。失敗しても起動は止めない。
+ * 前回からの差分 + セッション注入トークン概算 + 直近未使用の件数。失敗しても起動は止めない。
  */
 function printStartupSummary(cwd) {
     try {
@@ -350,8 +411,8 @@ function printStartupSummary(cwd) {
                 .length
             : null;
         console.log((0, locale_1.srvMsg)(`スキル定義のセッション注入 ≈${sessionTokens.toLocaleString()}tok` +
-            (unused !== null ? ` / 未使用 ${unused} 件` : ''), `Skill definitions inject ≈${sessionTokens.toLocaleString()} tok/session` +
-            (unused !== null ? ` / ${unused} unused` : '')));
+            (unused !== null ? ` / 直近未使用 ${unused} 件` : ''), `Skill definitions inject ≈${sessionTokens.toLocaleString()} tok/session` +
+            (unused !== null ? ` / ${unused} with no recent use` : '')));
     }
     catch {
         /* サマリーは補助情報。失敗しても起動を妨げない */