skillview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 myskills contributors
+
+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,62 @@
+# skillview
+
+An interactive terminal manager for the AI agent skills on your machine.
+
+`skillview` scans the skill folders of your local AI agents — **Claude** (`~/.claude`),
+**Cursor** (`~/.cursor`), and **Agents** (`~/.agents`) — and lets you browse them by agent,
+sorted by how recently they changed. View a skill's full `SKILL.md`, search across titles and
+descriptions, and delete skills you no longer want, all without leaving the terminal.
+
+## Install
+
+```bash
+npm install -g skillview
+```
+
+Then run:
+
+```bash
+skillview            # launch the interactive browser
+skillview --help     # show usage and keybindings
+skillview --version  # print the version
+```
+
+Requires Node.js >= 18.
+
+## How it works
+
+Skills are expected at:
+
+```
+~/.claude/skills/<skill>/SKILL.md
+~/.cursor/skills/<skill>/SKILL.md
+~/.agents/skills/<skill>/SKILL.md
+```
+
+Each `SKILL.md` starts with YAML frontmatter holding `name` and `description`. `skillview` reads
+that to show a colored title and a short description for every skill.
+
+## Navigation
+
+The UI has three levels:
+
+1. **Agents** — pick `.claude`, `.cursor`, or `.agents` (shown with skill counts).
+2. **Skills** — skills in that agent, newest first. Each shows an orange title and a two-line
+   description.
+3. **Skill detail** — the full, scrollable `SKILL.md`.
+
+### Keys
+
+| Key             | Action                                  |
+| --------------- | --------------------------------------- |
+| `↑` / `↓`       | Move selection / scroll                 |
+| `Enter`         | Open the selected agent or skill        |
+| `Esc` / `←`     | Go back a level                         |
+| `/`             | Search skills (in the skills view)      |
+| `d`             | Delete the selected skill (asks first)  |
+| `PgUp` / `PgDn` | Page through a long skill in detail view |
+| `q` / `Ctrl+C`  | Quit                                    |
+
+## License
+
+MIT

package/dist/app.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useCallback } from "react";
+import { Box, Text, useApp } from "ink";
+import { listAgents, listSkills } from "./lib/scanner.js";
+import { AgentList } from "./components/AgentList.js";
+import { SkillList } from "./components/SkillList.js";
+import { SkillView } from "./components/SkillView.js";
+import { ORANGE } from "./theme.js";
+export function App() {
+    const { exit } = useApp();
+    const [view, setView] = useState("agents");
+    const [agents, setAgents] = useState(() => listAgents());
+    const [agent, setAgent] = useState(null);
+    const [skills, setSkills] = useState([]);
+    const [skill, setSkill] = useState(null);
+    // Quit ('q') is handled per-view so it never fires while typing in the search
+    // box. Ctrl+C always exits via Ink's default handler.
+    const openAgent = useCallback((a) => {
+        setAgent(a);
+        setSkills(listSkills(a));
+        setView("skills");
+    }, []);
+    const refreshSkills = useCallback(() => {
+        if (agent) {
+            // Re-read agent metadata (counts) and skills after a delete.
+            const fresh = listAgents().find((a) => a.id === agent.id) ?? agent;
+            setAgent(fresh);
+            setSkills(listSkills(fresh));
+            setAgents(listAgents());
+        }
+    }, [agent]);
+    const openSkill = useCallback((s) => {
+        setSkill(s);
+        setView("detail");
+    }, []);
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 0, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { color: ORANGE, bold: true, children: "skillview" }), _jsx(Text, { color: "gray", children: " \u00B7 local AI skill manager" })] }), view === "agents" && (_jsx(AgentList, { agents: agents, onSelect: openAgent, onQuit: exit })), view === "skills" && agent && (_jsx(SkillList, { agent: agent, skills: skills, onOpen: openSkill, onBack: () => setView("agents"), onChanged: refreshSkills })), view === "detail" && skill && (_jsx(SkillView, { skill: skill, onBack: () => setView("skills") }))] }));
+}

package/dist/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+/// <reference types="node" />
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { render } from "ink";
+import { App } from "./app.js";
+function readVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+const HELP = `skillview — interactive manager for your local AI agent skills
+
+Usage:
+  skillview            Launch the interactive browser
+  skillview --help     Show this help
+  skillview --version  Show the version
+
+Scans skills under ~/.claude/skills, ~/.cursor/skills, and ~/.agents/skills.
+
+Navigation:
+  ↑/↓            Move selection / scroll
+  Enter          Open the selected agent or skill
+  Esc / ←        Go back a level
+  /              Search skills (in the skills view)
+  d              Delete the selected skill (asks first)
+  PgUp / PgDn    Page through a skill in the detail view
+  q / Ctrl+C     Quit`;
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+    console.log(readVersion());
+    process.exit(0);
+}
+render(_jsx(App, {}));

package/dist/components/AgentList.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import { ORANGE } from "../theme.js";
+export function AgentList({ agents, onSelect, onQuit }) {
+    const [index, setIndex] = useState(0);
+    useInput((input, key) => {
+        if (input === "q") {
+            onQuit();
+        }
+        else if (key.upArrow || input === "k") {
+            setIndex((i) => (i - 1 + agents.length) % agents.length);
+        }
+        else if (key.downArrow || input === "j") {
+            setIndex((i) => (i + 1) % agents.length);
+        }
+        else if (key.return) {
+            const a = agents[index];
+            if (a && a.exists && a.count > 0)
+                onSelect(a);
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "gray", children: "Select an agent:" }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: agents.map((a, i) => {
+                    const selected = i === index;
+                    const enterable = a.exists && a.count > 0;
+                    const status = !a.exists
+                        ? "not found"
+                        : a.count === 0
+                            ? "empty"
+                            : `${a.count} skill${a.count === 1 ? "" : "s"}`;
+                    return (_jsxs(Box, { children: [_jsx(Text, { color: selected ? ORANGE : undefined, children: selected ? "❯ " : "  " }), _jsx(Text, { color: selected ? ORANGE : enterable ? undefined : "gray", bold: selected, children: a.label }), _jsxs(Text, { color: "gray", children: ["  ", a.id, " \u00B7 ", status] })] }, a.id));
+                }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "\u2191/\u2193 move \u00B7 Enter open \u00B7 q quit" }) })] }));
+}

package/dist/components/ConfirmDelete.js

@@ -0,0 +1,13 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+export function ConfirmDelete({ skill, onConfirm, onCancel }) {
+    useInput((input, key) => {
+        if (input === "y" || input === "Y") {
+            onConfirm();
+        }
+        else if (input === "n" || input === "N" || key.escape || key.return) {
+            onCancel();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "red", paddingX: 1, children: [_jsxs(Text, { color: "red", bold: true, children: ["Delete skill \"", skill.title, "\"?"] }), _jsx(Text, { color: "gray", children: "This permanently removes:" }), _jsx(Text, { color: "gray", children: skill.path }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: ["Press ", _jsx(Text, { color: "red", bold: true, children: "y" }), " to delete \u00B7 any other key to cancel"] }) })] }));
+}

package/dist/components/SkillList.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useMemo, useEffect } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import TextInput from "ink-text-input";
+import { deleteSkill } from "../lib/scanner.js";
+import { wrapToLines } from "../lib/wrap.js";
+import { ConfirmDelete } from "./ConfirmDelete.js";
+import { ORANGE } from "../theme.js";
+const ITEM_ROWS = 4; // title + 2 description lines + blank separator
+export function SkillList({ agent, skills, onOpen, onBack, onChanged }) {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const rows = stdout?.rows ?? 24;
+    const columns = stdout?.columns ?? 80;
+    const [mode, setMode] = useState("list");
+    const [query, setQuery] = useState("");
+    const [index, setIndex] = useState(0);
+    const [offset, setOffset] = useState(0);
+    const [message, setMessage] = useState(null);
+    const filtered = useMemo(() => {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return skills;
+        return skills.filter((s) => s.title.toLowerCase().includes(q) ||
+            s.description.toLowerCase().includes(q));
+    }, [skills, query]);
+    // Keep selection in range when the list changes.
+    useEffect(() => {
+        setIndex((i) => Math.min(i, Math.max(0, filtered.length - 1)));
+    }, [filtered.length]);
+    const perPage = Math.max(1, Math.floor((rows - 8) / ITEM_ROWS));
+    // Scroll so the selected item stays visible.
+    useEffect(() => {
+        setOffset((o) => {
+            if (index < o)
+                return index;
+            if (index >= o + perPage)
+                return index - perPage + 1;
+            return o;
+        });
+    }, [index, perPage]);
+    const selected = filtered[index];
+    useInput((input, key) => {
+        if (input === "q") {
+            exit();
+        }
+        else if (key.upArrow || input === "k") {
+            setIndex((i) => (i - 1 + filtered.length) % Math.max(1, filtered.length));
+            setMessage(null);
+        }
+        else if (key.downArrow || input === "j") {
+            setIndex((i) => (i + 1) % Math.max(1, filtered.length));
+            setMessage(null);
+        }
+        else if (key.return) {
+            if (selected)
+                onOpen(selected);
+        }
+        else if (input === "d") {
+            if (selected)
+                setMode("confirm");
+        }
+        else if (input === "/") {
+            setMode("search");
+            setMessage(null);
+        }
+        else if (key.escape || key.leftArrow) {
+            if (query) {
+                setQuery("");
+            }
+            else {
+                onBack();
+            }
+        }
+    }, { isActive: mode === "list" });
+    // Esc inside the search box clears the query and returns to the list.
+    useInput((_input, key) => {
+        if (key.escape) {
+            setQuery("");
+            setMode("list");
+        }
+    }, { isActive: mode === "search" });
+    if (mode === "confirm" && selected) {
+        return (_jsx(ConfirmDelete, { skill: selected, onConfirm: () => {
+                const title = selected.title;
+                try {
+                    deleteSkill(selected);
+                    setMessage(`Deleted "${title}"`);
+                }
+                catch (err) {
+                    setMessage(`Failed to delete: ${String(err)}`);
+                }
+                setMode("list");
+                onChanged();
+            }, onCancel: () => setMode("list") }));
+    }
+    const descWidth = columns - 6;
+    const visible = filtered.slice(offset, offset + perPage);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: ORANGE, bold: true, children: agent.label }), _jsxs(Text, { color: "gray", children: ["  ", filtered.length, query ? `/${skills.length}` : "", " skill", skills.length === 1 ? "" : "s", " \u00B7 newest first"] })] }), (mode === "search" || query) && (_jsxs(Box, { children: [_jsx(Text, { color: "gray", children: "search: " }), mode === "search" ? (_jsx(TextInput, { value: query, onChange: setQuery, onSubmit: () => setMode("list") })) : (_jsx(Text, { children: query }))] })), message && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "green", children: message }) })), _jsx(Box, { flexDirection: "column", marginTop: 1, children: filtered.length === 0 ? (_jsx(Text, { color: "gray", children: query ? "No skills match your search." : "No skills here." })) : (visible.map((s, i) => {
+                    const realIndex = offset + i;
+                    const isSel = realIndex === index;
+                    const descLines = wrapToLines(s.description || "(no description)", descWidth, 2);
+                    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: isSel ? ORANGE : "gray", children: isSel ? "❯ " : "  " }), _jsx(Text, { color: ORANGE, bold: isSel, children: s.title })] }), descLines.map((line, li) => (_jsxs(Text, { color: s.description ? undefined : "gray", children: ["  ", line] }, li)))] }, s.path));
+                })) }), _jsx(Box, { children: _jsx(Text, { color: "gray", children: "\u2191/\u2193 move \u00B7 Enter view \u00B7 / search \u00B7 d delete \u00B7 Esc back \u00B7 q quit" }) })] }));
+}

package/dist/components/SkillView.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useMemo, useEffect } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { readSkill } from "../lib/scanner.js";
+import { ORANGE } from "../theme.js";
+export function SkillView({ skill, onBack }) {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const rows = stdout?.rows ?? 24;
+    const content = useMemo(() => readSkill(skill), [skill]);
+    const lines = useMemo(() => content.replace(/\t/g, "    ").split("\n"), [
+        content,
+    ]);
+    const viewport = Math.max(3, rows - 6); // reserve header + footer
+    const maxOffset = Math.max(0, lines.length - viewport);
+    const [offset, setOffset] = useState(0);
+    useEffect(() => {
+        setOffset(0);
+    }, [skill]);
+    useInput((input, key) => {
+        if (key.escape || key.leftArrow || input === "b") {
+            onBack();
+        }
+        else if (input === "q") {
+            exit();
+        }
+        else if (key.upArrow || input === "k") {
+            setOffset((o) => Math.max(0, o - 1));
+        }
+        else if (key.downArrow || input === "j") {
+            setOffset((o) => Math.min(maxOffset, o + 1));
+        }
+        else if (key.pageUp) {
+            setOffset((o) => Math.max(0, o - viewport));
+        }
+        else if (key.pageDown || input === " ") {
+            setOffset((o) => Math.min(maxOffset, o + viewport));
+        }
+        else if (input === "g") {
+            setOffset(0);
+        }
+        else if (input === "G") {
+            setOffset(maxOffset);
+        }
+    });
+    const visible = lines.slice(offset, offset + viewport);
+    const atEnd = offset >= maxOffset;
+    const pct = maxOffset === 0 ? 100 : Math.round((offset / maxOffset) * 100);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: ORANGE, bold: true, children: skill.title }), _jsxs(Text, { color: "gray", children: ["  ", skill.file] })] }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: visible.map((line, i) => (_jsx(Text, { children: line.length ? line : " " }, offset + i))) }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "gray", children: [atEnd ? "END" : `${pct}%`, " \u00B7 \u2191/\u2193 scroll \u00B7 PgUp/PgDn page \u00B7 g/G top/bottom \u00B7 Esc back \u00B7 q quit"] }) })] }));
+}

package/dist/lib/scanner.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import matter from "gray-matter";
+/** The agent directories we manage, in display order. */
+const AGENT_DEFS = [
+    { id: ".claude", label: "Claude" },
+    { id: ".cursor", label: "Cursor" },
+    { id: ".agents", label: "Agents" },
+];
+const HOME = os.homedir();
+function skillsDirFor(id) {
+    return path.join(HOME, id, "skills");
+}
+/** Collapse any run of whitespace (incl. newlines) into single spaces. */
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** A skill entry may be a real directory or a symlink to one. */
+function isDirLike(entry) {
+    return entry.isDirectory() || entry.isSymbolicLink();
+}
+function countSkills(skillsDir) {
+    try {
+        return fs
+            .readdirSync(skillsDir, { withFileTypes: true })
+            .filter((e) => isDirLike(e) &&
+            fs.existsSync(path.join(skillsDir, e.name, "SKILL.md"))).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** List the agent directories with their skill counts. */
+export function listAgents() {
+    return AGENT_DEFS.map(({ id, label }) => {
+        const skillsDir = skillsDirFor(id);
+        const exists = fs.existsSync(skillsDir);
+        return {
+            id,
+            label,
+            skillsDir,
+            exists,
+            count: exists ? countSkills(skillsDir) : 0,
+        };
+    });
+}
+/** List the skills inside an agent, sorted by SKILL.md mtime (newest first). */
+export function listSkills(agent) {
+    let entries;
+    try {
+        entries = fs.readdirSync(agent.skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!isDirLike(entry))
+            continue;
+        const dirPath = path.join(agent.skillsDir, entry.name);
+        const file = path.join(dirPath, "SKILL.md");
+        let stat;
+        try {
+            stat = fs.statSync(file);
+        }
+        catch {
+            continue; // no SKILL.md -> not a skill
+        }
+        let title = entry.name;
+        let description = "";
+        try {
+            const raw = fs.readFileSync(file, "utf8");
+            const { data } = matter(raw);
+            if (typeof data.name === "string" && data.name.trim()) {
+                title = data.name.trim();
+            }
+            if (typeof data.description === "string") {
+                description = collapse(data.description);
+            }
+        }
+        catch {
+            // keep dir-name title, empty description
+        }
+        skills.push({
+            dir: entry.name,
+            path: dirPath,
+            file,
+            title,
+            description,
+            mtime: stat.mtimeMs,
+        });
+    }
+    skills.sort((a, b) => b.mtime - a.mtime);
+    return skills;
+}
+/** Read the raw SKILL.md contents for the detail view. */
+export function readSkill(skill) {
+    try {
+        return fs.readFileSync(skill.file, "utf8");
+    }
+    catch (err) {
+        return `Failed to read ${skill.file}\n\n${String(err)}`;
+    }
+}
+/** Permanently delete a skill's directory. */
+export function deleteSkill(skill) {
+    fs.rmSync(skill.path, { recursive: true, force: true });
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/wrap.js

@@ -0,0 +1,42 @@
+/**
+ * Wrap a single-line string into at most `maxLines` lines of `width` columns,
+ * appending an ellipsis if the text is truncated. Returns at least one line.
+ */
+export function wrapToLines(text, width, maxLines) {
+    const w = Math.max(8, width);
+    if (!text)
+        return [""];
+    const words = text.split(" ");
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        const candidate = current ? `${current} ${word}` : word;
+        if (candidate.length <= w) {
+            current = candidate;
+            continue;
+        }
+        // candidate too long
+        if (current)
+            lines.push(current);
+        current = word;
+        // a single word longer than the width: hard-split it
+        while (current.length > w) {
+            lines.push(current.slice(0, w));
+            current = current.slice(w);
+        }
+        if (lines.length >= maxLines)
+            break;
+    }
+    if (current && lines.length < maxLines)
+        lines.push(current);
+    if (lines.length > maxLines)
+        lines.length = maxLines;
+    // If we ran out of room but there was more text, mark truncation.
+    const consumed = lines.join(" ").length;
+    if (consumed < text.length && lines.length > 0) {
+        const last = lines[maxLines - 1] ?? lines[lines.length - 1] ?? "";
+        const trimmed = last.length >= w ? `${last.slice(0, w - 1)}…` : `${last}…`;
+        lines[lines.length - 1] = trimmed;
+    }
+    return lines.length ? lines : [""];
+}

package/dist/theme.js

@@ -0,0 +1,4 @@
+/** Claude-style orange used for skill/agent titles. */
+export const ORANGE = "#d97757";
+/** Dim gray used for help bars and secondary text. */
+export const DIM = "gray";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "skillview",
+  "version": "0.1.0",
+  "description": "Interactive terminal manager for local AI agent skills (Claude, Cursor, Agents). Browse, search, view, and delete SKILL.md files by agent and recency.",
+  "keywords": [
+    "ai",
+    "skills",
+    "claude",
+    "cursor",
+    "agents",
+    "cli",
+    "tui",
+    "ink",
+    "skill-manager"
+  ],
+  "license": "MIT",
+  "author": "Jianyu",
+  "type": "module",
+  "bin": {
+    "skillview": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.tsx",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "ink": "^5.1.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}