ginuim/skill-base

English | 中文

Skill Base는 에이전트 스킬 (Agent Skills)을 위한 프라이빗 배포 플랫폼입니다. 한 번만 게시하면, 최소한의 서버와 skb CLI를 통해 Cursor, Claude Code, Codex, OpenClaw 및 유사한 어시스턴트 전반에서 팀이 스킬을 일관되게 설치, 업데이트 및 롤백 (rollback)할 수 있도록 합니다. 이는 단순한 파일 저장소가 아닌, 팀을 위한 스킬 배포 및 버전 관리 (versioning) 문제를 해결합니다.

많은 팀이 이미 스킬 (Skills)을 작성하고 있지만, 일반적인 패턴은 여전히 .cursor/skills, .claude/skills, .github/instructions 등에 파일을 넣고 Git을 통해 동기화하는 방식입니다. 팀 규모가 커지기 전까지는 작동하지만, 그 이후에는 문제가 발생합니다.

어떤 사람은 Cursor를 사용하고, 다른 사람은 Claude Code, Qoder, Windsurf, OpenCode를 사용합니다. 각 IDE (통합 개발 환경)는 서로 다른 폴더 레이아웃과 컨벤션 (conventions)을 가지고 있습니다. 여러분이 동기화해야 하는 것은 단 하나의 폴더가 아니라, 디스크 상의 서로 다른 규칙들의 집합입니다.

PM (프로덕트 매니저)과 QA (품질 보증) 또한 PRD (제품 요구 사항 문서), 테스트 케이스, 회귀 테스트 체크리스트를 위해 스킬이 필요합니다. 이들이 팀 표준을 사용하기 위해 리포지토리 (repo) 접근 권한이나 git pull 교육을 받을 필요는 없어야 합니다.

프로젝트 A에서 “범용 API 인증 스킬 (generic API auth Skill)”이 업데이트되어도, 프로젝트 B는 자동으로 이를 따르지 않습니다. 결국 모든 곳에 복사하게 되고, 모든 곳에서 버전이 어긋나며, 모든 곳에서 업데이트를 놓치게 됩니다.

Skill Base는 한 가지를 명확하게 수행합니다: 스킬을 게시 가능하고, 설치 가능하며, 업데이트 가능하고, 롤백이 용이한 팀 자산 (assets)으로 만드는 것입니다.

다음 내용을 어시스턴트에게 그대로 전달하세요 (사용 중인 환경에 맞춰 서버 URL과 인증 코드를 교체하십시오). 각 단계 아래의 들여쓰기된 인용문은 Claw에 그대로 붙여넣을 프롬프트입니다.

설치 skill-base-cli (ClawHub에서 가져오기 - 기존 Skill Base 사이트 사용)
ClawHub에서 skill-base-cli를 가져와 스킬 디렉토리에 설치합니다. 일상적인 skb 검색, 설치, 게시 및 팀이 이미 운영 중인 Skill Base에 연결하는 용도로 사용하십시오. CLI를 사용하기 위해 server-deploy 스킬을 반드시 설치할 필요는 없습니다.

설치 skill-base-web-deploy (ClawHub에서 가져오기 - 서버 배포 또는 운영)
ClawHub에서 skill-base-web-deploy를 가져와 스킬 디렉토리에 설치합니다. 어시스턴트가 ...를 수행해야 할 때만 이 스킬을 설치하십시오.

서비스 실행 (run the service)
당신의 머신이나 서버에서 서비스를 실행합니다. — Docker, 데이터 디렉토리 (data directory), 백업, 그리고 기타 서버 측 (server-side) 작업들을 포함합니다. -

CLI를 서버로 지정 (Point the CLI at your server)
Skill Base 설정을 도와주세요; 서버 URL은

https://skill-base-server

입니다.

실제 사이트 루트 URL (site root URL)을 사용하십시오.

스킬 검색 (Search for a Skill)
skb를 사용하여 some-skill을 검색하세요.

보통 로그인이 필요하지 않습니다. -

스킬 설치 (Install a Skill)
skb를 사용하여 some-skill을 설치하세요. skill_id@version 형식을 통해 버전을 고정하거나, 대상 디렉토리 또는 IDE를 위해 -d / --ide 옵션을 전달할 수 있습니다. 보통 로그인이 필요하지 않습니다. -

스킬 업데이트 (Update a Skill)
skb를 사용하여 some-skill을 업데이트하세요. -

skb 로그인 완료 (Complete skb login)
skb 로그인을 도와주세요; 인증 코드는 xxxx-xxxx 입니다.

코드는 브라우저 흐름(browser flow)에서 제공되거나 브라우저에서 https://<host>/cli-code를 열었을 때 나타나며, 5분 동안 유효합니다. -

게시 (Publish)
skb를 사용하여 방금 작성한 스킬을 게시하세요.

필요할 때 어시스턴트에게 --changelog 초안 작성을 요청할 수도 있습니다.

이 저장소는 skills/ 아래에 어시스턴트 지향적인 두 가지 스킬을 유지하며, 두 스킬 모두 ClawHub에 게시되어 있습니다:

스킬 (Skill)	역할 (Role)
skill-base-cli	어시스턴트가 당신의 Skill Base 사이트를 대상으로 터미널에서 skb init, login, whoami, search, install, update, publish 등을 실행하도록 안내합니다.
skill-base-web-deploy	어시스턴트가 Skill Base 서버를 배포, 시작 또는 운영(npx skill-base, Docker, 포트, 데이터 디렉토리, 백업 등)하도록 안내합니다.

OpenClaw-class 제품에서는 Claw가 ClawHub에서 필요한 스킬을 어시스턴트의 스킬 디렉토리로 설치하도록 할 수 있습니다 (마켓플레이스에서 스킬 패키지를 가져오는 것과 동일한 개념). 설치 후, 전형적인 프라이빗 Skill Base 루프는 다음과 같습니다:

서버 (Server) — 어시스턴트가 로컬 인스턴스를 시작하게 하거나 (예: npx skill-base -d <data-dir> -p <port>), 기존 배포 환경에 연결하게 합니다. 작업이 "서버 실행 또는 운영"일 때 skill-base-web-deploy를 사용하십시오.

CLI 대상 (CLI target) — skb init -s <site-root-url>을 실행합니다.

서버 루트를 ~/.skill-base/config.json에 저장하려면 URL 뒤에 /api 접미사(suffix)를 붙이지 마십시오.로그인 (Login)—skb search와 skb install은 로그인을 요구하지 않습니다. 게시(publish)할 준비가 되면, 어시스턴트가 여러분과 함께 skb publish를 실행하도록 하십시오. skb login은 브라우저 인증 흐름(browser verification flow)을 사용합니다. 또한 브라우저에서 (예를 들어 여러분의 머신에 있는 http://<your-skill-base-host>/cli-code 또는 http://localhost:8000/cli-code)를 열어 임시 (temporary) 코드를 얻을 수도 있습니다. CLI는 이 코드를 **장기 지속 PAT (long-lived PAT)**로 교환합니다. 이 코드는 5분 동안 유효하므로, Claw나 어시스턴트에 붙여넣어도 안전합니다. 여러분이 장기적인 비밀 정보를 넘겨주는 것이 아니기 때문입니다.일상적인 사용 (Day-to-day)— skb search, skb install, skb update, skb publish를 사용하여 가져오기(pull), 업데이트, 릴리스를 수행하십시오. skill-base-cli가 이 작업들에 대한 권한을 가집니다. 게시할 때는 릴리스 노트(release notes)를 위해 skill-base-cli --changelog "..."를 사용하십시오. 또한 AI 어시스턴트가 여러분의 변경 사항이나 메모로부터 변경 로그(changelog) 문구를 생성하도록 한 뒤, 이를 skb publish에 전달할 수도 있습니다.

CLI를 머신에 전역(globally)으로 설치하거나 (pnpm add -g skill-base-cli) npx skill-base-cli를 사용할 수도 있습니다. 이 두 가지 Skill의 가치는 어시스턴트가 여러분을 대신하여 일관된 규칙(one convention) 하에 동일한 명령어를 일관되게 실행하도록 돕는다는 점에 있습니다.

skb install은 단순한 다운로드가 아닙니다. CLI는 특정 Skill이 어떤 로컬 디렉토리에 설치되었는지, 어떤 IDE에 속해 있는지, 그리고 현재 버전을 기억합니다.

팀 표준이 변경되면 다음을 실행합니다:

skb update some-skill

설치 기록이 하나뿐이라면 CLI가 직접 업데이트하며, 여러 디렉토리가 있다면 사용자가 선택할 수 있도록 목록을 보여줍니다. 핵심은 화려한 UI가 아니라, 더 이상 수십 개의 프로젝트에 걸쳐 오래된 Skill을 일일이 수동으로 교체할 필요가 없다는 점입니다.

이로써 실질적인 루프가 완성됩니다: AI가 로컬에서 Skill을 다듬게 한 다음, 내부 서버로 skb publish를 수행하십시오. 그러면 팀원들은 skb update를 한 번 실행하는 것만으로 최신 규칙을 가져올 수 있습니다.

엔지니어들은 계속해서 터미널을 사용합니다:

skb search vue
skb install team-vue-rules --ide cursor
skb publish ./my-skill --changelog "API auth rules updated"

PM, QA, 그리고 CLI (Command Line Interface) 사용을 선호하지 않는 동료들은 웹 UI (Web UI)에서 패키지를 검색, 버전 탐색 및 다운로드할 수 있습니다. 팀의 지식은 코드를 작성하는 사람들만을 위한 것이어서는 안 됩니다.

웹 UI는 계정 기반의 즐겨찾기, 다운로드 카운터, 그리고 선택 사항인 글로벌 태그 라이브러리 (Global tag library)도 지원합니다. 슈퍼 관리자 (Super admins)는 사용자 메뉴의 태그 관리 (Tag management) (/admin/tags) 섹션에서 태그를 관리합니다.

홈 디렉토리에서는 컴팩트한 태그 (Tags) 필터 (다중 선택, OR 의미론)를 사용하여 현재 보이는 스킬들에 포함된 태그로 스킬 목록을 좁힐 수 있습니다. 스킬 소유자 및 협업자 (Collaborators)는 스킬 상세 페이지에서 해당 라이브러리를 통해 태그를 할당합니다. 인라인 미리보기 (Inline previews)는 전용 /view 엔드포인트 (Endpoint)를 사용하므로, 버전 ZIP 파일을 탐색하더라도 다운로드 통계가 부풀려지지 않습니다.

가시성 (Visibility)은 데이터 모델 (Data model)에 내장되어 있습니다:

• 스킬은 기본적으로 public (공개) 상태입니다.
• 스킬은 private (비공개)로 설정할 수 있습니다 (소유자/협업자/관리자만 조회 가능).
• 기존/레거시 행들은 마이그레이션 (Migration) 동안 안전하게 업그레이드되며 public으로 취급됩니다.
• 만약 누군가 협업자 권한 없이 기존의 skill_id로 게시를 시도하면, 게시가 거부됩니다.

Skill Base 서버는 다음 항목들만 관리합니다:

• skills.db: 스킬, 버전, 사용자, 권한을 위한 인덱스 (Index)
• skills/<skill-id>/<version>.zip: 릴리스 (Release)별 아카이브된 패키지
• 소규모 Node.js 서비스: 인증 (Auth), 업로드, 다운로드, 버전 API, 정적 UI

MySQL도, Redis도, 다음 달이면 관리를 포기하게 될 복잡한 인프라 (Infra) 더미도 없습니다.

-d ./data 옵션을 전달하면, 레이아웃은 대략 다음과 같습니다:

data/
├── skills.db
└── skills/
...

백업 (Backups), 마이그레이션 (Migrations), 롤백 (Rollbacks)은 단순하게 유지됩니다. 많은 팀들이 심지어 이 디렉토리를 Git으로 버전 관리할 수도 있습니다.

Node.js >= 18 버전이 필요합니다.
서버는 이제 SQLite 접근을 위해 node-sqlite3-wasm을 사용하므로, 일반적인 시작 방식이 더 이상 로컬의 better-sqlite3에 의존하지 않습니다.

네이티브 컴파일 (native compilation).
이전에 SQLite를 WAL 모드로 작성했던 이전 릴리스에서 업그레이드하는 경우, Skill Base는 첫 시작 시 기존 데이터베이스를 자동으로 마이그레이션합니다. 먼저 사용자의 PATH에 있는 sqlite3 (서버의 libc와 일치하는 것)를 시도한 다음, 번들로 포함된 sqlite3 헬퍼(helper)로 폴백(fallback)하며, 그 후 수동 작업이나 데이터 손실 없이 WASM 드라이버로 계속 진행합니다.

다음 환경을 위한 번들 마이그레이션 헬퍼가 포함되어 있습니다:

• macOS arm64
• macOS x64
• Linux x64
• Windows x64

다른 플랫폼에 배포하면서 오래된 WAL 데이터베이스를 업그레이드하는 경우, 첫 시작 시 SKILL_BASE_SQLITE3_PATH를 로컬 sqlite3 실행 파일로 설정하십시오.

npx skill-base -d ./skill-data -p 8000

처음 방문 시 웹 UI가 초기화를 실행합니다. 안내에 따라 관리자 계정을 생성하십시오.

일반적인 호출 방식:

npx skill-base
npx skill-base --host 127.0.0.1
npx skill-base --base-path /skills/
...

일반적인 플래그 (flags):

플래그	단축형	설명	기본값
--port	-p	리슨 포트 (Listen port)	8000
--host	-h	바인드 주소 (Bind address)	0.0.0.0
--data-dir	-d	데이터 디렉토리 (Data directory)	패키지 data/
--base-path	-	URL 접두사 (URL prefix)	/
--cache-max-mb	-	프로세스 내 LRU 캐시 크기 (MB)	50
--session-store	-	세션 저장소 유형 (memory	sqlite)
--no-cappy	-	터미널 Cappy 비활성화	기본적으로 활성화됨
--verbose	-v	디버그 로깅 (Debug logging)	off

환경 변수 (Environment variables):

변수	설명	기본값
CACHE_MAX_MB	프로세스 내 LRU 캐시 제한	50
SESSION_STORE	memory 또는 sqlite (sqlite는 아래 세션 저장소 섹션 참조)	memory
DEBUG	true로 설정하면 상세 로깅을 활성화합니다 (npx skill-base 사용 시 --verbose / -v와 동일: 시작 시 DEBUG: 라인 출력 및 Fastify 요청 로깅)	off

세션은 프로세스 메모리에 상주합니다.

memory (기본값): 애플리케이션이 재시작되면 모든 세션이 삭제됩니다 (사용자가 다시 로그인해야 함). 세션 생성/읽기/삭제 시 SQLite를 건드리지 않으므로, sqlite 방식에 비해 데이터베이스 I/O를 줄일 수 있습니다.

세션은 skills.db와 함께 sqlite의 sessions 테이블에 저장됩니다. 세션은 재시작 후에도 유지되며, 인스턴스들이 동일한 데이터베이스 파일을 공유하는 멀티 인스턴스 (multi-instance) 배포 환경에 적합합니다. 세션 생명주기 동안 SQLite 읽기/쓰기가 발생할 수 있습니다.

GET /api/v1/health는 캐싱이 활성화되어 있는지 확인할 수 있도록 간소화된 캐시 통계 (cache stats)를 반환합니다.

pnpm add -g skill-base-cli

skb init -s http://your-team-server
skb login

저장된 토큰이 해당 서버에서 여전히 작동하는지 확인하려면: skb whoami를 사용하세요.

(또는 스크립트용으로 skb whoami --json / skb whoami -q를 사용하세요).

# Search
skb search vue
# Latest version
...

지원되는 IDE는 다음과 같습니다:

• Cursor
• Claude Code
• GitHub Copilot
• Windsurf
• Qoder
• QoderWork
• OpenCode

Skill Base는 다음과 같은 상황에서 도움이 됩니다:

• 팀에서 두 개 이상의 AI IDE를 사용하는 경우
• 스킬 (Skills)을 여러 프로젝트에서 재사용해야 하는 경우
• 표준이 자주 진화하여 버전 기록 (version history)이 필요한 경우
• PM, QA, ops가 스킬에 직접 접근하기를 원하는 경우
• 작은 플랫폼을 위해 무거운 인프라를 구축하고 싶지 않은 경우

Skill Base는 SKILL.md를 포함하는 디렉토리를 게시합니다. 최소한의 예시는 다음과 같습니다:

---
name: team-vue3-admin
description: "Internal Vue3 admin best practices. Triggers on requests to create Vue admin pages, use ProTable, ProForm, or internal request utilities."
...

프론트매터 (frontmatter)가 없으면 첫 번째 # 제목이 이름이 되고, 그 뒤의 첫 번째 단락이 설명이 됩니다. 하지만 여전히 name과 description을 명시적으로 설정하는 것이 좋습니다.

CLI를 사용하지 않는 사람들을 위해 웹 UI는 다음 기능을 지원합니다:

• 내부 스킬 탐색 및 검색
• 기록 및 변경 로그 (changelogs) 보기
• 패키지 다운로드
• SKILL.md가 포함된 폴더 또는 zip 파일을 업로드하여 게시
• URL 또는 owner/repo를 통해 공개 (public) GitHub 저장소를 가져오기 (게시 페이지): 서버가 GitHub zipball을 다운로드하고 SKILL.md를 파싱하여 일반 업로드와 같이 게시합니다. 기본적으로 유도된 스킬 ID가 이미 존재하고 해당 ID에 게시할 권한이 없는 경우, UI는 게시 전에 편집할 수 있는 gh-owner-repo 스타일의 ID를 제안합니다.
• 스킬 가시성 설정 (public...

/private)
)

스킬 (Skill) 생성 시 설정하며, 이후 스킬 상세 페이지에서 (소유자만) 가시성 (visibility)을 업데이트할 수 있습니다. - 비공개 (private) 스킬은 목록, 상세, 버전 및 다운로드 엔드포인트 (endpoints) 전반에서 협업자 이외의 사용자에게는 숨겨집니다.

GitHub 가져오기 (server): 선택 사항인 환경 변수 GITHUB_TOKEN 또는 SKILL_BASE_GITHUB_TOKEN은 API 속도 제한 (rate limits)을 발생시킬 수 있습니다. SKILL_BASE_GITHUB_IMPORT_MAX_ZIP_MB는 다운로드 크기를 제한하며 (기본값 50), SKILL_BASE_GITHUB_CONNECTIVITY_TIMEOUT_MS는 연결 확인 (connectivity probe) 타임아웃을 조정합니다 (기본값 8000). 게시 (Publish) 페이지는 GET /api/v1/skills/import/github/connectivity를 호출하여 서버가 GitHub에 도달할 수 있는지 여부를 표시할 수 있습니다 (브라우저 VPN은 도움이 되지 않습니다). 이 흐름에서는 비공개 리포지토리 (Private repos)가 지원되지 않습니다.

CLI: skb import-github owner/repo (별칭 skb import)는 --ref, --subpath 옵션을 사용합니다.