The open-source skill registry for AI coding agents.
Create, manage, and distribute SKILL.md files, or connect any agent directly via MCP.

Quick Start  ·  MCP Server  ·  Features  ·  Self-Hosting  ·  Contributing

AI coding agents like Claude Code, Cursor, and Codex use SKILL.md files to learn new capabilities. But managing these files is painful:

• They live scattered across ~/.claude/skills/, .cursor/skills/, .codex/skills/
• No versioning, no search, no way to share across projects or teams
• Writing them from scratch means guessing what works

SkillNote fixes this. It's a self-hosted registry with a clean web UI, a CLI for one-command installs, and an MCP server that lets any agent connect directly with no file installation needed.

Why self-hosted? Enterprise workflows, proprietary codebases, and compliance-sensitive prompts contain institutional knowledge that shouldn't leave your infrastructure. SkillNote runs entirely on your machines. Your skills stay private, versioned, and accessible only to your team.

Make sure you have Docker and Docker Compose v2+ installed.

git clone https://github.com/luna-prompts/skillnote.git
cd skillnote
docker compose up --build -d

Four containers spin up:

Open http://localhost:3000 and start creating skills.

The backend auto-runs migrations and seeds a default skill (skill-creator) on first boot. No manual setup needed.

Most people building AI agents hear about both and assume they're the same thing. They're not. Understanding the difference is what makes SkillNote click.

A Skill is a reusable piece of knowledge injected into an agent's context: instructions, workflows, rules, examples. Think of it as a dynamic system prompt loaded on demand:

User message
    ↓
Agent picks the right Skill
    ↓
Injects SKILL.md content into the prompt
    ↓
LLM responds with that context

Skills improve reasoning. They teach the agent how to do something.

Model Context Protocol is a standard for delivering context to agents: tools, APIs, documents, prompts. It improves connectivity. It doesn't care what the content is; it's the pipe.

Skills = HTML    (the content)
MCP    = HTTP    (the transport)

HTTP delivers HTML. But HTML isn't part of HTTP. Same relationship.

Version 1: local files:

Agent reads skills/making-tea/SKILL.md from disk

Simple. Works offline. But skills go stale, drift across machines, and require manual installs.

Version 2: MCP delivery (what SkillNote does):

Agent  →  MCP  →  SkillNote  →  Skills DB

Every skill is exposed as an MCP tool. The agent discovers and calls them live: no files, no installs, always up to date. Update a skill in the Web UI and every connected agent gets the new version instantly.

Real-time push notifications. When a skill is created, updated, or deleted the MCP server immediately pushes a notifications/tools/list_changed event to every connected agent over their open SSE stream. Compliant clients (Claude Code, OpenClaw, Cursor, …) re-fetch tools/list automatically — no reconnect, no polling, no restart required.

┌──────────┐     tools/list      ┌───────────────┐
│  Agent   │ ─────────────────▶  │  SkillNote    │
│          │ ◀─────────────────  │  MCP Server   │
│          │   [all your skills] │               │
│          │                     │  PostgreSQL   │
│          │  tools/call         │  LISTEN/      │
│          │ ─────────────────▶  │  NOTIFY       │
│          │ ◀─────────────────  │               │
│          │   skill content     │               │
│          │                     │               │
│          │ ◀─────────────────  │  push:        │
│          │  notifications/     │  tools/list   │
│          │  tools/list_changed │  _changed     │
└──────────┘  (SSE stream)       └───────────────┘

SkillNote exposes every skill as an MCP tool your agent can discover and call directly: no local files needed, no restart when skills change.

Every skill = one MCP tool. The tool name is the skill slug, the description is what the agent reads to decide when to invoke it, and calling the tool returns the full SKILL.md content. Filter by collection to control which skills (tools) each agent sees.

How it works:

• Each skill becomes a tool: name = slug, description = skill description
• The agent uses the description to decide when to invoke the skill
• Calling the tool returns the full SKILL.md content
• Skills added, updated, or deleted in SkillNote trigger a notifications/tools/list_changed push to every connected agent — no reconnect needed

claude mcp add --transport http skillnote http://localhost:8083/mcp --scope user

openclaw mcp add --transport http skillnote http://localhost:8083/mcp --scope user

{
  "mcpServers": {
    "skillnote": {
      "type": "http",
      "url": "http://localhost:8083/mcp"
    }
  }
}

{
  "mcpServers": {
    "skillnote": {
      "type": "http",
      "url": "http://localhost:8083/mcp"
    }
  }
}

{
  "mcpServers": {
    "skillnote": {
      "type": "http",
      "url": "http://localhost:8083/mcp"
    }
  }
}

{
  "mcpServers": {
    "skillnote": {
      "type": "http",
      "url": "http://localhost:8083/mcp"
    }
  }
}

{
  "mcpServers": {
    "skillnote": {
      "type": "http",
      "url": "http://localhost:8083/mcp"
    }
  }
}

http://localhost:8083/mcp

Use environment variables to serve only a subset of skills to a specific agent:

SKILLNOTE_MCP_FILTER_COLLECTIONS=devops,security docker compose up -d mcp

This is useful for scoping what different teams or agents can see.

The MCP Integrations page (sidebar → Connect → MCP Integrations) gives you ready-to-copy config snippets for every supported agent, a scope selector to generate collection-filtered URLs, and a live connection monitor that shows every connected agent — its name, version, IP, call count, and session duration — updating every 5 seconds.

A Notion-style WYSIWYG editor powered by Tiptap. Write in rich text or switch to raw markdown. Paste a raw SKILL.md file and it auto-extracts the name, description, and body from the frontmatter.

Every save creates a snapshot. Browse the full history, compare versions, and restore any previous state with one click. Published versions use semantic versioning (1.0.0, 1.1.0, ...) and are distributed as checksummed ZIP bundles.

Track how your skills are used across every connected agent. The Analytics dashboard shows total calls, unique skills invoked, active agents, a skill leaderboard, agent breakdown by client, an activity timeline, collection usage, and a live connections panel — all filterable by 7d / 30d / 90d / all-time.

Organise skills into collections. Filter, search, and browse by category. Add or remove skills from any collection with inline confirmation.

Install skills as local files to any AI coding agent from the web UI or CLI. Supported agents:

Every skill is a Markdown file with YAML frontmatter:

---
name: pdf-extractor
description: Extract text and tables from PDF files. Use when the user mentions PDFs, scanned documents, or form extraction.
---

# 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

SkillNote is lightweight. Here's what it uses on a typical machine at idle:

The API and MCP images share base layers — the combined pull is ~600 MB, not 912 MB.

Minimum recommended specs:

• CPU: 1 core (2+ recommended for MCP-heavy workloads)
• RAM: 512 MB free
• Disk: 2 GB for images + space for skill bundles (5 MB each by default)

Disk usage over time:

• Each published skill version creates a ZIP bundle (≤ 5 MB by default)
• PostgreSQL data grows slowly — a typical install with 100 skills is < 10 MB
• Logs are written to stdout (captured by Docker); no files accumulate on disk

To check live resource usage at any time:

docker stats

git clone https://github.com/luna-prompts/skillnote.git
cd skillnote
docker compose up --build -d

SKILLNOTE_HOST=192.168.1.100 SKILLNOTE_API_PORT=9000 docker compose up --build -d

docker compose down          # Stop (keeps data)
docker compose down -v       # Stop + wipe database

Run the backend in Docker, frontend with hot-reload:

# Terminal 1: Backend + MCP
docker compose up --build -d postgres api mcp
curl http://localhost:8082/health   # Wait for {"status":"ok"}

# Terminal 2: Frontend
npm install
npm run dev                         # http://localhost:3000

• Claude Code Skills - Anthropic's official skills documentation
• Model Context Protocol - MCP specification
• AgentSkills.io - The skills ecosystem
• Codex Skills - OpenAI Codex skills reference
• Antigravity Skills - Google Antigravity skills documentation
• OpenHands Skills - OpenHands skills overview

If you find SkillNote useful, please consider giving it a star on GitHub. It helps others discover the project and motivates us to keep improving it.

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m 'feat: add my feature')
4. Push to the branch (git push origin feat/my-feature)
5. Open a Pull Request

Please follow Conventional Commits for commit messages.

Join us on Discord to discuss ideas, get help, or just hang out.

MIT © Luna Prompts

Made with ❤️ by Luna Prompts