luna-prompts/skillnote

AI 코딩 에이전트(AI coding agents)를 위한 오픈 소스 스킬 레지스트리(skill registry).

팀의 SKILL.md 라이브러리를 셀프 호스팅(Self-host) 하세요.

버전 관리, 스코프(scope) 지정, 그리고 단 하나의 CLI를 통해 Claude Code와 OpenClaw로 배포하세요.

빠른 시작 (Quick start) ·
이유 (Why) ·
기능 (Features) ·
에이전트 (Agents) ·
아키텍처 (Architecture) ·
자주 묻는 질문 (FAQ) ·
Discord

Claude Code는 모든 활성 스킬 설명(docs)에 걸쳐 약 8,000자를 공유합니다. 이 제한을 넘어서면 설명이 조용히 잘립니다(truncate). 시스템 프롬프트는 컨텍스트에 나열되지 않은 스킬 사용을 금지하므로, 잘린 스킬은 보이지 않을 뿐만 아니라 명시적으로 사용 금지 상태가 됩니다 (#13343, #40121).

실제로 약 15개의 활성 스킬을 넘어가면 스킬이 작동을 멈추며, 어떤 스킬이 문제인지 알 수 없습니다. 새로운 팀원은 프로젝트가 어떤 스킬에 의존하는지 발견할 방법이 없습니다. 공유 스킬을 업데이트하려면 모든 사람을 위해 다시 압축(re-zip)하고 다시 업로드해야 합니다. 또한 배포 절차, 컴플라이언스 워크플로우(compliance workflows), 또는 내부 API 패턴과 같은 비공개 스킬을 안전하게 보관할 장소가 없습니다.

SkillNote는 이를 해결하는 셀프 호스팅 레지스트리(self-hosted registry)입니다. 프로젝트별 컬렉션(collections)을 통해 어떤 스킬을 로드할지 범위를 지정합니다. 라이브 동기화(Live sync)는 브라우저에서의 편집 내용을 60초 이내에 연결된 모든 에이전트에 푸시합니다. 에이전트는 스킬 사용 후 1점에서 5점 사이로 점수를 매기므로, 무엇이 효과적인지에 대한 신호(signal)를 마침내 얻을 수 있습니다. 귀하의 스킬은 귀하의 인프라에 머뭅니다. 귀하의 서버, 귀하의 규칙.

SkillNote 미사용 시	SkillNote 사용 시
약 15개 활성 스킬 초과 시 잘림	프로젝트당 컬렉션으로 범위 지정
노트북마다 ~/.claude/skills/ 존재	하나의 레지스트리로 모든 에이전트 연결
수정을 공유하려면 다시 압축 + 다시 업로드	브라우저에서 편집하면 모든 세션이 60초 내 반영
실제로 무엇이 작동하는지 알 수 없음	에이전트가 사용하는 모든 스킬에 대해 1-5점 및 댓글 작성
비공개 스킬을 안전하게 보관할 곳이 없음	셀프 호스팅; 네트워크를 절대 벗어나지 않음

npx skillnote start

http://localhost:3000 을 엽니다.

Docker(실행 중) 및 **Node.js 20+**가 필요합니다. CLI는 GHCR에서 게시된 이미지를 가져와 웹 + API + Postgres 스택을 실행하고, 상태 확인(healthchecks)을 기다린 후 대시보드를 엽니다. 캐시가 있는 상태(warm cache)에서는 약 30초가 소요됩니다.

┌────────────────────────────────────────────┐
│ SkillNote ▸ AI를 위한 스킬 레지스트리 │
│ v0.5.2 · github.com/luna-prompts/skillnote│
...

다른 설치 방법 (Other ways to install)

Docker Compose 직접 사용하기 (Node 불필요):

curl -fsSL https://raw.githubusercontent.com/luna-prompts/skillnote/cli-v0.5.4/deploy/docker-compose.yml -o docker-compose.yml
docker compose up -d

같은 네트워크의 팀원을 위한 LAN 접근:

SKILLNOTE_HOST=<your-lan-ip> docker compose up -d

Podman 사용 시: npx skillnote start

Docker 전용이지만, Compose 경로나 install.sh 모두 podman compose (Podman 4+) 또는 podman-compose와 함께 작동합니다.

소스 코드에서 빌드하기 (기여자):

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

install.sh는 게시된 이미지를 가져오는 대신 로컬 소스에서 빌드합니다. docker compose, podman compose, 또는 podman-compose를 자동 감지합니다.

npx skillnote start # 부팅 및 UI 열기
npx skillnote stop # 중단; 볼륨 보존
npx skillnote restart # 중단 + 시작
...

백엔드가 실행된 후, 에이전트용 플러그인을 설치합니다.

npx skillnote connect claude-code
source ~/.zshrc # 또는 ~/.bashrc

표준 /setup/agent 스크립트를 실행합니다: ~/.claude/settings.json에 플러그인 마켓플레이스를 등록하고, ~/.claude/plugins/에 SkillNote 플러그인을 설치하며, ~/.skillnote/bin/에 피커 바이너리를 배치하고, 셸 래퍼를 추가합니다. 어떤 프로젝트에서든 claude를 실행하면 첫 실행 시 컬렉션 피커가 나타납니다:

컬렉션을 선택하면 (.skillnote.json에 저장됨) 모든 세션에서 사용 범위가 지정된 스킬이 로드됩니다.
또는, 이 프롬프트를 새로운 Claude Code 세션에 붙여넣으세요

Install SkillNote on my machine and wire it into this Claude Code session.
1. If http://localhost:8082/health doesn't respond, run:
npx skillnote start --no-browser -d
...

clawhub install skillnote

이것이 기본 localhost:8082에 대한 전체 설치 과정입니다.

설정(setup)입니다. 백엔드(backend)가 실행 중이지 않다면, 스킬이 첫 번째 동기화(sync) 시에 자동으로 부트스트랩(auto-bootstraps)합니다.

이 스킬은 다음 파일들을 포함합니다:
sync.sh (60초 간격 카탈로그 동기화), log-watcher.py (분석 데몬 (analytics daemon)), install-backend.sh (부트스트랩 (bootstrap)), 그리고 항상 로드되는 SKILL.md입니다.

SKILL.md는 ~/.openclaw/workspace/AGENTS.md 파일 안에 지속적인 <skillnote v1> 블록을 이식(grafts)합니다.

기본 호스트가 아니거나 다른 방식으로 설치하는 경우

기본 호스트가 아닌 경우:

export SKILLNOTE_BASE_URL="http://your-server:8082"
clawhub install skillnote
echo 'export SKILLNOTE_BASE_URL="http://your-server:8082"' >> ~/.zshrc

또는 스크립트 방식 (clawhub 미사용):

npx skillnote start --no-browser -d
npx skillnote connect openclaw

Cursor, Codex, Antigravity, 그리고 OpenHands는 로드맵(roadmap)에 포함되어 있습니다. 어댑터(adapter) 구축을 돕고 싶다면 이슈(issue)를 생성해 주세요.

Claude Code는 모든 활성 스킬 설명(skill description)에 걸쳐 약 8,000자(characters)를 공유합니다. 약 15개의 스킬을 넘어가면 설명이 조용히 잘리며(truncate), 잘린 스킬은 트리거(trigger)되지 않습니다. 컬렉션(Collections)은 프로젝트당 어떤 스킬을 로드할지 범위를 지정합니다. 예를 들어 프론트엔드(frontend) 프로젝트는 React + 테스트 패턴(testing patterns)을 가져오고, API 프로젝트는 에러 처리(error handling) + 배포 관례(deploy conventions)를 가져옵니다. 동일한 레지스트리(registry)를 사용하되 활성 세트(active sets)만 다르므로, 컨텍스트(context) 낭비가 없습니다.

폴더 이름이 컬렉션과 일치하면 플러그인(plugin)이 자동으로 이를 추천합니다.

Anthropic이 해당 형식을 출시한 이후, 커뮤니티에서는 수천 개의 SKILL.md 파일을 게시했습니다. GitHub URL, 약어(garrytan/gstack), 하위 폴더의 트리 URL(tree URL), 또는 Claude Code 마켓플레이스 매니페스트(anthropic.json)를 붙여넣으세요. SkillNote는 저장소(repo)를 얕은 복제(shallow-clones)하고, 모든 SKILL.md를 스캔하며, 프론트매터(frontmatter)를 검증한 뒤, 사용자가 설치할 항목을 정확히 선택할 수 있는 워크스페이스(workspace)를 엽니다.

시도해 볼 만한 인기 레지스트리:

• Anthropic의 공식 Agent Skills 저장소: anthropics/skills
• 800개 이상의 커뮤니티 스킬, 가장 큰 큐레이션 세트: ComposioHQ/awesome-claude-skills
• Claude Code, Codex, Gemini CLI, Cursor 등을 위한 600개 이상의 스킬: alirezarezvani/claude-skills
• Garry Tan의 50개 이상의 주관적인 YC 스타일 도구들 (CEO, Designer, Eng Manager 등): garrytan/gstack

: Jesse Vincent의 에이전트 기술 프레임워크 (agentic skills framework) obra/superpowers

브라우저에서 기술 (skill)을 편집하면 실행 중인 모든 Claude Code 또는 OpenClaw 세션이 60초 이내에 변경 사항을 반영합니다. Claude Code는 매 프롬프트 (prompt)마다 다시 동기화하며, 세션 중간에 SKILL.md를 핫 리로드 (hot-reloads) 합니다. OpenClaw의 sync.sh는 60초 간격으로 실행됩니다. 한 사람이 기술을 업데이트하면 모두가 이를 적용받습니다. 새로운 팀원은 설정 명령어를 한 번만 실행하면 팀이 구축한 모든 기술을 상속받습니다.

대부분의 기술 설정은 실행 후 잊어버리는 (fire-and-forget) 방식입니다. SkillNote는 이 루프를 완성합니다. 기술을 적용한 후, 에이전트는 이를 1~5점으로 평가하고 수행한 작업을 설명합니다. OpenClaw는 추가적으로 각 평가를 해당 평가를 생성한 특정 작업과 연관시키는 linked_usage_id를 게시합니다. 이를 통해 어떤 기술이 실제로 사용되고 있는지, 어떤 기술이 작동을 멈추는지, 그리고 버전에 따라 성능이 어떻게 변하는지 확인할 수 있습니다.

저장할 때마다 스냅샷 (snapshot)이 생성됩니다. 클릭 한 번으로 모든 버전을 찾아보고, 비교하고, 복구할 수 있습니다. 배포된 버전은 유의적 버전 (semver)을 사용하며 체크섬 (checksummed) 처리된 ZIP 번들로 제공됩니다.

Claude Code가 사용자가 동일한 사항을 세 번 수정하는 것을 감지하면 (예: "npm 대신 pnpm을 사용하세요"), 이를 기술로 전환할 것을 제안합니다. 해당 기술은 SkillNote로 푸시되며 60초 이내에 연결된 모든 에이전트에 동기화됩니다. 한 사람이 한 번 가르친 것이 모두가 가진 기술이 됩니다.

에이전트 (Agent)	상태 (Status)	메커니즘 (Mechanism)
Claude Code	지원됨 (Supported)	6개의 라이프사이클 훅 (lifecycle hooks)을 가진 네이티브 플러그인 (~/.claude/plugins/skillnote/)
OpenClaw	지원됨 (Supported)	sync.sh 및 분석 데몬 (analytics daemon)을 포함한 clawhub 기술 번들
Cursor	계획됨 (Planned)	로드맵 (Roadmap)
Codex CLI	계획됨 (Planned)	로드맵 (Roadmap)
...

어댑터 (adapter) 구축을 돕고 싶으신가요? 이슈 (issue)를 생성하거나 Discord에서 저희와 함께하세요.

┌──────────────────────────────────────────────────────┐
│                                                      │
│ SkillNote Server (Docker)                            │
│ ...                                                  │

SkillNote는 각 에이전트의 네이티브 기술 시스템을 사용합니다. Claude Code의 경우, SessionStart, UserPromptSubmit, PostToolUse, PostCompact, SubagentStart, Stop을 포함하는 훅 (hooks) 및 플러그인 형식을 사용합니다. 오직 SessionStart

블록(약 1초 동안 동기화); 그 외의 모든 훅 (hooks)은 비동기 (async)로 실행되므로, SkillNote를 위해 대기할 필요가 없습니다.

OpenClaw의 경우 sync.sh가 포함된 clawhub 설치 가능 번들입니다.

(catalog), log-watcher.py (analytics), 그리고 에이전트가 매 작업마다 레지스트리 (registry)를 조회하도록 유지하는 AGENTS.md 접목 (graft)이 포함됩니다.

기술 (Skills)은 네트워크 추상화 (network abstraction)를 통해 전달되지 않고, 로컬 SKILL.md 파일로 작성됩니다. 이는 allowed-tools, context: fork, effort, model을 포함한 모든 Claude Code 프론트매터 (frontmatter) 기능이 네이티브하게 작동함을 의미합니다. 이러한 기능들은 디스크 상의 SKILL.md 파일에서만 작동하며, 이것이 SkillNote가 기술을 네트워크 프로토콜을 통해 제공하는 대신 디스크로 동기화하는 이유입니다.

전체 고수준 설계 (HLD)는 docs/openclaw-hld.md를 참조하세요.

---
name: pdf-extractor
description: PDF 파일에서 텍스트와 표를 추출합니다. 사용자가 PDF 또는 스캔된 문서를 언급할 때 사용하세요.
...

SkillNote는 신뢰할 수 있는 환경, 즉 개발자의 노트북, 프라이빗 네트워크 상의 팀 VM, 또는 VPN 뒤에 있는 셀프 호스팅 (self-hosted) 서버를 위해 구축되었습니다. 기본적으로 웹 UI 또는 API에 대한 인증 (authentication)이 없습니다. :3000 및 :8082에 도달할 수 있는 것이라면 무엇이든 기술을 읽고 쓸 수 있습니다.

로컬 전용 (기본값): npx skillnote start는 localhost에 바인딩됩니다. 안전합니다.
LAN 전용: 동일한 네트워크의 팀원들에게 노출하려면 SKILLNOTE_HOST=<lan-ip>를 설정하세요. LAN이 신뢰할 수 있다고 가정합니다.
인터넷 노출: :3000 또는 :8082를 공인 IP에 직접 바인딩하지 마세요. 기본 인증 (basic auth), OAuth, 또는 Tailscale/Cloudflare Tunnel을 사용하는 리버스 프록시 (reverse proxy) (Caddy, Nginx, Traefik) 뒤에 배치하세요.
마켓플레이스 가져오기 (Marketplace imports): 모든 설치는 에이전트가 읽게 될 SKILL.md 파일을 작성합니다. 익숙하지 않은 소스에서 가져오기 전에 워크스페이스 미리보기를 검토하세요.

API 인증은 로드맵에 포함되어 있습니다. 그때까지는 도달 가능성 (reachability)을 액세스 경계 (access boundary)로 취급하세요.

계층 (Layer)	기술 (Technology)
CLI	Node 20+, TypeScript, commander, @clack/prompts
...
SkillNote란 무엇인가요?

SkillNote는 Anthropic의 Agent Skills 형식을 위한 오픈 소스(open-source) 기반의 셀프 호스팅(self-hosted) 레지스트리입니다. 여러분의 자체 인프라(노트북, 팀 VM, 프라이빗 서버 등)에서 실행할 수 있으며, 팀이 Claude Code, OpenClaw 및 기타 코딩 에이전트 전반에 걸쳐 SKILL.md 파일을 생성, 버전 관리 및 공유할 수 있는 단일 공간을 제공합니다. 웹 UI를 통해 Notion 스타일의 에디터로 스킬을 편집할 수 있으며, CLI 플러그인은 레지스트리를 각 에이전트의 네이티브 스킬 시스템과 동기화하여 세션 도중에도 스킬이 핫 리로드(hot-reload)되도록 합니다.

SkillNote는 MCP와 어떻게 다른가요?

MCP (Model Context Protocol)는 네트워크를 통해 도구(tools)와 통신하기 위한 와이어 프로토콜(wire protocol)입니다. 반면 스킬(Skills)은 에이전트가 디스크에서 읽어들이는 로컬 SKILL.md 파일입니다. 이 둘은 서로 다른 문제를 해결합니다. MCP는 에이전트가 원격 서비스(remote service)를 호출할 수 있게 해주며, 스킬은 지침(instructions), 예시(examples), 그리고 allowed-tools 또는 context: fork와 같은 프론트매터(frontmatter) 디렉티브(directives)를 통해 에이전트에게 무언가를 수행하는 방법을 알려줍니다. SkillNote는 후자의 방식을 배포합니다. SkillNote가 스킬을 디스크로 동기화하는 이유는 allowed-tools, context: fork, effort, model과 같은 기능들이 실제로 Claude Code에 의해 디스크 상에서 평가되기 때문이며, 이러한 기능들은 네트워크 프로토콜을 통해서는 작동하지 않습니다.

Claude Code 스킬을 팀 전체와 어떻게 공유하나요?

팀원들이 접근할 수 있는 서버에서 SkillNote를 실행하세요 (LAN 환경이라면 SKILLNOTE_HOST=<lan-ip> docker compose up -d를 사용하거나, 원격 팀의 경우 리버스 프록시(reverse proxy) 뒤에서 실행합니다). 모든 팀원은 npx skillnote connect claude-code 명령어를 통해 Claude Code에 SkillNote 플러그인을 설치합니다. 그 이후부터는 누군가가 SkillNote 웹 UI에서 수행하는 모든 편집 사항이 60초 이내에 실행 중인 모든 Claude Code 세션으로 전파됩니다. 새로운 팀원은 connect 명령어를 한 번만 실행하면 팀이 구축한 모든 스킬을 상속받게 됩니다.

SkillNote는 무료인가요?

네. SkillNote는 MIT 라이선스이며 셀프 호스팅 방식입니다. 클라우드 티어(cloud tier)나 유료 플랜, 사용량 텔레메트리(usage telemetry)가 없습니다. 여러분의 장비에서 직접 실행하며 데이터에 대한 소유권도 여러분에게 있습니다.

Claude Code: 다른 컬렉션의 스킬이 나타납니다

Claude Code는 상위 디렉토리의 스킬을 탐색합니다. 만약 claude를 실행했다면

상위 폴더(~/projects/)에서 실행하여 컬렉션을 선택했다면, 해당 스킬들은 ~/projects/.claude/skills/에 남아 모든 하위 디렉토리 프로젝트로 유출됩니다.

rm -rf ~/path/to/parent/.claude/skills/skillnote-*

항상 상위 폴더(umbrella folders)가 아닌, 실제 프로젝트 디렉토리에서 claude를 실행하세요.

Claude Code: 플러그인 변경 사항이 적용되지 않는 경우

Claude Code는 시작 시점에 플러그인을 로드합니다. Claude Code가 실행 중인 상태에서 플러그인을 재설치했다면, 프로그램을 종료한 후 다시 시작해야 새 플러그인이 로드됩니다.

OpenClaw: 설치 후 sn-* 스킬이 나타나지 않는 경우

첫 세션에서 sync.sh가 성공적으로 실행되었는지 확인하세요:

~/.openclaw/skills/skillnote/sync.sh
ls ~/.openclaw/skills/sn-* | head

만약 동기화(sync) 결과가 아무것도 나오지 않는다면, ~/.openclaw/skills/skillnote/config.json 파일에 host 설정이 있는지 확인하세요.