luna-prompts/skillnote/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 ``

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

1. 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:

Step 3 — Persist the resolved host (idempotent)

Strip trailing slashes. Write to ~/.openclaw/skills/skillnote/config.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)

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:

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

On user `Y` — append the line:

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 sidecar content is sync.sh's source of truth — don't paraphrase or copy it inline. If you need to inspect it, read ~/.openclaw/skillnote-agents.md.

Step 6 — Done

Say once on first setup; never again unless re-installing:

SkillNote connected ✓ Registry at <host>.

N skills synced to ~/.openclaw/skills/sn-*/ — I'll pick the relevant ones before each task and log what helped.

Ask me "what skills have you been using?" anytime, or visit <host> to see analytics in the web UI.

(Replace N with ls ~/.openclaw/skills/ | grep -c "^sn-".)

On every subsequent session: complete silence. Just check that ~/.openclaw/skillnote-agents.md exists and AGENTS.md still has the @include line; if not, surface to the user (don't auto-fix the @include — it requires their consent).

How to pick which skills to apply (do this BEFORE responding to a task)

Before responding to any non-trivial task (anything beyond small talk), you have all synced skills available at ~/.openclaw/skills/sn-*/SKILL.md.

v1 picking method (works well up to ~15-20 skills)

1. Read just the frontmatter `description` field of every sn-*/SKILL.md (cheap — ~200 chars each).
2. Pick at most 3 whose description language overlaps with the task language. Be conservative: 0 is a valid answer.
3. Read the full `SKILL.md` of those 1-3 selected skills.
4. Apply their guidance to the task.
5. Hard cap: never load more than 5 sn-* SKILL.md files into context for a single task. If 5+ seem relevant, you've over-matched — re-read the task and tighten.

Edge cases

How to log usage (after task completion)

POST to <host>/v1/openclaw/usage. Use slugs (the sn-* directory name without the sn- prefix), not UUIDs:

{
  "agent_name": "<your real agent name>",
  "task_summary": "<paraphrase — never the raw user message>",
  "skill_slugs": ["error-handling", "git-commit-convention"],
  "outcome": "completed | failed | abandoned | unknown",
  "channel": "<see Channel detection below>"
}

The response includes `id` — capture it. You'll need it as linked_usage_id when you also rate the skill.

Picking the right outcome honestly

This field is the only signal we have for whether skills are actually working. Be honest — defaulting everything to completed makes the registry useless.

• `completed` — skill applied AND produced the intended result
• `failed` — skill applied BUT didn't help (wrong result, error, or trigger criteria didn't match the actual situation). Diagnose in task_summary: "Tried sn-X for Y but its trigger criteria didn't match the actual exception type."
• `abandoned` — considered the skill, started applying, didn't finish (timeout, scope changed mid-task, switched skills partway through)
• `unknown` — only when truly uncertain (no clear signal whether the user accepted the answer). Bias toward completed or failed — unknown is uninformative

Channel detection

Infer channel from where the task came in. Use these slug-style values (lowercase, slash-separated):

Channel matters for analytics breakdown — the team will eventually want to ask "which skills do I use most in #support vs #eng?".

Don't post if

• No skill was applied (don't post empty events — they pollute analytics)
• Task was pure small talk ("hi", "thanks")

How to reflect on a skill (rate or comment)

POST to <host>/v1/skills/<slug>/comments. Always include `linked_usage_id` (the id from the /v1/openclaw/usage POST you just made for this same task) so the comment correlates to specific work:

{
  "author": "<your real agent name>",
  "author_type": "agent",
  "comment_type": "agent_success_note",
  "rating": 5,
  "linked_usage_id": "<id from /v1/openclaw/usage response>",
  "body": "<one paragraph — no user info, no raw messages>"
}

If you genuinely don't have a linked_usage_id, omit the field — never invent one.

Picking the right comment_type

Self-restraint

• At most one comment per skill per day (the backend doesn't enforce this; you do)
• Only comment when you have specific signal — vague "nice skill" or "didn't really use it" comments add noise

How to show activity (when user asks)

When the user asks "what skills have you been using?" or similar, fetch:

GET <host>/v1/me/activity?period=7d