skillnote-doctor

---

The 8,000-character problem

Claude Code shares ~8,000 characters across every active skill description (docs). Past that limit, descriptions silently truncate. The system prompt forbids using skills that aren't listed in context, so truncated skills are both invisible and explicitly off-limits (#13343, #40121).

In practice, past ~15 active skills your skills stop working and you can't tell which ones. New teammates have no way to discover what skills the project depends on. Updating a shared skill means re-zipping and re-uploading for everyone. And private skills, like deploy procedures, compliance workflows, or internal API patterns, have nowhere safe to live.

SkillNote is a self-hosted registry that fixes that. Per-project collections scope which skills load. Live sync pushes browser edits to every connected agent within 60 seconds. Agents rate skills 1 to 5 after using them, so you finally have signal on what works. Your skills stay on your infrastructure. Your servers, your rules.

---

Quick start

npx skillnote start

Opens http://localhost:3000.

Requires Docker (running) and Node.js 20+. The CLI pulls the published images from GHCR, brings up the web + API + Postgres stack, waits for healthchecks, and opens the dashboard. About 30 seconds on a warm cache.

┌────────────────────────────────────────────┐
│  SkillNote ▸  the skill registry for AI    │
│  v0.5.2 · github.com/luna-prompts/skillnote│
└────────────────────────────────────────────┘
◇  Prerequisites ok
◇  Images pulled
◇  Containers running
◇  Services healthy

╭────────┬──────────────────────────────╮
│ Web UI │ http://localhost:3000        │
│ API    │ http://localhost:8082        │
╰────────┴──────────────────────────────╯

Docker Compose directly (no Node):

curl -fsSL https://raw.githubusercontent.com/luna-prompts/skillnote/cli-v0.5.4/deploy/docker-compose.yml -o docker-compose.yml
docker compose up -d

LAN-accessible for teammates on the same network:

SKILLNOTE_HOST=<your-lan-ip> docker compose up -d

Podman: npx skillnote start is Docker-only, but the Compose path and install.sh both work with podman compose (Podman 4+) or podman-compose.

Building from source (contributors):

git clone https://github.com/luna-prompts/skillnote.git
cd skillnote && ./install.sh

install.sh builds from local source instead of pulling published images. Auto-detects docker compose, podman compose, or podman-compose.

Lifecycle commands

npx skillnote start         # boot + open UI
npx skillnote stop          # halt; volumes preserved
npx skillnote restart       # stop + start
npx skillnote status        # health table (--json for scripts)
npx skillnote logs [svc]    # tail logs (-f to follow)
npx skillnote open          # open UI (--app for chromeless)
npx skillnote doctor        # 11 health checks
npx skillnote reset --confirm   # DESTRUCTIVE: drops all data

---

Wire up your AI agent

After the backend is running, install the plugin for your agent.

Claude Code

npx skillnote connect claude-code
source ~/.zshrc      # or ~/.bashrc

Runs the canonical /setup/agent script: registers the plugin marketplace in ~/.claude/settings.json, installs the SkillNote plugin into ~/.claude/plugins/, drops picker binaries in ~/.skillnote/bin/, and adds a shell wrapper. Run claude in any project, and the collection picker appears on first launch:

Pick a collection (it's saved to .skillnote.json) and your scoped skills load on every session.

Install SkillNote on my machine and wire it into this Claude Code session.

1. If http://localhost:8082/health doesn't respond, run:
   npx skillnote start --no-browser -d
2. If ~/.claude/plugins/skillnote/ doesn't exist, run:
   curl -sf http://localhost:8082/setup | bash
3. source ~/.zshrc
4. Confirm: claude --version, ls ~/.claude/plugins/skillnote/
5. Report what collection picker options you see when running `claude`.

OpenClaw

clawhub install skillnote

That's the whole install for the default localhost:8082 setup. If the backend isn't running, the skill auto-bootstraps it on first sync.

The skill ships sync.sh (60s catalog sync), log-watcher.py (analytics daemon), install-backend.sh (bootstrap), and an always-loaded SKILL.md that grafts a persistent <skillnote v1> block into ~/.openclaw/workspace/AGENTS.md.

For a non-default host:

export SKILLNOTE_BASE_URL="http://your-server:8082"
clawhub install skillnote
echo 'export SKILLNOTE_BASE_URL="http://your-server:8082"' >> ~/.zshrc

Or scripted (no clawhub):