@skillsgate/tui 0.1.12 → 0.1.14

package/src/data/use-installed-skills.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react"
+import { useEffect, useRef } from "react"
 import fs from "node:fs/promises"
 import path from "node:path"
 import os from "node:os"
@@ -8,6 +8,7 @@ import { useDb } from "../db/context.js"
 import { agents } from "../../../cli/src/core/agents.js"
 import { readSkillLock } from "../../../cli/src/core/skill-lock.js"
 import { SKILL_MD } from "../../../cli/src/constants.js"
+import { loadCachedSkills, saveCachedSkills, type CachedSkill } from "../db/skills-cache.js"
 import type { EnrichedSkill } from "../store/types.js"
 import type { AgentType, SkillLockFile } from "../../../cli/src/types.js"
 
@@ -92,111 +93,121 @@ async function listSupportingFiles(skillDir: string): Promise<Array<{ relativePa
   return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
 }
 
+/**
+ * Convert cached skill rows into lightweight EnrichedSkill objects
+ * suitable for rendering the list immediately on startup.
+ */
+function cachedToEnriched(cached: CachedSkill[], lock: SkillLockFile): EnrichedSkill[] {
+  return cached.map((c) => ({
+    name: c.name,
+    description: c.description,
+    filePath: path.join(c.canonicalPath, SKILL_MD),
+    canonicalPath: c.canonicalPath,
+    agents: c.agents,
+    scope: c.scope,
+    projectName: c.scope === "project" ? getProjectNameForPath(c.canonicalPath) : null,
+    hasSupportingFiles: false,
+    supportingFiles: [],
+    metadata: {} as Record<string, unknown>,
+    lock: lock.skills[c.folderName],
+  }))
+}
+
+/**
+ * Convert EnrichedSkill objects from a full scan into CachedSkill rows
+ * for persistence in the SQLite database.
+ */
+function enrichedToCached(skills: EnrichedSkill[]): CachedSkill[] {
+  const now = new Date().toISOString()
+  return skills.map((s) => ({
+    canonicalPath: s.canonicalPath,
+    folderName: path.basename(s.canonicalPath),
+    name: s.name,
+    description: s.description,
+    agents: s.agents,
+    agentShortCodes: [],
+    scope: s.scope,
+    source: s.lock?.source ?? null,
+    sourceType: s.lock?.sourceType ?? null,
+    fileModTime: now,
+    scannedAt: now,
+  }))
+}
+
+/**
+ * Dispatch agent counts derived from the given skills array.
+ */
+function dispatchAgentCounts(
+  skills: EnrichedSkill[],
+  dispatch: ReturnType<typeof useDispatch>,
+): void {
+  const agentCounts = new Map<AgentType, number>()
+  for (const skill of skills) {
+    for (const agentName of skill.agents) {
+      agentCounts.set(agentName, (agentCounts.get(agentName) ?? 0) + 1)
+    }
+  }
+  dispatch({ type: "UPDATE_AGENT_COUNTS", counts: Object.fromEntries(agentCounts) })
+}
+
 /**
  * Scans all detected agent globalSkillsDir paths for SKILL.md files,
  * parses them with gray-matter, enriches with lock file data, and
  * populates the store.
+ *
+ * On first mount, cached results are served instantly while a background
+ * rescan runs. Subsequent tab switches reuse the cache. Press `r` to
+ * force a full rescan.
  */
 export function useInstalledSkills() {
   const dispatch = useDispatch()
   const { installedLoading } = useStore()
-  const { settings } = useDb()
+  const { db, settings } = useDb()
+  const hasLoadedCache = useRef(false)
 
   useEffect(() => {
-    // Only scan when installedLoading is true (initial mount or refresh triggered)
+    // Only act when installedLoading is true (initial mount or refresh triggered)
     if (!installedLoading) return
 
     let cancelled = false
 
-    async function scan() {
-      dispatch({ type: "SET_INSTALLED_LOADING", loading: true })
-
-      try {
-        const lock = await readSkillLock()
-        // Map: skillName -> EnrichedSkill (deduplicating across agents)
-        const skillMap = new Map<string, EnrichedSkill>()
-
-        // Scan each agent's global skills directory
-        for (const agent of Object.values(agents)) {
-          const skillsDir = agent.globalSkillsDir
-          try {
-            const entries = await fs.readdir(skillsDir, { withFileTypes: true })
-            for (const entry of entries) {
-              // Include both real directories and symlinks (skills are often symlinked)
-              if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
-
-              const skillDirPath = path.join(skillsDir, entry.name)
-              const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
-              const skillMdPath = path.join(skillDirPath, SKILL_MD)
-              try {
-                const raw = await fs.readFile(skillMdPath, "utf-8")
-                const { data: frontmatter } = matter(raw)
-                const skillName = entry.name
-                const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
-                const scope = getScopeForPath(canonicalPath)
-                const supportingFiles = await listSupportingFiles(canonicalPath)
-
-                const existing = skillMap.get(canonicalPath)
-                if (existing) {
-                  // Skill already seen from another agent - add this agent
-                  if (!existing.agents.includes(agent.name)) {
-                    existing.agents.push(agent.name)
-                  }
-                } else {
-                  skillMap.set(canonicalPath, {
-                    name: skillName,
-                    description:
-                      (frontmatter.description as string) ??
-                      extractFirstLine(raw),
-                    filePath: skillMdPath,
-                    canonicalPath,
-                    agents: [agent.name],
-                    scope,
-                    projectName:
-                      scope === "project" ? getProjectNameForPath(canonicalPath) : null,
-                    hasSupportingFiles: supportingFiles.length > 0,
-                    supportingFiles,
-                    metadata: frontmatter as Record<string, unknown>,
-                    lock: lock.skills[skillName],
-                  })
-                }
-              } catch {
-                // SKILL.md not found or unreadable in this directory - skip
-              }
-            }
-          } catch {
-            // Agent skills directory doesn't exist - skip
-          }
-        }
-
-        const customScanPaths = settings.get<string[]>("scan.customPaths", [])
-        for (const customPath of customScanPaths) {
-          const resolvedRoot = path.resolve(customPath.replace(/^~(?=$|\/|\\)/, home))
-          const collected = await collectCustomSkills(resolvedRoot, lock)
-          for (const skill of collected) {
-            if (!skillMap.has(skill.canonicalPath)) {
-              skillMap.set(skill.canonicalPath, skill)
+    async function loadFromCacheAndScan() {
+      const isInitialLoad = !hasLoadedCache.current
+
+      // On initial load, try serving from cache first for instant startup
+      if (isInitialLoad) {
+        try {
+          const cached = loadCachedSkills(db)
+          if (cached.length > 0) {
+            const lock = await readSkillLock()
+            const skills = cachedToEnriched(cached, lock)
+            if (!cancelled) {
+              dispatch({ type: "SET_INSTALLED_SKILLS", skills })
+              dispatchAgentCounts(skills, dispatch)
+              hasLoadedCache.current = true
             }
           }
+        } catch {
+          // Cache read failed; fall through to full scan
         }
+      }
 
+      // Run full filesystem scan (in background after cache, or blocking on refresh)
+      try {
+        const scannedSkills = await fullScan(settings)
         if (cancelled) return
 
-        const skills = Array.from(skillMap.values()).sort((a, b) =>
-          a.name.localeCompare(b.name)
-        )
-
-        dispatch({ type: "SET_INSTALLED_SKILLS", skills })
-
-        // Update agent skill counts (without removing agents that have 0 skills)
-        const agentCounts = new Map<AgentType, number>()
-        for (const skill of skills) {
-          for (const agentName of skill.agents) {
-            agentCounts.set(agentName, (agentCounts.get(agentName) ?? 0) + 1)
-          }
+        // Persist to cache
+        try {
+          saveCachedSkills(db, enrichedToCached(scannedSkills))
+        } catch {
+          // Cache write failed; non-critical
         }
 
-        dispatch({ type: "UPDATE_AGENT_COUNTS", counts: Object.fromEntries(agentCounts) })
+        hasLoadedCache.current = true
+
+        dispatch({ type: "SET_INSTALLED_SKILLS", skills: scannedSkills })
+        dispatchAgentCounts(scannedSkills, dispatch)
       } catch {
         if (!cancelled) {
           dispatch({ type: "SET_INSTALLED_SKILLS", skills: [] })
@@ -204,11 +215,88 @@ export function useInstalledSkills() {
       }
     }
 
-    scan()
+    loadFromCacheAndScan()
     return () => { cancelled = true }
   }, [installedLoading])
 }
 
+/**
+ * Performs a full filesystem scan across all agent directories and custom paths.
+ */
+async function fullScan(
+  settings: ReturnType<typeof useDb>["settings"],
+): Promise<EnrichedSkill[]> {
+  const lock = await readSkillLock()
+  const skillMap = new Map<string, EnrichedSkill>()
+
+  // Scan each agent's global skills directory
+  for (const agent of Object.values(agents)) {
+    const skillsDir = agent.globalSkillsDir
+    try {
+      const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+      for (const entry of entries) {
+        // Include both real directories and symlinks (skills are often symlinked)
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+
+        const skillDirPath = path.join(skillsDir, entry.name)
+        const skillMdPath = path.join(skillDirPath, SKILL_MD)
+        try {
+          const raw = await fs.readFile(skillMdPath, "utf-8")
+          const { data: frontmatter } = matter(raw)
+          const skillName = entry.name
+          const canonicalPath = await fs.realpath(skillDirPath).catch(() => skillDirPath)
+          const scope = getScopeForPath(canonicalPath)
+          const supportingFiles = await listSupportingFiles(canonicalPath)
+
+          const existing = skillMap.get(canonicalPath)
+          if (existing) {
+            // Skill already seen from another agent - add this agent
+            if (!existing.agents.includes(agent.name)) {
+              existing.agents.push(agent.name)
+            }
+          } else {
+            skillMap.set(canonicalPath, {
+              name: skillName,
+              description:
+                (frontmatter.description as string) ??
+                extractFirstLine(raw),
+              filePath: skillMdPath,
+              canonicalPath,
+              agents: [agent.name],
+              scope,
+              projectName:
+                scope === "project" ? getProjectNameForPath(canonicalPath) : null,
+              hasSupportingFiles: supportingFiles.length > 0,
+              supportingFiles,
+              metadata: frontmatter as Record<string, unknown>,
+              lock: lock.skills[skillName],
+            })
+          }
+        } catch {
+          // SKILL.md not found or unreadable in this directory - skip
+        }
+      }
+    } catch {
+      // Agent skills directory doesn't exist - skip
+    }
+  }
+
+  const customScanPaths = settings.get<string[]>("scan.customPaths", [])
+  for (const customPath of customScanPaths) {
+    const resolvedRoot = path.resolve(customPath.replace(/^~(?=$|\/|\\)/, home))
+    const collected = await collectCustomSkills(resolvedRoot, lock)
+    for (const skill of collected) {
+      if (!skillMap.has(skill.canonicalPath)) {
+        skillMap.set(skill.canonicalPath, skill)
+      }
+    }
+  }
+
+  return Array.from(skillMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  )
+}
+
 async function collectCustomSkills(
   rootPath: string,
   lock: SkillLockFile,

package/src/data/use-search.ts

@@ -1,5 +1,5 @@
 import { useState, useEffect, useRef, useCallback } from "react"
-import { fetchCatalog, searchSkills, type CatalogSkill, type SearchMode } from "./api-client.js"
+import { searchSkills, type CatalogSkill } from "./api-client.js"
 
 const DEBOUNCE_MS = 300
 const PAGE_SIZE = 20
@@ -11,35 +11,28 @@ interface UseSearchResult {
   total: number
   hasMore: boolean
   loadMore: () => void
-  remainingSearches: number | null
 }
 
 /**
  * Hook that manages search state with debounce and pagination.
- * - When query is empty, loads the catalog with pagination
+ * - When query is empty, loads popular skills
  * - When query is provided, searches after 300ms debounce
- * - Supports keyword and semantic search modes
  */
-export function useSearch(
-  query: string,
-  mode: SearchMode,
-  token?: string | null
-): UseSearchResult {
+export function useSearch(query: string): UseSearchResult {
   const [results, setResults] = useState<CatalogSkill[]>([])
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [total, setTotal] = useState(0)
   const [offset, setOffset] = useState(0)
-  const [remainingSearches, setRemainingSearches] = useState<number | null>(null)
 
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
-  // Reset pagination when query or mode changes
+  // Reset pagination when query changes
   useEffect(() => {
     setResults([])
     setOffset(0)
     setError(null)
-  }, [query, mode])
+  }, [query])
 
   useEffect(() => {
     if (timerRef.current) {
@@ -52,19 +45,10 @@ export function useSearch(
       setError(null)
 
       try {
-        if (query.trim()) {
-          const data = await searchSkills(query, mode, token)
-          setResults(data.skills)
-          setTotal(data.total)
-          if (data.remainingSearches !== undefined) {
-            setRemainingSearches(data.remainingSearches)
-          }
-        } else {
-          const data = await fetchCatalog(PAGE_SIZE, 0)
-          setResults(data.skills)
-          setTotal(data.total)
-          setOffset(PAGE_SIZE)
-        }
+        const data = await searchSkills(query, PAGE_SIZE)
+        setResults(data.skills)
+        setTotal(data.total)
+        setOffset(PAGE_SIZE)
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
         if (!msg.includes("abort")) {
@@ -86,17 +70,17 @@ export function useSearch(
         clearTimeout(timerRef.current)
       }
     }
-  }, [query, mode, token])
+  }, [query])
 
   const loadMore = useCallback(async () => {
-    if (query.trim() || loading) return
-    if (results.length >= total) return
+    if (loading) return
+    if (results.length >= total && total > 0) return
 
     setLoading(true)
     try {
-      const data = await fetchCatalog(PAGE_SIZE, offset)
+      const data = await searchSkills(query, PAGE_SIZE, offset)
       setResults((prev) => [...prev, ...data.skills])
-      setTotal(data.total)
+      setTotal((prev) => prev + data.total)
       setOffset((prev) => prev + PAGE_SIZE)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
@@ -113,6 +97,5 @@ export function useSearch(
     total,
     hasMore: results.length < total,
     loadMore,
-    remainingSearches,
   }
 }

package/src/data/use-skill-actions.ts

@@ -1,11 +1,13 @@
 import { useCallback } from "react"
+import { exec as execCb } from "node:child_process"
+import { promisify } from "node:util"
 import { useStore, useDispatch } from "../store/context.js"
 import { useDb } from "../db/context.js"
-import type { EnrichedSkill } from "../store/types.js"
+import type { EnrichedSkill, Action } from "../store/types.js"
 
 // CLI core imports -- these share the same Bun runtime
 import { parseSource } from "../../../cli/src/core/source-parser.js"
-import { cloneRepo, cleanupTempDir, fetchTreeSha } from "../../../cli/src/core/git.js"
+import { cleanupTempDir, fetchTreeSha } from "../../../cli/src/core/git.js"
 import { discoverSkills } from "../../../cli/src/core/skill-discovery.js"
 import {
   installSkillForAgent,
@@ -16,12 +18,11 @@ import {
 import {
   addSkillToLock,
   removeSkillFromLock,
-  readSkillLock,
 } from "../../../cli/src/core/skill-lock.js"
 import { agents, detectInstalledAgents } from "../../../cli/src/core/agents.js"
 import { downloadSkill } from "../../../cli/src/core/skillsgate-client.js"
 import { getToken } from "../../../cli/src/utils/auth-store.js"
-import type { Skill, AgentConfig, ParsedSource } from "../../../cli/src/types.js"
+import type { Skill, AgentConfig } from "../../../cli/src/types.js"
 
 interface UseSkillActionsResult {
   installSkill: (skill: EnrichedSkill) => Promise<void>
@@ -40,7 +41,9 @@ export function useSkillActions(): UseSkillActionsResult {
   const { settings } = useDb()
 
   /**
-   * Install a skill from its source (GitHub URL, SkillsGate slug, or install command).
+   * Install a skill from its source.
+   * For public skills (with a source in owner/repo format), runs `npx skills add`.
+   * For private skills, uses the existing download flow.
    */
   const installSkill = useCallback(async (skill: EnrichedSkill) => {
     dispatch({
@@ -61,7 +64,16 @@ export function useSkillActions(): UseSkillActionsResult {
 
       const source = parseSource(sourceStr)
 
-      // Detect installed agents to install to
+      // Public skills (owner/repo format): use `npx skills add`
+      if (source.type === "github" || isOwnerRepoFormat(sourceStr)) {
+        const repo = source.type === "github"
+          ? `${source.owner}/${source.repo}`
+          : sourceStr
+        await runSkillsAdd(repo, dispatch)
+        return
+      }
+
+      // Private skills: use the existing download flow
       const installedAgents = await detectInstalledAgents()
       if (installedAgents.length === 0) {
         dispatch({
@@ -88,19 +100,16 @@ export function useSkillActions(): UseSkillActionsResult {
 
       let tmpDir: string
       if (source.type === "skillsgate") {
-        // Download from SkillsGate API
+        // Download from private API
         const token = await getToken()
         tmpDir = await downloadSkill(source.username!, source.slug!, token)
-      } else if (source.type === "github") {
-        // Clone from GitHub
-        tmpDir = await cloneRepo(source)
       } else {
         // Local path -- use directly
         tmpDir = source.localPath!
       }
 
       try {
-        // Discover skills in the cloned/downloaded directory
+        // Discover skills in the downloaded directory
         const skills = await discoverSkills(tmpDir, source.subpath)
 
         if (skills.length === 0) {
@@ -320,9 +329,49 @@ export function useSkillActions(): UseSkillActionsResult {
 
 // ---------- Helpers ----------
 
+const execAsync = promisify(execCb)
+
+/**
+ * Checks if a string matches the owner/repo format (e.g. "vercel/skills").
+ */
+function isOwnerRepoFormat(str: string): boolean {
+  return /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(str)
+}
+
+/**
+ * Runs `npx skills add <source> --all -y` as a child process to install
+ * all skills from a public repository.
+ */
+async function runSkillsAdd(
+  source: string,
+  dispatch: (action: Action) => void
+): Promise<void> {
+  try {
+    await execAsync(
+      `npx skills add ${source} --all -y`,
+      { timeout: 60_000 }
+    )
+
+    dispatch({ type: "REFRESH_SKILLS" })
+    dispatch({
+      type: "SHOW_NOTIFICATION",
+      notification: {
+        type: "success",
+        message: `Installed skills from ${source}`,
+      },
+    })
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    dispatch({
+      type: "SHOW_NOTIFICATION",
+      notification: { type: "error", message: `Install failed: ${msg}` },
+    })
+  }
+}
+
 /**
  * Resolves the source string for a skill from its metadata.
- * Checks: lock.source, metadata.githubUrl, metadata.installCommand
+ * Checks: lock.source, metadata.source, metadata.githubUrl, metadata.installCommand
  */
 function resolveSource(skill: EnrichedSkill): string | null {
   // From lock file entry
@@ -330,17 +379,20 @@ function resolveSource(skill: EnrichedSkill): string | null {
     return skill.lock.source
   }
 
-  // From metadata (catalog skills)
+  // From metadata (catalog skills -- owner/repo format)
   const meta = skill.metadata
+  if (meta?.source && typeof meta.source === "string") {
+    return meta.source
+  }
+
   if (meta?.githubUrl && typeof meta.githubUrl === "string") {
     return meta.githubUrl
   }
 
-  // From install command (e.g. "skillsgate add @user/slug")
+  // From install command (e.g. "skills add <source>")
   if (meta?.installCommand && typeof meta.installCommand === "string") {
     const cmd = meta.installCommand as string
-    // Extract the source from "skillsgate add <source>" or "skillsgate install <source>"
-    const match = cmd.match(/skillsgate\s+(?:add|install)\s+(.+)/)
+    const match = cmd.match(/skills?\s+(?:add|install)\s+(.+)/)
     if (match) {
       return match[1].trim()
     }

package/src/db/migrations.ts

@@ -50,6 +50,26 @@ const MIGRATIONS: Migration[] = [
       INSERT OR IGNORE INTO schema_version VALUES (1);
     `,
   },
+  {
+    version: 2,
+    up: `
+      CREATE TABLE IF NOT EXISTS cached_skills (
+        canonical_path TEXT PRIMARY KEY,
+        folder_name TEXT NOT NULL,
+        name TEXT NOT NULL,
+        description TEXT NOT NULL DEFAULT '',
+        agents TEXT NOT NULL DEFAULT '[]',
+        agent_short_codes TEXT NOT NULL DEFAULT '[]',
+        scope TEXT NOT NULL DEFAULT 'global',
+        source TEXT,
+        source_type TEXT,
+        file_mod_time TEXT NOT NULL,
+        scanned_at TEXT NOT NULL
+      );
+
+      INSERT OR IGNORE INTO schema_version VALUES (2);
+    `,
+  },
 ]
 
 function getCurrentVersion(db: Database): number {

package/src/db/skills-cache.ts

@@ -0,0 +1,89 @@
+import type { Database } from "bun:sqlite"
+import type { AgentType, SourceType } from "../../../cli/src/types.js"
+
+export interface CachedSkill {
+  canonicalPath: string
+  folderName: string
+  name: string
+  description: string
+  agents: AgentType[]
+  agentShortCodes: string[]
+  scope: "global" | "project" | "custom"
+  source: string | null
+  sourceType: SourceType | null
+  fileModTime: string
+  scannedAt: string
+}
+
+interface CachedSkillRow {
+  canonical_path: string
+  folder_name: string
+  name: string
+  description: string
+  agents: string
+  agent_short_codes: string
+  scope: string
+  source: string | null
+  source_type: string | null
+  file_mod_time: string
+  scanned_at: string
+}
+
+function rowToSkill(row: CachedSkillRow): CachedSkill {
+  return {
+    canonicalPath: row.canonical_path,
+    folderName: row.folder_name,
+    name: row.name,
+    description: row.description,
+    agents: JSON.parse(row.agents) as AgentType[],
+    agentShortCodes: JSON.parse(row.agent_short_codes) as string[],
+    scope: row.scope as CachedSkill["scope"],
+    source: row.source,
+    sourceType: row.source_type as SourceType | null,
+    fileModTime: row.file_mod_time,
+    scannedAt: row.scanned_at,
+  }
+}
+
+export function loadCachedSkills(db: Database): CachedSkill[] {
+  const rows = db
+    .query("SELECT * FROM cached_skills ORDER BY name ASC")
+    .all() as CachedSkillRow[]
+  return rows.map(rowToSkill)
+}
+
+export function saveCachedSkills(db: Database, skills: CachedSkill[]): void {
+  const insert = db.query(
+    `INSERT OR REPLACE INTO cached_skills
+       (canonical_path, folder_name, name, description, agents, agent_short_codes, scope, source, source_type, file_mod_time, scanned_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  )
+
+  db.exec("BEGIN TRANSACTION")
+  try {
+    db.exec("DELETE FROM cached_skills")
+    for (const skill of skills) {
+      insert.run(
+        skill.canonicalPath,
+        skill.folderName,
+        skill.name,
+        skill.description,
+        JSON.stringify(skill.agents),
+        JSON.stringify(skill.agentShortCodes),
+        skill.scope,
+        skill.source,
+        skill.sourceType,
+        skill.fileModTime,
+        skill.scannedAt,
+      )
+    }
+    db.exec("COMMIT")
+  } catch (err) {
+    db.exec("ROLLBACK")
+    throw err
+  }
+}
+
+export function clearSkillsCache(db: Database): void {
+  db.exec("DELETE FROM cached_skills")
+}