Agent Skill Hub

A localhost-only web app for browsing every Agent Skill installed on your machine and in your projects — per platform, per path, per instance — and for generating safe, agent-ready prompts to edit or clean them up.

Agent Skills (SKILL.md directories) accumulate across tools: Claude Code, Codex CLI, Cursor, Gemini CLI, shared ~/.agents/skills directories, per-project skill folders, symlinks between all of them. This hub scans those locations, deduplicates what is actually the same skill, shows which platform sees which copy through which path, flags problems (broken links, duplicate conflicts, invalid frontmatter), and generates careful prompts for your coding agent when something needs fixing — while itself staying read-only and fully offline.

Status: v0.3.0 is published — inventory, diagnostics, snapshot changes, the read-only Prompt Center, and the Phase 6 security hardening (local sessions, exact origins, CSRF, approved roots, log masking) are in place, CI-verified on macOS, Linux, and Windows. See the changelog, release notes, AGENT_SKILL_HUB_DEVELOPMENT_PLAN_KO.md for the full plan, and docs/VERIFICATION.md for recorded exit-criteria runs. Next up (not started): direct, journaled cleanup actions with rollback (Phase 7).

Install and first run

Requires Node.js ≥ 22. No global install needed:

npx agent-skill-hub

or install it:

npm install -g agent-skill-hub
agent-skill-hub

What happens on start:

1. The server binds to 127.0.0.1 on port 4317 (or the next free port) and only ever listens on localhost.
2. Your browser opens with a one-time session link (http://127.0.0.1:<port>/#bootstrap=<token>). The token travels in the URL fragment, is exchanged once for an HttpOnly session cookie, and is scrubbed from the address bar. Other local pages and processes cannot use the API without it.
3. An initial scan runs in the background; results appear as soon as it finishes.

Useful flags:

• --no-open — do not open a browser; print the one-time session link once in the terminal instead (valid ~15 minutes; restart for a fresh one).
• --port <n> — preferred port (falls back to the next free port).
• --watch — debounce file changes in scanned roots into automatic rescans.
• --home <dir> — treat <dir> as the home directory (testing/demos).
• agent-skill-hub scan — one-shot CLI scan without the server.

If your session ever shows “Session required” (server restarted, session expired), restart agent-skill-hub — every session lives only in server memory, by design.

What it does

• 59 built-in platforms (Claude Code, Codex CLI, Cursor, Gemini CLI, …) registered in a single schema-validated data file with per-OS, $HOME-rooted candidate paths, plus your own custom platforms.
• Shared-root deduplication: directories read by several platforms (e.g. $HOME/.agents/skills, shared by 8 platforms) are merged by real path into one scan root with many platform observations — including through symlinks.
• Web UI: Dashboard, Platforms, All Skills, All Instances, Projects, Problems (H001–H015 health rules), Changes (snapshot history + diff), Prompt Center, and Settings — with search, filters, virtualized lists, and JSON/CSV export.
• Prompt Center: deterministic Generic/Codex/Claude Code prompts for Inspect, Edit, Disable, Unlink, Archive, Delete, and Repair link. Impact and risk are calculated from the current snapshot; Delete is always archive-first. Optional history stores bounded metadata only — never prompt bodies or your instructions.
• Approved roots (Settings): skills behind symlinks that leave your home directory stay unread until you explicitly approve the target directory. Approvals are validated (no filesystem roots, no home ancestors, no overlaps) and enforced again on every content read.

Where your data lives

Everything the app writes stays under $HOME/.agent-skill-hub/:

Path	Contents
config.json	approved project roots
approved-roots.json	approved extra roots
platforms.custom.json	your custom platforms
snapshots/	current scan snapshot + bounded history
cache/	SKILL.md parse/hash cache
prompt-history.json	optional prompt metadata (opt-in, bounded)

Uninstall / reset: remove the package (npm uninstall -g agent-skill-hub) and delete $HOME/.agent-skill-hub/. The app never modifies your skill files, so there is nothing else to restore. If a state file is ever corrupted the app backs it up as *.corrupt-<timestamp>.bak next to the original and continues with defaults — delete or inspect those at your leisure.

Security model

• Binds to 127.0.0.1 only; other interfaces are not supported.
• Host-header allowlist (DNS-rebinding guard) and an exact-origin allowlist — other localhost ports are rejected, CORS stays disabled.
• Every API surface except health, static UI assets, and the bootstrap exchange requires the in-memory session (HttpOnly, SameSite=Strict cookie); every state-changing request additionally requires the per-session X-Agent-Skill-Hub-CSRF header and a JSON content type.
• Content reads re-check both the stored lexical path and the live realpath against the currently-approved boundaries (home, projects, approved roots) on every request — a symlink swapped after a scan, or a boundary removed a second ago, is refused.
• Logs mask your home directory to ~ and redact token/cookie/session/CSRF-bearing fields; unexpected errors return an opaque internal-error body with no stack or path.
• No skill file-write APIs, no shell execution, no telemetry, no external network requests at runtime.

See SECURITY.md for the threat model and how to report vulnerabilities.

Troubleshooting

• The scan found nothing. The Platforms page lists every candidate path per platform with its live status (missing, exists-empty, exists-with-skills, …) — a missing directory is a status, not an error. Project-local skills only appear after you add the project directory on the Projects page.
• A skill shows an external-symlink-target warning. A symlink points outside your home directory, so its content is deliberately not read. Approve the target directory under Settings → Approved extra roots, then Rescan.
• No browser opened (SSH, headless, or the launch failed). Restart with agent-skill-hub --no-open and open the printed one-time link yourself.
• “Session required” after a while. The server restarted or the session expired; sessions are memory-only by design. Restart agent-skill-hub for a fresh link.
• permission-denied on a root. The app runs with your user's permissions and never elevates; fix the directory permissions or leave it — the rest of the scan is unaffected.

Development

Requires pnpm ≥ 10.

pnpm install
pnpm dev        # Fastify API on 127.0.0.1:4317 + Vite UI on 127.0.0.1:5173

The dev API prints its own one-time session link pointing at the Vite origin (http://127.0.0.1:5173) on every restart; open that link, not the bare origin. Vite proxies /api to the local API so the browser talks to one local origin.

If port 4317 is taken (it is also the default OTLP gRPC port), set AGENT_SKILL_HUB_API_PORT=<free port> — both the dev API and the Vite proxy follow it.

Quality gates

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm verify:registry               # standalone builtin-registry sanity check
pnpm audit --prod --audit-level high
pnpm smoke:package                 # npm pack allowlist + clean npx install/run smoke

See CONTRIBUTING.md for fixture safety rules and the security-change checklist.

API (v1, main surfaces)

All routes below require the local session; state-changing routes also require the CSRF header.

Method	Path	Purpose
GET	/api/v1/health	liveness (no session required)
POST	/api/v1/session/exchange	one-time bootstrap → session cookie
GET	/api/v1/session	session status + CSRF token
GET	/api/v1/platforms	all platforms + deduplicated scan roots
POST/PATCH/DELETE	/api/v1/custom-platforms…	manage custom platforms
GET/POST/DELETE	/api/v1/projects…	manage approved project roots
GET/POST/DELETE	/api/v1/approved-roots…	manage approved extra roots
POST	/api/v1/scans	run and persist a scan
GET	/api/v1/skill-variants, /instances	inventory
GET	/api/v1/problems, /changes	diagnostics and snapshot diffs
POST	/api/v1/prompts/preview	calculate impact and generate a prompt

License

Apache-2.0. Registry data is derived from skills-manage — see NOTICE and THIRD_PARTY_NOTICES.md.