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 the AGENTS.md graft is in place, 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):

   clawhub install skillnote
   

2. curl bundle installer (works against any reachable SkillNote backend):

   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, install-backend.sh), 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. I can install it now (clones the repo and runs docker compose up; ~3 min for the first build). Proceed? [Y/n]

On n — output the manual instructions and STOP setup:

No problem. When you're ready, run one of:

bash ~/.openclaw/skills/skillnote/install-backend.sh
# or
git clone https://github.com/luna-prompts/skillnote.git && cd skillnote && ./install.sh

Then restart this session.

On Y — run this single command and stream stdout/stderr back to the user so they see Docker build progress (don't background it; don't silence it; let them see what's happening for the ~3 min build):

bash ~/.openclaw/skills/skillnote/install-backend.sh

The script handles: prereq check (git, curl, docker-or-podman), clone to $HOME/skillnote, ./install.sh (Docker build + compose up), poll /health until ready (60s timeout), print URLs.

If install-backend.sh is missing

Curl the canonical version from GitHub raw:

curl -sfL https://raw.githubusercontent.com/luna-prompts/skillnote/master/plugin-openclaw/skillnote/install-backend.sh | bash

If even that fails (no network), instruct the user to clone the repo manually:

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

Customizing

Set env vars BEFORE invoking install-backend.sh:

If install-backend.sh exits non-zero

Capture the last 20 lines of output and show them verbatim. Common patterns:

After success, the URLs appear (http://localhost:3000, http://localhost:8082). Continue to Step 3.

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 (PID-guarded; won't double-launch)
• Appends the <skillnote v1> block to ~/.openclaw/workspace/AGENTS.md (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 — Verify the AGENTS.md graft (sync.sh did it; you just check)

grep -c '<skillnote v1>' ~/.openclaw/workspace/AGENTS.md

Honoring an opt-out

If the user told you in this session "don't touch AGENTS.md" or "skip the graft" (and only if they explicitly said so — don't invent the question), write {"grafted": false} to ~/.openclaw/skills/skillnote/config.json BEFORE running sync.sh in Step 4. sync.sh checks that flag and skips the graft.

The block sync.sh appends is the source of truth — don't paraphrase or modify it. If you need to inspect it, read ~/.openclaw/skills/skillnote/sync.sh.

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 the marker is in AGENTS.md; if not, sync.sh re-grafts on next run.

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

Render in natural prose: top skills by usage, ratings you left, any patterns you noticed. Don't dump raw JSON — summarize.

Daily self-update check

sync.sh does this automatically every 24 hours (tracked via ~/.openclaw/skills/skillnote/.last-version-check):

1. GET <host>/v1/openclaw-skill → returns {version, skill}
2. Compare to ~/.openclaw/skills/skillnote/VERSION
3. If newer:
   • If clawhub is on PATH: clawhub install skillnote@<ver>
   • Otherwise: overwrite SKILL.md + VERSION inline from the response

You don't need to do anything for self-updates. If a notification appears that the skill was updated, prefer to re-read SKILL.md before continuing — the steps may have changed.

Uninstall

When the user says "remove skillnote" or "uninstall skillnote":

1. Stop the daemon:

   PID=$(cat ~/.openclaw/skills/skillnote/.log-watcher.pid 2>/dev/null) && kill "$PID" 2>/dev/null
   

2. Remove the AGENTS.md graft (the <skillnote v1>...</skillnote v1> block) from ~/.openclaw/workspace/AGENTS.md.
3. Remove the skill files:
   • If clawhub is on PATH: clawhub uninstall skillnote
   • Otherwise: rm -rf ~/.openclaw/skills/skillnote
4. Optional (frees disk; loses synced skills): rm -rf ~/.openclaw/skills/sn-*
5. Confirm to the user:

   SkillNote removed. AGENTS.md restored, daemon stopped, skill files deleted.

The SkillNote backend itself stays running — it's separate from this skill. To stop it too: cd <skillnote-repo> && docker compose down.

Hard rules

• Use skill_slugs, not skill_ids. Synced skills don't have id: in their frontmatter; the slug is the sn-* directory name without the sn- prefix.
• Never log raw user messages or PII. Always paraphrase task summaries.
• Never log secrets, tokens, or credentials — even if the user pasted them.
• Don't post usage events when no skill was applied. Empty events pollute analytics.
• Don't comment more than once per skill per day (self-enforced — backend doesn't check).
• Don't mention SkillNote on every reply. Only when relevant or when the user asks about activity.
• Don't mutate config.json after setup. If the host needs to change, ask the user to say "re-setup skillnote" so they consent explicitly.
• Don't graft AGENTS.md yourself. sync.sh handles it. If you find the marker missing, re-run sync.sh — don't use your file-edit tool.