skillnote

# Quick orientation

You are running with the SkillNote skill loaded. Your responsibilities, in order:

1. **Setup** (Steps 1-6 below) — one-time per machine; ~30s if backend is already running, ~3 min if you need to install it
2. **Pick + apply** the right skills before responding to user tasks
3. **Log + rate** what worked after the task is done

Setup is **silent on every load after the first**. If `~/.openclaw/skills/skillnote/config.json` already has a working `host` and `~/.openclaw/skillnote-agents.md` exists, skip Steps 1-5 and stay quiet.

---

# How this skill got onto disk (recovery info)

This `SKILL.md` lives at `~/.openclaw/skills/skillnote/` and arrived via one of:

1. **clawhub** (recommended):
   ```bash
   clawhub install skillnote
   ```
2. **curl bundle installer** (works against any reachable SkillNote backend):
   ```bash
   curl -sf $SKILLNOTE_BASE_URL/setup/agent | bash -s -- --agent openclaw
   ```
   If `$SKILLNOTE_BASE_URL` isn't set, default to `http://localhost:8082`.
3. **Manual ZIP** — download `<host>/v1/openclaw-bundle.zip` and unzip into `~/.openclaw/skills/`. Air-gapped only.

If you find critical files missing from `~/.openclaw/skills/skillnote/` (e.g., `sync.sh`, `log-watcher.py`), use method 2 to reinstall — don't try to reconstruct missing files.

---

# Setup

## Step 1 — Resolve the backend URL

Layered lookup; stop at first match:
1. `$SKILLNOTE_BASE_URL` env var
2. `~/.openclaw/skillnote/config.json` → `host`
3. `~/.openclaw/skills/skillnote/config.json` → `host`
4. Default: `http://localhost:8082`

Reachability check: `GET <host>/v1/skills?limit=1`.

- **Reachable** → skip to Step 3 (persist).
- **Unreachable AND host == `http://localhost:8082`** → likely no backend on this machine yet. Continue to Step 2.
- **Unreachable AND host is custom** → user pointed at a specific server; do NOT auto-install. Tell the user it's down and stop:
  > SkillNote at `<host>` isn't reachable. Either the server is down, or the URL is wrong. I'll retry next session.

## Step 2 — Stand up the backend (only if Step 1 routed here)

Tell the user what's about to happen, then ask once:

> **SkillNote backend isn't running.** Run this in another terminal (takes ~3 min for the first Docker image pull):
>
> ```bash
> npx skillnote start
> ```
>
> When the CLI prints `Services healthy` and shows the URL table, come back and tell me "done" and I'll continue setup.

Wait for the user to confirm. Do not run the command yourself — `npx` pulling code from the registry and starting Docker containers from inside an `always: true` skill is the exact pattern static scanners flag as a "dropper." The user runs it themselves so the install action is theirs and auditable.

After the user confirms the backend is up:
- Re-run the reachability check from Step 1 (`GET <host>/v1/skills?limit=1`).
- If reachable → continue to Step 3.
- If still unreachable after 3 retries spaced 5s apart: ask the user to share the last 20 lines of `npx skillnote start` output; surface their error verbatim; stop.

### Customizing the install
If the user needs non-default ports, pass CLI flags to `skillnote start`:

| Need | Command |
| ---- | ------- |
| Port `8082` busy | `npx skillnote start --api-port 8182` |
| Port `3000` busy | `npx skillnote start --web-port 3001` |
| Bind to a LAN IP | `SKILLNOTE_HOST=<your-lan-ip> npx skillnote start` |

## Step 3 — Persist the resolved host (idempotent)

Strip trailing slashes. Write to `~/.openclaw/skills/skillnote/config.json`:

```json
{
  "host": "<resolved url>",
  "user_id": "<see below>"
}
```

For `user_id`: use your **real OpenClaw agent name** when known (e.g., `main`, `support-bot`, `dev-helper`). It's the identity that surfaces in analytics — multiple agents collapsing into one user_id loses signal. If you genuinely don't know your agent name, use `openclaw-main` as a fallback only.

## Step 4 — First sync (populates skills locally)

```bash
chmod +x ~/.openclaw/skills/skillnote/sync.sh && ~/.openclaw/skills/skillnote/sync.sh
```

Tell the user "Syncing skills from the registry…" — sync usually takes a couple seconds. The script:
- Fetches the catalog (`GET <host>/v1/skills`)
- Writes one `~/.openclaw/skills/sn-<slug>/SKILL.md` per skill (with rating-footer pre-baked)
- Spawns the `log-watcher.py` daemon (single-instance, pgrep-guarded)
- Writes `~/.openclaw/skillnote-agents.md` (the sidecar instructions file; idempotent; honors `{"grafted": false}` in config)

If sync.sh exits non-zero: capture the output, surface to the user, stop. Don't retry blindly.

## Step 5 — Wire the sidecar into AGENTS.md (one-time, user-confirmed)

sync.sh writes the `<skillnote v1>` instructions to a sidecar file: `~/.openclaw/skillnote-agents.md`. For OpenClaw to actually pick up those instructions, the user's own `~/.openclaw/workspace/AGENTS.md` needs to `@include` it. This is a **one-line edit, one time, with user confirmation** — not something sync.sh does itself.

First, check if it's already wired:

```bash
grep -c 'skillnote-agents.md' ~/.openclaw/workspace/AGENTS.md 2>/dev/null
```

| Result | Action |
|---|---|
| `1` | ✅ already wired; continue to Step 6 |
| `0` or file missing | Ask the user (once, explicit consent): "I need to add one line to your `~/.openclaw/workspace/AGENTS.md` so OpenClaw picks up the SkillNote instructions: `@include ~/.openclaw/skillnote-agents.md`. OK to add it?" |
| `≥2` | Already wired multiple times — tell the user; don't auto-fix |

**On user `Y`** — append the line:
```bash
mkdir -p ~/.openclaw/workspace
echo '@include ~/.openclaw/skillnote-agents.md' >> ~/.openclaw/workspace/AGENTS.md
```

**On user `n`** — write `{"grafted": false}` to `~/.openclaw/skills/skillnote/config.json` so sync.sh stops regenerating the sidecar, and tell them:
> No problem. SkillNote will sync skills but won't inject instructions into your agent. Re-run `~/.openclaw/skills/skillnote/sync.sh` and add the `@include` line later if you change your mind.

The side