luna-prompts/skillnote

S K I L L N O T E

The open-source skill registry for AI coding agents.

Self-host your team’s SKILL.md library. Version it, scope it, and ship it to Claude Code and OpenClaw from one CLI.

Quick start  ·  Why  ·  Features  ·  Agents  ·  Architecture  ·  FAQ  ·  Discord

---

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 .

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        │
╰────────┴──────────────────────────────╯

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.

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 `` block into ~/.openclaw/workspace/AGENTS.md.

claude.ai (web app)

A small Chrome extension syncs your SkillNote collections to your claude.ai account as plugin groups — skills you publish in SkillNote appear in claude.ai’s Customize → Plugins, and claude.ai-authored skills import back. No copy-paste either way. The extension opens as a side panel beside claude.ai, matches its light/dark theme, and shows how often your skills actually get used.

Install (Chrome Web Store listing pending review — load unpacked for now):

cd extensions/claude-ai && npm install && npm run build
# chrome://extensions → enable Developer mode → Load unpacked → select dist/

Connect — everything happens in the panel, no separate tab:

1. Click the SkillNote toolbar icon to open the side panel.
2. Enter your SkillNote URL — the same address you open in your browser (e.g. http://localhost:3000) — and click Connect. (Chrome asks once for permission to reach that address.)
3. In SkillNote, the notifications bell (top-right) shows the pairing request — confirm the code matches and click Approve.
4. Choose what to sync: on any collection in SkillNote, open Sync ▾ → claude.ai and flip the toggle. Those skills appear in claude.ai within seconds (as the plugin group SkillNote: ), and re-sync automatically on every change.

You stay in control of what leaves SkillNote: the Sync menu is per-collection, so dev-only or sensitive collections simply stay off. Toggle one on and it’s live on claude.ai; toggle it off and the connector retires that plugin group.

Sync runs automatically while you’re signed in to claude.ai. The extension reads your claude.ai session cookies locally only — they never leave your machine, and it only ever talks to claude.ai and the SkillNote URL you entered.

Full walkthrough: docs/claude-ai-user-guide.md · architecture: docs/claude-ai-integration.md · admin runbook: docs/claude-ai-admin-runbook.md · privacy: extensions/claude-ai/PRIVACY.md.

Cursor, Codex, Antigravity, and OpenHands are on the roadmap. Open an issue if you want to help build an adapter.

---

Features

Per-project collections

Claude Code shares ~8,000 characters across every active skill description; past ~15 skills, descriptions silently truncate and truncated skills won’t trigger. Collections scope which skills load per project: frontend project gets React + testing patterns, API project gets error handling + deploy conventions. Same registry, different active sets, no context wasted.

If your folder name matches a collection, the plugin recommends it automatically.

Import from any GitHub repo

The community has published thousands of SKILL.md files since Anthropic released the format. Paste a GitHub URL, shorthand (garrytan/gstack), a tree URL to a subfolder, or a Claude Code marketplace manifest (anthropic.json). SkillNote shallow-clones the repo, scans every SKILL.md, validates frontmatter, and opens a workspace where you pick exactly what to install.

Some popular registries to try:

• anthropics/skills: Anthropic’s official Agent Skills repository
• ComposioHQ/awesome-claude-skills: 800+ community skills, the largest curated set
• alirezarezvani/claude-skills: 600+ skills for Claude Code, Codex, Gemini CLI, Cursor, and more
• garrytan/gstack: Garry Tan’s 50+ opinionated YC-flavored tools (CEO, Designer, Eng Manager, etc.)
• obra/superpowers: Jesse Vincent’s agentic skills framework

Live sync, every agent

Edit a skill in the browser and every running Claude Code or OpenClaw session picks up the change within 60 seconds. Claude Code re-syncs on every prompt and hot-reloads SKILL.md mid-session. OpenClaw’s sync.sh runs on a 60s throttle. One person updates a skill, everyone gets it. New teammates run the setup command once and inherit every skill the team has built.

Agent reviews

Most skill setups are fire-and-forget. SkillNote closes the loop. After applying a skill, the agent rates it 1-5 and describes what it did. OpenClaw additionally posts a linked_usage_id correlating each rating to the specific task that produced it. You see which skills are actually being used, which ones break, and how performance changes across versions.

Version history

Every save creates a snapshot. Browse, compare, and restore any version in one click. Published versions use semver and ship as checksummed ZIP bundles.

Skill push

When Claude Code notices you correct the same thing three times (“use pnpm, not npm”), it offers to turn it into a skill. The skill is pushed to SkillNote and syncs to every connected agent in 60 seconds. What one person teaches once becomes a skill everyone has.

---

Agent support

Want to help build an adapter? Open an issue or join us on Discord.

---

Architecture

┌──────────────────────────────────────────────────────┐
│                                                      │
│   SkillNote Server (Docker)                          │
│                                                      │
│   Web UI        REST API       PostgreSQL            │
│   :3000         :8082          (storage + notify)    │
│                                                      │
└────────────────────┬─────────────────────────────────┘
                     │
                  REST API
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
┌────────────────────┐   ┌────────────────────┐
│ Claude Code plugin │   │  OpenClaw skill    │
│                    │   │                    │
│ ~/.claude/         │   │ ~/.openclaw/       │
│   plugins/         │   │   skills/          │
│   skillnote/       │   │   skillnote/       │
│                    │   │                    │
│ 6 lifecycle hooks  │   │ sync.sh + daemon   │
│ Per-project picker │   │ AGENTS.md graft    │
└────────────────────┘   └────────────────────┘

SkillNote uses each agent’s native skill system. For Claude Code that’s hooks plus plugin format, with SessionStart, UserPromptSubmit, PostToolUse, PostCompact, SubagentStart, and Stop. Only SessionStart blocks (for ~1 second to sync); every other hook runs async, so you never wait for SkillNote.

For OpenClaw it’s a clawhub-installable bundle with sync.sh (catalog), log-watcher.py (analytics), and an AGENTS.md graft that keeps the agent consulting the registry on every task.

Skills are written as local SKILL.md files, not piped through a network abstraction. That means every Claude Code frontmatter feature, including allowed-tools, context: fork, effort, and model, works natively. These features only work with on-disk SKILL.md files, which is why SkillNote syncs to disk instead of serving skills over a network protocol.

For the full HLD see docs/openclaw-hld.md.

---

SKILL.md format

---
name: pdf-extractor
description: Extract text and tables from PDF files. Use when the user mentions PDFs or scanned documents.
collections: [data, documents]
allowed-tools: Read Write Bash(pdftotext *)
context: fork
---

# PDF Extractor

When the user provides a PDF file:
1. Use `pdftotext` to extract raw text
2. Identify tables and format them as markdown
3. Preserve headings and document structure

---

Security & deployment

SkillNote is built for trusted environments: a developer’s laptop, a team VM on a private network, or a self-hosted server behind a VPN. Out of the box it has no authentication on the web UI or API; anything that can reach :3000 and :8082 can read and write skills.

• Local-only (default): npx skillnote start binds to localhost. Safe.
• LAN-only: set SKILLNOTE_HOST= to expose to teammates on the same network. Assumes the LAN is trusted.
• Internet-exposed: never bind :3000 or :8082 directly to a public IP. Put it behind a reverse proxy (Caddy, Nginx, Traefik) with basic auth, OAuth, or a Tailscale/Cloudflare Tunnel.
• Marketplace imports: every install writes SKILL.md files that your agent will read. Review the workspace preview before importing from unfamiliar sources.

Auth on the API is on the roadmap. Until then, treat reachability as the access boundary.

---

Tech stack

---

FAQ

---

Contributing

1. Fork the repo
2. git checkout -b feat/my-feature
3. Commit with Conventional Commits
4. Push and open a PR

CLAUDE.md has the architectural patterns and conventions. docs/ has design docs and HLDs.

Active development happens on Discord.

---

Contributors

---

License

MIT © Luna Prompts

Built by Luna Prompts