SkillNote
Type: ../types/agent-memory-system-review.md · Status: current
SkillNote is Luna Prompts' self-hosted skill registry and distribution surface for AI coding agents. It stores reusable SKILL.md procedures in a FastAPI/PostgreSQL service, exposes them through a Next.js UI, publishes release ZIPs, syncs selected collections into Claude Code and OpenClaw skill directories, and can project registry skills as live MCP tools. Its strongest design contribution is separating skill content, registry metadata, release bundles, telemetry, and runtime projections into distinct artifacts with different behavioral authority.
Repository: https://github.com/luna-prompts/skillnote
Reviewed commit: 3a77acdb9ddbff13d9721c4871cf0f940b151e9b
Last checked: 2026-05-16
Core Ideas
The canonical registry is Postgres rows, not files. skills stores name, slug, description, content_md, collections, extra_frontmatter, source provenance, and fork flags; collections is a separate table but each skill also carries a PostgreSQL array of collection names (backend/app/db/models/skill.py, backend/app/db/models/collection.py). The storage substrate is therefore a service database plus a local bundle directory, with derived copies written into agent-specific filesystem locations. The skill body is a system-definition artifact when an agent consumes it as instructions; the same row's source metadata is a knowledge artifact when used as provenance.
SKILL.md is parsed, synthesized, and mirrored at several boundaries. Imports shallow-clone GitHub sources, scan SKILL.md files, validate frontmatter, store the body and provenance, and mark local edits as forked from upstream (backend/app/services/imports/inspector.py, backend/app/services/imports/importer.py). Claude Code sync reconstructs PROJECT/.claude/skills/skillnote-<slug>/SKILL.md from registry fields, preserving extra_frontmatter; OpenClaw sync writes ~/.openclaw/skills/sn-<slug>/SKILL.md with a rating footer (plugin/hooks-handlers/sync.sh, plugin-openclaw/skillnote/sync.sh). These mirrored files are compiled views, not the registry source of truth.
Content versions and release versions are separate tracks. Browser/API edits create integer skill_content_versions snapshots of title, description, body, and collections, and restore operations can apply an old content snapshot back to the live skill (backend/app/db/models/skill_content_version.py, backend/app/api/skills.py). Separately, /v1/publish accepts semver ZIP bundles, validates archive safety and SKILL.md frontmatter, stores the ZIP under skills/<slug>/<version>.zip, records checksum/status/channel rows in skill_versions, and /download verifies the stored checksum before serving the bundle (backend/app/api/publish.py, backend/app/db/models/skill_version.py, backend/app/api/downloads.py).
The CLI has both product lifecycle and legacy bundle-install surfaces. npx skillnote start manages the Docker Compose web/API/Postgres stack, while connect claude-code and connect openclaw fetch backend-served install scripts for those two supported live integrations (cli/README.md, cli/src/commands/connect.ts, backend/app/api/setup.py). The older add/update commands still download active semver bundles, verify checksums, extract safely, and copy to detected adapters for Claude, Cursor, Codex, OpenClaw, OpenHands, or .agents/skills universal fallback (cli/src/commands/add.ts, cli/src/commands/update.ts, cli/src/agents/index.ts).
MCP projection is live and invalidated through PostgreSQL NOTIFY. backend/mcp_server.py turns each skill row into a FastMCP tool named by slug; calling the tool returns the skill body plus an optional complete_skill instruction, and complete_skill writes a rating row (backend/mcp_server.py). REST skill create/update/delete routes send pg_notify('skillnote_skills_changed', ...), the MCP server LISTENs on that channel, and connected MCP sessions receive notifications/tools/list_changed so clients can refresh their tool list (backend/app/api/skills.py, backend/app/api/settings.py, backend/mcp_server.py). The file says URL query filtering exists, but the provider implementation actually filters by SKILLNOTE_MCP_FILTER_COLLECTIONS, not by parsing the request URL.
Collections are activation scope, not access control. Collection names control which skills are synced or listed and are capped at 15 skills to fit Claude Code's skill-description budget (backend/app/validators/skill_validator.py, plugin/skills/collection/SKILL.md). They are a routing and context-budget mechanism. They are not a governance boundary: auth tables were explicitly dropped, API routes do not require tokens, and the current login command only stores a host URL (backend/alembic/versions/0004_drop_auth_tables.py, cli/src/commands/login.ts, cli/src/config/index.ts).
Frontend local state is a shadow and offline fallback. The Next.js client stores skillnote:skills in localStorage, stamps API-synced rows with _syncedAt, keeps genuinely local offline-created skills, drops stale API ghosts, and falls back to local data when the API is unreachable (src/lib/skills-store.ts). The service worker explicitly does no offline caching, so this is local UI resilience, not a full offline-first sync engine (public/sw.js). Offline edits can survive locally, but the reviewed code does not show a durable replay queue that reconciles them back to Postgres.
Telemetry affects dashboards and resolver context, not skill learning. Claude Code hooks post skill call events; OpenClaw sync launches a log watcher that notices reads of sn-*/SKILL.md; OpenClaw agents can submit task summaries, outcomes, and linked comments; ratings are stored in both skill_ratings and comments depending on surface (plugin/hooks-handlers/track-usage.sh, plugin-openclaw/skillnote/log-watcher.py, backend/app/api/hooks.py, backend/app/api/comments.py, backend/app/api/analytics.py). OpenClaw's context-bundle sorts candidates by recent usage and ratings, but the module states the agent-side resolver does relevance selection, and the code does not mine traces or ratings into durable skill edits or learned routing policy (backend/app/api/openclaw.py).
Comparison with Our System
| Dimension | SkillNote | Commonplace |
|---|---|---|
| Primary retained artifact | Skill rows and projected SKILL.md files |
Typed markdown notes, reviews, instructions, references, sources, and generated indexes |
| Canonical storage substrate | PostgreSQL plus local bundle files | Git-tracked files, schemas, scripts, indexes, and reports |
| Behavior-shaping surface | Agent skill directories, MCP tools, install scripts, sync hooks, generated sidecars | Type specs, collection rules, skills, validation commands, review gates, indexes |
| Versioning | Integer content snapshots plus semver ZIP release rows | Git history plus replacement archives, generated indexes, and validation/report artifacts |
| Activation | Collections, Claude hooks, OpenClaw sidecar, MCP tool list, local copied skills | rg, indexes, authored links, skills, instructions, type contracts |
| Feedback | Call events, usage events, comments, ratings, dashboards, OpenClaw context metadata | Review warnings, validation output, connect reports, manual promotion decisions |
| Trace-derived learning | Telemetry is retained and ranked, but not distilled into durable behavior-changing artifacts | Treated as a requirement only when traces become reviewed notes, instructions, skills, tests, or policy |
The strongest alignment is that both systems treat skills as system-definition artifacts: retained prose and symbolic frontmatter that can alter future agent behavior through discovery, routing, instruction, and tool permissions. SkillNote is more productized around the distribution problem. Commonplace is more explicit about artifact contracts, lineage, review state, and collection semantics.
The main divergence is source-of-truth choice. SkillNote makes Postgres the canonical registry and emits files for agents. That makes UI editing, dashboards, import status, and live MCP projection straightforward, but it gives up the inspectable file tree as the primary governance substrate. Commonplace's files-first model makes review, diffs, archival replacement, and local conventions cheap, but it has less polished packaging for shipping a scoped skill set into several agent runtimes.
SkillNote's authority model is pragmatic but implicit. A registry row's description is a routing pointer, content_md is instruction, extra_frontmatter can become execution policy in Claude Code, ZIP metadata is a release contract, skill_call_events and skill_ratings are telemetry knowledge artifacts, and OpenClaw sidecars are system-definition artifacts because they instruct every later task to sync, read, log, and rate skills. The code separates these substrates, but it does not name the authority differences as explicitly as commonplace does.
The feedback loop should be read narrowly. SkillNote records traces and gives agents prompts to rate skills after use. Those traces become dashboard evidence and weak ranking signals in context-bundle; they do not become new skills, revised skill bodies, validation gates, or policy updates without a human or agent manually invoking skill-push. This review therefore does not classify SkillNote as trace-derived learning.
Read-back: both — agents can pull skills through MCP tools or mirrored files, while synced collections and sidecars load skill discovery and usage instructions.
Borrowable Ideas
Separate live content versions from distributable release bundles. Ready to borrow if commonplace grows a skill publishing surface. The split between editable content snapshots and checksummed semver ZIP releases is cleaner than overloading one version number for both authoring history and installable artifacts.
Use LISTEN/NOTIFY for live tool-list invalidation. Worth borrowing for a service-backed projection layer. If commonplace ever exposes typed notes or skills through MCP, database or file-watcher invalidation should push "tool list changed" rather than relying only on reconnects.
Treat collection scope as context-budget control. Already aligned. SkillNote's hard 15-skill cap per collection is a practical response to always-loaded skill descriptions. Commonplace should keep any agent-facing skill bundles small enough that discovery metadata remains reliable.
Make derived agent files visibly disposable. SkillNote's sync hooks write manifests and delete only managed skillnote-* or sn-* directories. That pattern is useful: compiled agent-facing views should be clearly prefixed, manifest-tracked, and safe to regenerate.
Expose feedback without pretending it is learning. SkillNote's ratings and comments are useful evidence even without automatic distillation. Commonplace can borrow the humility: store call evidence and outcomes first, then promote only when a reviewable mechanism exists.
Serve installer bundles with host-specific substitution carefully. The setup endpoints bake API/web/MCP URLs into Claude and OpenClaw bundles, sanitize host input, and reject symlink/path-traversal bundle entries. This is a useful packaging pattern, but it should remain paired with explicit governance and authentication if used beyond local/self-hosted environments.
Curiosity Pass
The README's "agents rate every skill" story is broader than the implemented learning loop. Ratings exist, complete_skill exists, and OpenClaw comments can link to usage events, but the durable skill body changes only through ordinary create/update paths or explicit skill-push flows.
There are three distribution surfaces with different semantics. Live sync writes current registry content into agent skill directories. MCP projects current rows as tools. Semver bundles distribute ZIP releases through skill_versions. These are not interchangeable; each has different freshness, installation, and checksum guarantees.
OpenClaw has the richer governance-adjacent surface. Its sidecar instructs agents to sync before work, log summarized usage afterward, avoid raw user-message logging, and rate clear successes or failures (plugin-openclaw/skillnote/SKILL.md, plugin-openclaw/skillnote/sync.sh). That is closer to an operational memory protocol than the Claude Code plugin's simpler "sync and track calls" model.
The marketplace publish-back path is provenance-preserving but narrow. /marketplace/<collection>.json emits only imported skills because publish-back needs git-clonable sources; local user-authored registry skills are omitted (backend/app/services/imports/publisher.py, backend/app/api/marketplace.py). That is a good lineage boundary, but users may expect "collection marketplace" to include everything.
Security is self-hosted-local rather than multi-tenant. Import URL parsing has SSRF defenses and bundle validation rejects unsafe ZIP entries, but registry mutation endpoints are unauthenticated and CORS is configured for local origins by default (backend/app/services/imports/security.py, backend/app/validators/bundle_validator.py, backend/app/main.py). That matches the README's self-hosted assumption more than an enterprise governance model.
What to Watch
- Whether ratings, comments, and OpenClaw usage events start feeding a reviewed skill-revision or routing-policy loop rather than remaining analytics.
- Whether authentication, roles, collection visibility, or approval workflows return after the explicit auth-table removal.
- Whether MCP collection filtering is implemented from actual request query parameters instead of environment-only filters.
- Whether offline local edits gain a replay/reconciliation queue, or remain browser-local shadows.
- Whether imported-skill refresh grows a stronger lineage policy for forked skills, upstream drift, and conflict resolution.
- Whether semver release bundles become the primary install path again, or live registry sync remains the dominant integration surface.
Relevant Notes:
- Skills are instructions plus routing and execution policy - exemplifies: SkillNote operationalizes skills as discovery metadata, bodies, frontmatter policy, and runtime-specific install surfaces.
- System-definition artifact - defined-in: SkillNote skills, sidecars, hooks, settings, and MCP tools are consumed with instruction, routing, configuration, or evaluation force.
- Knowledge artifact - defined-in: provenance rows, comments, ratings, analytics dashboards, and usage summaries advise later work but do not directly bind behavior.
- Behavioral authority - sharpens: SkillNote bundles several authority paths in one product surface, so review must separate registry rows, mirrored files, telemetry, and runtime tools.
- Storage substrate - contrasts: SkillNote's canonical substrate is Postgres, while many agent-facing artifacts are regenerated filesystem projections.
- Use trace-derived extraction as meta-learning - contrasts: SkillNote stores call traces and ratings, but the reviewed code does not distill them into durable behavior-changing artifacts.