USB MCP server

USB+ is now live: https://github.com/PeepSick/usbplus

USB has evolved into USB+, a unified platform for discovering, verifying, and installing AI capabilities across runtimes.

The new platform brings together the skill catalog, cross-runtime installation, and the Trust Layer — including usb secscan for skill contract verification and usb mcprobe for runtime observation of MCP servers.

Explore the live platform: https://usbplus.peepsicklabs.com/

Current version: v1.0.5

License: MIT

This repository represents the earlier USB implementation. For the latest documentation, CLI usage, catalog, API endpoints, and installation instructions, visit the official USB+ platform.

— PeepSick Labs

USB — Universal Skill Bridge

---

Quickstart

npm install -g @peepsick/usb-cli

usb install

USB detects every AI runtime installed on your machine and installs natively where it can — SKILL.md skills for Claude Code, a .mdc rule for Cursor. If it finds more than one, it asks which:

usb search postgres                  # find a skill
usb install intent-router            # install just one
usb install web-dev --target=claude  # install a preset into a specific runtime

Real output, not mocked up:

$ usb install web-dev --target=claude
✅ universal-skill-bridge-catalog v0.4.1 installed for target: claude (73 skills)
📦 Portable pack: ~/.ai-skills/universal-skill-bridge-catalog
🔌 Target files: ~/.claude/skills/universal-skill-bridge-catalog

Who is this for?

• ✅ Claude Code users — installs into ~/.claude/skills/ as loadable SKILL.md skills
• ✅ Cursor users — writes a .mdc rule into your project's .cursor/rules/
• ✅ AI teams — one shared skill catalog instead of copy-pasted prompts across repos
• ✅ MCP developers — USB speaks MCP natively (usb_search, usb_render_install, ...)
• ✅ Framework authors — @peepsick/usb-sdk gives you a typed Agent base class to build on

Why USB?

Every agent runtime invents its own way to package capabilities: Claude Code has skills, Cursor has rules, LangChain has tools, MCP has servers. There's no shared unit you can install once and reuse everywhere — so the same "audit this Dockerfile" or "harden this API" logic gets rewritten from scratch for every framework.

	Without USB	With USB
Distribution	Copy-paste prompts between repos	usb install <skill>
Portability	Rewritten per framework	One skill, 16 targets — 4 installed natively, 12 as a portable bundle
Discovery	Scattered gists and Notion docs	usb search, /api/skills, MCP tools
Trust	Blind curl | bash	Download → verify sha256 → read → run

Architecture

One skill definition. USB compiles it into every runtime's native format.

flowchart LR
    S[Skill] --> C{USB Compiler}
    C --> R1[Claude Code]
    C --> R2[Cursor]
    C --> R3[MCP]
    C --> R4[OpenAI]
    C --> R5[LangChain]
    C --> R6[LeoSis]
    C --> R7[+ 10 more]

You write it once. USB handles packaging, install paths, and sha256-verified delivery for all 16 targets.

Supported targets

Targets come in two tiers, and it's worth being precise about which is which.

Installs into the runtime — the runtime loads these on its own, no wiring:

claude · cursor · leosis · hermes

Emits a portable bundle — skill markdown plus a JSON adapter descriptor under ~/.ai-skills/adapters/<target>/, ready to feed into your own agent code:

openai · anthropic · langchain · mcp · openrouter · groq · mistral · ollama · lm-studio · vllm · generic

auto detects the runtime from your environment; generic falls back to plain markdown + a JSON manifest for anything unrecognized. Catalog: 529 skills — 9 hand-written core skills plus 65 engineering domains × 8 workflows (Audit, Plan, Build, Script, Diagnose, Harden, Explain, Tune).

Installing skills

npm (recommended):

npm install -g @peepsick/usb-cli

usb install intent-router     # a single skill
usb install web-dev           # a preset bundle
usb install --target=claude   # force a specific runtime target

Inspect-then-install — no npm/Node required, verifies the script before running it:

curl -fsSL https://usb.peepsicklabs.com/api/install?target=auto -o install.sh
EXPECTED=$(curl -fsSL https://usb.peepsicklabs.com/api/install-sha256?target=auto)
echo "$EXPECTED  install.sh" | sha256sum -c -   # mismatch = tampering or a stale CDN
less install.sh                                  # read what it actually does
bash install.sh

Trust the publisher and skip the review step: curl -fsSL https://usb.peepsicklabs.com/api/install?target=auto | bash

CLI reference

Command	Description
usb install [skill|preset]	Install a skill or preset bundle into the detected runtime
usb install --dry-run	Print the install script without executing it
usb install --target=<name>	Force a specific provider target
usb search <query>	Search the skill catalog
usb list	List every skill in the catalog
usb info <skill>	Show details for one skill
usb version	Print CLI/catalog version and the verify command for one-shot inspect+verify+run

usb install --dry-run                  # print the install script, do NOT execute
less <(usb install --dry-run web-dev)  # dry-run a preset and pipe to less

API

Endpoint	Purpose
/api/install?target=<name>	Render the install script for a target
/api/install-sha256?target=<name>	sha256 of the above, for verification
/api/skills	Browse the skill catalog
/api/audit/<slug>	Audit a single skill definition
/api/version	CLI/catalog version info
/api/health	Health check
/api/mcp	MCP server — HTTP JSON-RPC 2.0, tools: usb_search, usb_get_skill, usb_audit_skill, usb_render_install

curl -X POST https://usb.peepsicklabs.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Local development

git clone https://github.com/PeepSick/usb.git
cd usb
docker compose up -d

Open http://localhost:3000. Stack: Next.js 16, React 19, Tailwind v4, PostgreSQL + Drizzle ORM.

Contributing

USB is built in public and contributions are genuinely welcome — bug reports, docs fixes, new runtime adapters, new skill domains, or security hardening. You don't need to write code to help. Start with CONTRIBUTING.md; security issues go to info@peepsickai.com instead of the public tracker.

Before opening a PR that touches the CLI, installer, or this README, run bash scripts/verify-readme.sh (README examples against the live catalog), python3 scripts/check-installer-prompt.py (the interactive picker over a pty), python3 scripts/check-target-formats.py (the installed layout against what each runtime actually loads), python3 scripts/check-encoding.py (full-catalog encoding scan), and python3 scripts/check-links.py (broken internal links). CI runs all five on every PR and daily on a schedule.

---

Status

v0.4.6 (beta) — actively evolving. APIs, skill formats, and runtime adapters may change before v1.0.

Roadmap

• Skill marketplace
• Verified skill badges
• CI-based skill validation (schema/lint checks for new skill submissions)
• README-driven test harness — auto-extract and run labeled code blocks from this file in CI, instead of hand-syncing scripts/verify-readme.sh
• Versioned skill contracts
• Agent runtime certification layer

Acknowledgements & origin

Parts of the conceptual design of portable "AI skills" were inspired by emerging agent ecosystems — MCP-style tool servers, Claude Code agent workflows, and community skill catalogs such as mcpservers.org. That said, USB is a fully independent implementation built from scratch. No prompt template, skill record, or installer script was copied or scraped from any external catalog.

PeepSick Labs ecosystem

PeepSick Labs is an early-stage AI infrastructure studio, currently pre-incorporation, building in public.

Layer	Role
USB	Installs skills (skill layer for AI agents — this project)
Foundry	Builds agents (multi-agent orchestration & cognitive runtime)
Leosis	Powers intelligence (OpenAI-compatible LLM provider)

Contact

• Web: usb.peepsicklabs.com
• Email: info@peepsickai.com
• GitHub: github.com/PeepSick

License

MIT — free to use, modify, and redistribute, including commercially.

Building in public · Pre-incorporation · No legal entity formed yet · 2026