# skillnote-doctor

Adopt this skill: https://proskills.md/skills/other/luna-prompts-skillnote-plugin-openclaw-skillnote-doctor

Page: https://proskills.md/skills/other/luna-prompts-skillnote-plugin-openclaw-skillnote-doctor
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugin-openclaw/skillnote-doctor/SKILL.md
size: 3278
sha: 7c2737657e19901cf8ae9e5f4b4860efcd91dd38
upstream: https://github.com/luna-prompts/skillnote/blob/master/plugin-openclaw/skillnote-doctor/SKILL.md

````text
---
name: skillnote-doctor
description: "A diagnostic tool for OpenClaw agents -- checks skill registry connectivity, AGENTS.md setup, config file validity, and installed skill health. Use when your setup seems broken, skills aren't loading, or you want to audit your agent's configuration."
version: "1.0.1"
metadata: {"openclaw": {"emoji": "🩺", "triggers": ["diagnose", "check setup", "why isn't", "debug", "broken", "not working"]}}
---

# SkillNote Doctor

Diagnose your SkillNote + OpenClaw integration in 6 checks. Run every check even if an earlier one fails — the user needs the full picture. Report ✓ pass or ✗ fail with specific remediation for each.

## Check 1 — clawhub binary

Run: `which clawhub`

- ✓ Pass: binary found
- ✗ Fail: `clawhub not found. Install from https://clawhub.ai or run: npm install -g clawhub`

## Check 2 — SkillNote config

Read `~/.openclaw/skills/skillnote/config.json`.

- ✓ Pass: file exists, valid JSON, `host` is non-empty
- ✗ Fail (missing): `Config not found. SkillNote is not installed. Install with: clawhub install skillnote && clawhub install skillnote-resolver`
- ✗ Fail (invalid JSON): `Config is malformed. Delete ~/.openclaw/skills/skillnote/config.json and re-run skillnote setup.`
- ✗ Fail (empty host): `Config exists but host is empty. Ask your agent to re-setup skillnote.`

## Check 3 — Registry reachability

GET `<host>/v1/skills?limit=1`

- ✓ Pass: HTTP 200
- ✗ Fail (timeout/refused): `SkillNote at <host> is unreachable. Verify the URL and that your instance is running. Self-host guide: https://github.com/luna-prompts/skillnote`
- ✗ Fail (non-200): `Unexpected HTTP <N>. Check SkillNote server logs.`

## Check 4 — AGENTS.md marker

Read `~/.openclaw/workspace/AGENTS.md`. Check for exact string `<skillnote v1>`.

- ✓ Pass: marker found
- ✗ Fail: `AGENTS.md marker missing. Ask your agent: "re-graft skillnote into AGENTS.md" — or reinstall: clawhub install skillnote`

## Check 5 — skillnote-resolver installed

Check `~/.openclaw/skills/skillnote-resolver/SKILL.md` exists.

- ✓ Pass: file found
- ✗ Fail: `skillnote-resolver not found. Install with: clawhub install skillnote-resolver`

## Check 6 — resolver endpoint

POST `<host>/v1/openclaw/context-bundle` with body `{"task_summary": "doctor health check", "max_skills": 1}`

- ✓ Pass: HTTP 200, `skills` array present
- ✗ Fail: `Context bundle endpoint unavailable. Check SkillNote server version — endpoint requires v0.3.0+`

---

## Summary

After all checks report:

```
SkillNote health: X/6 checks passed
```

If all 6 pass:
> Your SkillNote integration looks healthy. If you're still seeing issues, check https://github.com/luna-prompts/skillnote/issues

If Check 2 fails with "Config not found" (SkillNote not installed at all):
> SkillNote not detected. Install with:
> ```
> clawhub install skillnote
> clawhub install skillnote-resolver
> ```
> Then follow the 5-step setup that runs automatically on first load.

---

# Hard rules

- Never modify any file during diagnosis — read-only.
- Never POST to any endpoint other than `/v1/openclaw/context-bundle`.
- Run all 6 checks regardless of earlier failures.
- Never guess or invent the host URL — read it strictly from config.json.
````

## File: README.md
upstream: https://github.com/luna-prompts/skillnote/blob/master/README.md

````text
<p align="center">
  <img src="public/logo.svg" width="88" height="88" alt="SkillNote" />
</p>

<h1 align="center">S K I L L N O T E</h1>

<p align="center">
  <strong>The open-source skill registry for AI coding agents.</strong>
  <br />
  Self-host your team's <code>SKILL.md</code> library. Version it, scope it, and ship it to Claude Code and OpenClaw from one CLI.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/skillnote"><img src="https://img.shields.io/npm/v/skillnote.svg?label=npm&color=cb3837&logo=npm" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/skillnote"><img src="https://img.shields.io/npm/dt/skillnote.svg?label=downloads&color=brightgreen" alt="npm total downloads" /></a>
  <a href="https://github.com/luna-prompts/skillnote/pkgs/container/skillnote-api"><img src="https://img.shields.io/badge/ghcr.io-multi--arch-2496ED?logo=docker&logoColor=white" alt="Docker images on GHCR" /></a>
  <a href="https://clawhub.ai/latentloop07/skillnote"><img src="https://img.shields.io/badge/clawhub-skillnote-F97316" alt="On clawhub" /></a>
  <a href="https://github.com/luna-prompts/skillnote/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
  <a href="https://discord.gg/GazU4amU6H"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://github.com/luna-prompts/skillnote"><img src="https://img.shields.io/github/stars/luna-prompts/skillnote?style=social" alt="Stars" /></a>
</p>

<p align="center">
  <a href="#quick-start"><strong>Quick start</strong></a> &nbsp;·&nbsp;
  <a href="#the-8000-character-problem">Why</a> &nbsp;·&nbsp;
  <a href="#features">Features</a> &nbsp;·&nbsp;
  <a href="#agent-support">Agents</a> &nbsp;·&nbsp;
  <a href="#architecture">Architecture</a> &nbsp;·&nbsp;
  <a href="#faq">FAQ</a> &nbsp;·&nbsp;
  <a href="https://discord.gg/GazU4amU6H">Discord</a>
</p>

<br />

<p align="center">
  <img src="docs/screenshots/connect-browse.png" width="100%" alt="SkillNote Connect page browsing Claude Code, OpenClaw, and claude.ai as official agent integrations, each shown with its canonical mark" />
</p>

---

## The 8,000-character problem

Claude Code shares **~8,000 characters** across every active skill description ([docs](https://docs.anthropic.com/en/docs/claude-code/skills)). 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](https://github.com/anthropics/claude-code/issues/13343), [#40121](https://github.com/anthropics/claude-code/issues/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.

| Without SkillNote | With SkillNote |
| --- | --- |
| Skills truncate past ~15 active | Collections scope to 15 per project |
| `~/.claude/skills/` per laptop | One registry, every agent |
| Re-zip + re-upload to share an edit | Edit in browser, every session picks it up in 60s |
| No signal on what actually works | Agents rate every skill they use, 1-5 + comment |
| Private skills have nowhere safe | Self-hosted; never leaves your network |

---

## Quick start

```bash
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.

```text
┌────────────────────────────────────────────┐
│  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        │
╰────────┴──────────────────────────────╯
```

<details>
<summary><b>Other ways to install</b></summary>

**Docker Compose directly** (no Node):

```bash
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:

```bash
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):

```bash
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`.

</details>

### Lifecycle commands

```text
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

```bash
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:

<p align="center">
  <img src="docs/terminal/picker4.png" width="640" alt="SkillNote collection picker in Claude Code terminal showing Conventions, DevOps, and Frontend collections" />
</p>

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

<details>
<summary><i>Or, paste this prompt into a fresh Claude Code session</i></summary>

<br />

```text
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`.
```

</details>

### OpenClaw

```bash
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`.

<details>
<summary><i>Non-default host or alternative install</i></summary>

<br />

For a non-default host:

```bash
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):

```b
````
