dsh-skill-hub 0.1.0 → 0.2.0

package/src/skillfs.test.ts

@@ -2,7 +2,7 @@ import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promise
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { createSkill, disableSkill, enableSkill, parseFrontmatter, rootOfPath, scanDiagnostics } from './skillfs.ts'
+import { clearTrash, createSkill, disableSkill, enableSkill, parseFrontmatter, restoreSkill, rootOfPath, scanDiagnostics, trashSkill } from './skillfs.ts'
 
 describe('parseFrontmatter', () => {
   it('parses a healthy frontmatter', () => {
@@ -86,20 +86,10 @@ describe('parseFrontmatter', () => {
     expect(parseFrontmatter('---\nname: ok-name\n---')).toEqual({ error: 'frontmatter requires a description field' })
   })
 
-  it('parses a single-string sets field into a list', () => {
-    const parsed = parseFrontmatter('---\nname: ok-name\ndescription: x\nsets: engineering\n---')
-    expect(parsed).toMatchObject({ value: { sets: ['engineering'] } })
-  })
-
-  it('parses an array sets field, trimming and dropping empties', () => {
-    const parsed = parseFrontmatter('---\nname: ok-name\ndescription: x\nsets: [engineering, " 3d ", ""]\n---')
-    expect(parsed).toMatchObject({ value: { sets: ['engineering', '3d'] } })
-  })
-
-  it('omits sets when the field is absent or empty', () => {
+  it('ignores sets frontmatter (sets grouping was removed)', () => {
     const expected = { name: 'ok-name', description: 'x', invocation: { modelInvocable: true, userInvocable: true }, content: '' }
-    expect(parseFrontmatter('---\nname: ok-name\ndescription: x\n---')).toEqual({ value: expected })
-    expect(parseFrontmatter('---\nname: ok-name\ndescription: x\nsets: []\n---')).toEqual({ value: expected })
+    expect(parseFrontmatter('---\nname: ok-name\ndescription: x\nsets: engineering\n---')).toEqual({ value: expected })
+    expect(parseFrontmatter('---\nname: ok-name\ndescription: x\nsets: [engineering, " 3d ", ""]\n---')).toEqual({ value: expected })
   })
 })
 
@@ -125,6 +115,21 @@ describe('createSkill / disableSkill / enableSkill', () => {
     expect(parseFrontmatter(text)).toMatchObject({ value: { name: 'demo-skill', description: 'Does demo things' } })
   })
 
+  it('scaffolds numeric-looking names as YAML strings', async () => {
+    const path = await createSkill('user-dsh', '1312', '1231', home)
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain("name: '1312'")
+    expect(text).toContain("description: '1231'")
+    expect(parseFrontmatter(text)).toMatchObject({ value: { name: '1312', description: '1231' } })
+  })
+
+  it('escapes YAML-significant description text', async () => {
+    const path = await createSkill('user-dsh', 'review-skill', 'Reviews: code #1', home)
+    expect(parseFrontmatter(await readFile(path, 'utf8'))).toMatchObject({
+      value: { name: 'review-skill', description: 'Reviews: code #1' },
+    })
+  })
+
   it('refuses non-kebab-case names', async () => {
     await expect(createSkill('user-dsh', 'Not Valid', '', home)).rejects.toThrow(/kebab-case/)
   })
@@ -153,6 +158,68 @@ describe('createSkill / disableSkill / enableSkill', () => {
   })
 })
 
+describe('trashSkill / restoreSkill', () => {
+  let dir: string
+  let home: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-trash-'))
+    home = join(dir, 'home')
+    await mkdir(join(home, 'skills'), { recursive: true })
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('trashes and restores a directory bundle', async () => {
+    const file = await createSkill('user-dsh', 'trash-dir', 'Trash me', home)
+    const { path, source } = await trashSkill(file)
+    expect(source).toBe(join(home, 'skills', 'trash-dir'))
+    expect(path.startsWith(join(home, 'skills', '.trash', 'trash-dir-'))).toBe(true)
+    await expect(access(file)).rejects.toThrow()
+    const restored = await restoreSkill({ name: 'trash-dir', path, movedAt: 1, sourcePath: source }, home)
+    expect(restored).toBe(source)
+    await expect(access(file)).resolves.toBeUndefined()
+  })
+
+  it('trashes and restores a flat skill file', async () => {
+    const flat = join(home, 'skills', 'flat-trash.md')
+    await writeFile(flat, '---\nname: flat-trash\ndescription: Flat\n---\n\nbody', 'utf8')
+    const { path, source } = await trashSkill(flat)
+    expect(source).toBe(flat)
+    await expect(access(flat)).rejects.toThrow()
+    const restored = await restoreSkill({ name: 'flat-trash', path, movedAt: 1, sourcePath: source }, home)
+    expect(restored).toBe(flat)
+    await expect(access(flat)).resolves.toBeUndefined()
+  })
+
+  it('restores a legacy directory entry without a source path', async () => {
+    const file = await createSkill('user-dsh', 'legacy-dir', 'Legacy', home)
+    const { path } = await trashSkill(file)
+    const target = await restoreSkill({ name: 'legacy-dir', path, movedAt: 1 }, home)
+    expect(target).toBe(join(home, 'skills', 'legacy-dir'))
+    await expect(access(join(target, 'SKILL.md'))).resolves.toBeUndefined()
+  })
+
+  it('refuses to restore an entry whose source path is outside the hub roots', async () => {
+    await expect(restoreSkill({ name: 'x', path: join(home, 'skills', '.trash', 'x-1'), movedAt: 1, sourcePath: '/outside/x' }, home))
+      .rejects.toThrow(/writable skill path/)
+  })
+
+  it('permanently clears a trashed skill', async () => {
+    const trashDir = join(home, 'skills', '.trash', 'gone-1')
+    await mkdir(trashDir, { recursive: true })
+    await writeFile(join(trashDir, 'SKILL.md'), '---\nname: gone\ndescription: x\n---', 'utf8')
+    await clearTrash({ name: 'gone', path: trashDir, movedAt: 1, sourcePath: join(home, 'skills', 'gone') }, home)
+    await expect(access(trashDir)).rejects.toThrow()
+  })
+
+  it('refuses to clear a path outside the hub trash roots', async () => {
+    await expect(clearTrash({ name: 'x', path: '/tmp/.trash/x-1', movedAt: 1 }, home)).rejects.toThrow(/not a hub trashed skill path/)
+  })
+})
+
 describe('scanDiagnostics', () => {
   let dir: string
   let home: string
@@ -170,7 +237,7 @@ describe('scanDiagnostics', () => {
   })
 
   it('returns an empty list for a healthy root', async () => {
-    await createSkill('user-dsh', 'good-skill', 'Good', home)
+    await createSkill('user-dsh', 'good-skill', 'Does good things well', home)
     expect(await scanDiagnostics('user-dsh', home)).toEqual([])
   })
 
@@ -192,6 +259,22 @@ describe('scanDiagnostics', () => {
   it('returns an empty list when the root does not exist', async () => {
     expect(await scanDiagnostics('user-dsh', join(dir, 'missing'))).toEqual([])
   })
+
+  it('flags a frontmatter name that diverges from the discovery path', async () => {
+    await mkdir(join(skills, 'folder-name'))
+    await writeFile(join(skills, 'folder-name', 'SKILL.md'), '---\nname: other-name\ndescription: A decent longer description\n---', 'utf8')
+    const entries = await scanDiagnostics('user-dsh', home)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].reason).toContain('does not match the discovery path "folder-name"')
+  })
+
+  it('flags a too-short description', async () => {
+    await mkdir(join(skills, 'short-desc'))
+    await writeFile(join(skills, 'short-desc', 'SKILL.md'), '---\nname: short-desc\ndescription: x\n---', 'utf8')
+    const entries = await scanDiagnostics('user-dsh', home)
+    expect(entries).toHaveLength(1)
+    expect(entries[0].reason).toContain('description is only 1 chars')
+  })
 })
 
 describe('rootOfPath', () => {
@@ -205,4 +288,3 @@ describe('rootOfPath', () => {
     }
   })
 })
-

package/src/skillfs.ts

@@ -12,13 +12,13 @@
  * content is the body after the frontmatter block, trimmed.
  */
 
-import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
-import { load } from 'js-yaml'
+import { dump, load } from 'js-yaml'
 import { isSkillName } from '@deepseek-ai/dsh-skill'
 import { dshHome } from './store.ts'
-import type { DiagnosticEntry, WritableRoot } from './protocol.ts'
+import type { DiagnosticEntry, TrashEntry, WritableRoot } from './protocol.ts'
 
 /** Root ids this module may write to. */
 export const WRITABLE_ROOTS: readonly WritableRoot[] = ['user-dsh', 'user-agents']
@@ -55,10 +55,13 @@ export async function createSkill(root: WritableRoot, name: string, description:
   const dir = join(rootPath(root, home), name)
   const file = join(dir, 'SKILL.md')
   await mkdir(dir, { recursive: true })
+  const safeDescription = description.trim() === '' ? 'New dsh skill created from the skill hub.' : description.trim()
   const body = [
     '---',
-    'name: ' + name,
-    'description: ' + (description.trim() === '' ? 'New dsh skill created from the skill hub.' : description.trim()),
+    // dump() emits a quoted string when plain text would parse as a number,
+    // mapping, or other non-string YAML (the official parser requires strings).
+    'name: ' + dump(name).trim(),
+    'description: ' + dump(safeDescription).trim(),
     '---',
     '',
     '# ' + name,
@@ -95,6 +98,44 @@ export async function enableSkill(disabledPath: string): Promise<string> {
   return original
 }
 
+/**
+ * Move a skill (directory bundle or flat .md file) into the root's trash.
+ * The skill stays recoverable: the source is renamed into
+ * <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
+ * SKILL.md path and moved as a whole directory.
+ * @returns the trashed path plus the original path that was moved.
+ */
+export async function trashSkill(sourcePath: string): Promise<{ path: string; source: string }> {
+  const source = basename(sourcePath) === 'SKILL.md' ? dirname(sourcePath) : sourcePath
+  const trashDir = join(dirname(source), '.trash')
+  await mkdir(trashDir, { recursive: true })
+  const target = join(trashDir, basename(source) + '-' + Date.now())
+  await rename(source, target)
+  return { path: target, source }
+}
+
+/** Restore a trashed skill (directory or flat file) to its original location. */
+export async function restoreSkill(entry: TrashEntry, home = dshHome()): Promise<string> {
+  if (basename(dirname(entry.path)) !== '.trash') {
+    throw new TypeError('not a trashed skill path: ' + entry.path)
+  }
+  const target = entry.sourcePath ?? join(dirname(dirname(entry.path)), entry.name)
+  if (entry.sourcePath !== undefined && rootOfPath(entry.sourcePath, home) === undefined) {
+    throw new TypeError('not a hub writable skill path: ' + entry.sourcePath)
+  }
+  await rename(entry.path, target)
+  return target
+}
+
+/** Permanently delete one trashed skill (directory or flat file). */
+export async function clearTrash(entry: TrashEntry, home = dshHome()): Promise<string> {
+  if (basename(dirname(entry.path)) !== '.trash' || rootOfPath(dirname(dirname(entry.path)), home) === undefined) {
+    throw new TypeError('not a hub trashed skill path: ' + entry.path)
+  }
+  await rm(entry.path, { recursive: true, force: true })
+  return entry.path
+}
+
 /** Classify a skill file path: 'directory' (SKILL.md), 'flat' (<name>.md), or undefined. */
 function skillFileKind(path: string): 'directory' | 'flat' | undefined {
   if (basename(path) === 'SKILL.md') return 'directory'
@@ -107,29 +148,11 @@ export interface FrontmatterValue {
   name: string
   description: string
   whenToUse?: string
-  /** Optional group names the skill declares (frontmatter `sets`). */
-  sets?: string[]
   invocation: { modelInvocable: boolean; userInvocable: boolean }
   /** Instruction body after the frontmatter block, trimmed. */
   content: string
 }
 
-/**
- * Normalize an optional frontmatter `sets` value into a clean string list.
- * Accepts a single string or a string array; trims, drops empties, and
- * ignores non-string entries. Returns undefined when absent or empty, so a
- * skill without sets stays uncategorized.
- */
-export function normalizeSets(raw: unknown): string[] | undefined {
-  const items = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : undefined
-  if (items === undefined) return undefined
-  const sets = items
-    .filter((item): item is string => typeof item === 'string')
-    .map((item) => item.trim())
-    .filter((item) => item !== '')
-  return sets.length === 0 ? undefined : sets
-}
-
 /** Parse a SKILL.md the way the official filesystem provider does. */
 export function parseFrontmatter(text: string): { value: FrontmatterValue } | { error: string } {
   const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n([\s\S]*))?$/.exec(text)
@@ -150,7 +173,6 @@ export function parseFrontmatter(text: string): { value: FrontmatterValue } | {
   const description = typeof record.description === 'string' ? record.description.trim() : ''
   if (description === '') return { error: 'frontmatter requires a description field' }
   const whenToUse = typeof record.whenToUse === 'string' && record.whenToUse.trim() !== '' ? record.whenToUse.trim() : undefined
-  const sets = normalizeSets(record.sets)
   if (Object.hasOwn(record, 'disableModelInvocation')) return { error: 'frontmatter field "disableModelInvocation" is unsupported; use "disable-model-invocation"' }
   if (Object.hasOwn(record, 'modelInvocable')) return { error: 'frontmatter field "modelInvocable" is unsupported; use "disable-model-invocation"' }
   if (Object.hasOwn(record, 'userInvocable')) return { error: 'frontmatter field "userInvocable" is unsupported; use "user-invocable"' }
@@ -162,7 +184,7 @@ export function parseFrontmatter(text: string): { value: FrontmatterValue } | {
   } catch (error) {
     return { error: error instanceof Error ? error.message : String(error) }
   }
-  return { value: { name, description, ...(whenToUse !== undefined ? { whenToUse } : {}), ...(sets !== undefined ? { sets } : {}), invocation, content: (match[2] ?? '').trim() } }
+  return { value: { name, description, ...(whenToUse !== undefined ? { whenToUse } : {}), invocation, content: (match[2] ?? '').trim() } }
 }
 
 /** Official boolean grammar: true/false, 1/0, and the common string spellings. */
@@ -193,10 +215,9 @@ export interface SkillEntry {
 /**
  * Scan one skills root for discovery files: directory bundles (SKILL.md)
  * and flat <name>.md files. Hub-disabled files (.disabled) are excluded;
- * the .system subdirectory is excluded when skipSystem is set (mirrors the
- * official provider's user-dsh behavior).
+ * dot-prefixed entries (including .trash and .system) are always skipped.
  */
-export async function scanRoot(base: string, skipSystem: boolean): Promise<SkillEntry[]> {
+export async function scanRoot(base: string): Promise<SkillEntry[]> {
   const entries: SkillEntry[] = []
   let names: string[]
   try {
@@ -207,7 +228,6 @@ export async function scanRoot(base: string, skipSystem: boolean): Promise<Skill
   }
   for (const name of names) {
     if (name.startsWith('.')) continue
-    if (skipSystem && name === '.system') continue
     const absolute = join(base, name)
     let stats
     try {
@@ -224,9 +244,9 @@ export async function scanRoot(base: string, skipSystem: boolean): Promise<Skill
   return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
 }
 
-/** Scan one writable root (user-dsh skips .system, mirroring the official provider). */
+/** Scan one writable root. */
 export function listSkillEntries(root: WritableRoot, home = dshHome()): Promise<SkillEntry[]> {
-  return scanRoot(rootPath(root, home), root === 'user-dsh')
+  return scanRoot(rootPath(root, home))
 }
 
 /**
@@ -264,8 +284,23 @@ export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Pro
       continue
     }
     const parsed = parseFrontmatter(text)
-    if ('error' in parsed) diagnostics.push({ path: entry.path, root, reason: parsed.error })
+    if ('error' in parsed) {
+      diagnostics.push({ path: entry.path, root, reason: parsed.error })
+      continue
+    }
+    const { value } = parsed
+    // The provider registers a skill by its discovery path (directory name or
+    // flat file name), so a frontmatter name that diverges from the path makes
+    // the skill show up under a different identity than its metadata claims.
+    const pathName = entry.kind === 'directory' ? basename(entry.directory) : basename(entry.path, '.md')
+    if (value.name !== pathName) {
+      diagnostics.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
+    }
+    // Agents decide to auto-activate a skill from its one-line description, so
+    // a too-short description leaves the skill hard to discover automatically.
+    if (value.description.length < 10) {
+      diagnostics.push({ path: entry.path, root, reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill` })
+    }
   }
   return diagnostics
 }
-

package/src/stats.test.ts

@@ -3,11 +3,11 @@ import { countSkillInvocations, createSkillStatsReader, readSkillStats, type Ses
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 /** Minimal user/message event carrying a skill-invocation source. */
-function invocationEvent(name: string, seq = 1): SessionEvent {
+function invocationEvent(name: string, seq = 1, time = 0): SessionEvent {
   return {
     type: 'user/message',
     seq,
-    time: 0,
+    time,
     data: {
       id: 'm' + seq as never,
       role: 'user',
@@ -28,11 +28,11 @@ function plainUserEvent(seq = 1): SessionEvent {
 }
 
 /** Minimal `skill` tool call (model-invoked skill). */
-function skillToolCall(name: string, seq = 1): SessionEvent {
+function skillToolCall(name: string, seq = 1, time = 0): SessionEvent {
   return {
     type: 'tool/call',
     seq,
-    time: 0,
+    time,
     data: { turn: 1, step: 1, callId: 'c' + seq as never, name: 'skill', arguments: JSON.stringify({ name }) },
   } as unknown as SessionEvent
 }
@@ -46,8 +46,8 @@ describe('countSkillInvocations', () => {
       plainUserEvent(4),
     ]
     const counts = countSkillInvocations(events)
-    expect(counts.get('code-review')).toBe(2)
-    expect(counts.get('tdd')).toBe(1)
+    expect(counts.get('code-review')?.count).toBe(2)
+    expect(counts.get('tdd')?.count).toBe(1)
     expect(counts.size).toBe(2)
   })
 
@@ -59,8 +59,8 @@ describe('countSkillInvocations', () => {
       { type: 'tool/call', seq: 4, time: 0, data: { turn: 1, step: 1, callId: 'c4', name: 'bash', arguments: '{}' } } as unknown as SessionEvent,
     ]
     const counts = countSkillInvocations(events)
-    expect(counts.get('godot-master')).toBe(2)
-    expect(counts.get('tdd')).toBe(1)
+    expect(counts.get('godot-master')?.count).toBe(2)
+    expect(counts.get('tdd')?.count).toBe(1)
     expect(counts.size).toBe(2)
   })
 
@@ -71,7 +71,7 @@ describe('countSkillInvocations', () => {
       { type: 'tool/call', seq: 3, time: 0, data: { turn: 1, step: 1, callId: 'c3', name: 'skill', arguments: 'not json' } } as unknown as SessionEvent,
     ]
     const counts = countSkillInvocations(events)
-    expect(counts.get('tdd')).toBe(2)
+    expect(counts.get('tdd')?.count).toBe(2)
     expect(counts.size).toBe(1)
   })
 
@@ -79,6 +79,17 @@ describe('countSkillInvocations', () => {
     expect(countSkillInvocations([]).size).toBe(0)
     expect(countSkillInvocations([plainUserEvent(1)]).size).toBe(0)
   })
+
+  it('records the latest lastUsed time across events', () => {
+    const events = [
+      invocationEvent('a', 1, 1000),
+      invocationEvent('a', 2, 3000),
+      invocationEvent('a', 3, 2000),
+      skillToolCall('a', 4, 2500),
+    ]
+    const stats = countSkillInvocations(events)
+    expect(stats.get('a')).toEqual({ count: 4, lastUsed: 3000 })
+  })
 })
 
 describe('readSkillStats', () => {
@@ -95,8 +106,8 @@ describe('readSkillStats', () => {
       }),
     }
     expect(await readSkillStats(query)).toEqual([
-      { name: 'code-review', count: 1 },
-      { name: 'tdd', count: 2 },
+      { name: 'code-review', count: 1, lastUsed: 0 },
+      { name: 'tdd', count: 2, lastUsed: 0 },
     ])
   })
 
@@ -111,12 +122,30 @@ describe('readSkillStats', () => {
         return { events: [invocationEvent('tdd', 1)] }
       },
     }
-    expect(await readSkillStats(query)).toEqual([{ name: 'tdd', count: 1 }])
+    expect(await readSkillStats(query)).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
   })
 })
 
 describe('createSkillStatsReader', () => {
-  it('caches results within the TTL window', async () => {
+  it('returns empty on first call, then serves the background scan from cache', async () => {
+    let resolveScan: (() => void) | undefined
+    const query: SessionQueryLike = {
+      listSessions: async () => [{ header: { id: 'a' as never } }],
+      readSession: () => new Promise((resolve) => {
+        resolveScan = () => resolve({ events: [invocationEvent('tdd', 1)] } as never)
+      }),
+    }
+    const reader = createSkillStatsReader(query, 60_000)
+    // 首次调用不等待全量扫描：立即返回空。
+    expect(await reader()).toEqual([])
+    // 后台扫描完成后，后续调用命中缓存。
+    resolveScan!()
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+  })
+
+  it('serves stale totals after expiry and rescans only once', async () => {
     let reads = 0
     const query: SessionQueryLike = {
       listSessions: async () => [{ header: { id: 'a' as never } }],
@@ -125,9 +154,15 @@ describe('createSkillStatsReader', () => {
         return { events: [invocationEvent('tdd', 1)] }
       },
     }
-    const reader = createSkillStatsReader(query, 60_000)
-    await reader()
-    await reader()
-    expect(reads).toBe(1)
+    const reader = createSkillStatsReader(query, 200)
+    expect(await reader()).toEqual([])
+    await new Promise((resolve) => setTimeout(resolve, 250))
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    // TTL 过期时立即返回 stale 值并触发一次后台刷新；后续调用命中缓存。
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    expect(reads).toBe(2)
   })
 })

package/src/stats.ts

@@ -25,16 +25,29 @@ export interface SessionQueryLike {
   readSession(id: SessionId): Promise<{ events: SessionEvent[] }>
 }
 
-/** Count skill invocations in one session's event log, keyed by skill name. */
-export function countSkillInvocations(events: readonly SessionEvent[]): Map<string, number> {
-  const counts = new Map<string, number>()
-  const bump = (name: string): void => {
-    if (name !== '') counts.set(name, (counts.get(name) ?? 0) + 1)
+/** Per-skill invocation stats in one session's event log. */
+export interface InvocationStat {
+  count: number
+  /** Unix epoch ms of the most recent invocation in this batch. */
+  lastUsed: number
+}
+
+/** Collect per-skill invocation counts and last-used times from one session. */
+export function countSkillInvocations(events: readonly SessionEvent[]): Map<string, InvocationStat> {
+  const stats = new Map<string, InvocationStat>()
+  const bump = (name: string, time: number): void => {
+    if (name === '') return
+    const current = stats.get(name)
+    if (current === undefined) stats.set(name, { count: 1, lastUsed: time })
+    else {
+      current.count += 1
+      if (time > current.lastUsed) current.lastUsed = time
+    }
   }
   for (const event of events) {
     if (event.type === 'user/message') {
       const source = event.data.source
-      if (source.kind === 'skill-invocation') bump(source.name)
+      if (source.kind === 'skill-invocation') bump(source.name, event.time)
     } else if (event.type === 'tool/call') {
       const call = event.data
       if (call.name === 'skill') {
@@ -43,18 +56,18 @@ export function countSkillInvocations(events: readonly SessionEvent[]): Map<stri
           const parsed: unknown = JSON.parse(call.arguments)
           if (typeof parsed === 'object' && parsed !== null) {
             const name = (parsed as { name?: unknown }).name
-            if (typeof name === 'string') bump(name)
+            if (typeof name === 'string') bump(name, event.time)
           }
         } catch { /* unparseable arguments skip */ }
       }
     }
   }
-  return counts
+  return stats
 }
 
-/** Scan every session and total per-skill invocation counts. */
+/** Scan every session and total per-skill counts, keeping the latest lastUsed. */
 export async function readSkillStats(query: SessionQueryLike): Promise<SkillStat[]> {
-  const totals = new Map<string, number>()
+  const totals = new Map<string, InvocationStat>()
   const sessions = await query.listSessions()
   for (const record of sessions) {
     let snapshot: { events: SessionEvent[] }
@@ -63,25 +76,49 @@ export async function readSkillStats(query: SessionQueryLike): Promise<SkillStat
     } catch {
       continue // unreadable sessions are skipped, never fatal
     }
-    for (const [name, count] of countSkillInvocations(snapshot.events)) {
-      totals.set(name, (totals.get(name) ?? 0) + count)
+    for (const [name, stat] of countSkillInvocations(snapshot.events)) {
+      const total = totals.get(name)
+      if (total === undefined) totals.set(name, { ...stat })
+      else {
+        total.count += stat.count
+        if (stat.lastUsed > total.lastUsed) total.lastUsed = stat.lastUsed
+      }
     }
   }
-  return [...totals.entries()].map(([name, count]) => ({ name, count })).sort((a, b) => a.name.localeCompare(b.name))
+  return [...totals.entries()]
+    .map(([name, stat]) => ({ name, count: stat.count, lastUsed: stat.lastUsed }))
+    .sort((a, b) => a.name.localeCompare(b.name))
 }
 
 /** A memoized stats reader (the panel polls, but logs change slowly). */
 export type SkillStatsReader = () => Promise<SkillStat[]>
 
-/** Wrap a query in a TTL cache so a 5s panel poll does not rescan every log. */
-export function createSkillStatsReader(query: SessionQueryLike, ttlMs = 30_000): SkillStatsReader {
+/**
+ * Wrap a query in a stale-while-revalidate cache: responses never wait for a
+ * full session-log scan. While the TTL is fresh the cached totals are
+ * returned; after expiry the stale totals are returned immediately and a
+ * single background rescan refreshes them — the panel's next poll picks the
+ * fresh numbers. A full scan decompresses every session log and can take
+ * seconds, so it must never sit on the request path.
+ */
+export function createSkillStatsReader(query: SessionQueryLike, ttlMs = 300_000): SkillStatsReader {
   let cached: SkillStat[] | undefined
   let cachedAt = 0
+  let refreshing: Promise<void> | null = null
   return async () => {
     const now = Date.now()
     if (cached !== undefined && now - cachedAt < ttlMs) return cached
-    cached = await readSkillStats(query)
-    cachedAt = Date.now()
-    return cached
+    // Expired (or first call): hand back the stale totals (empty on first
+    // call) and kick off one background rescan.
+    if (refreshing === null) {
+      refreshing = readSkillStats(query)
+        .then((stats) => {
+          cached = stats
+          cachedAt = Date.now()
+        })
+        .catch(() => { /* keep the previous totals on scan failure */ })
+        .finally(() => { refreshing = null })
+    }
+    return cached ?? []
   }
 }