AI 튜토리얼

Skillbox 셀프 호스팅: AI 에이전트를 위한 버전 관리형 스킬 라이브러리 구축

Docker로 Skillbox를 배포하고, 버전 관리형 스킬과 범위가 지정된 클라이언트 연결을 만들며, CLI 및 MCP 인터페이스를 사용하고, 선택적 Jev 추천을 구성하고, 데이터를 보호하거나 이전하는 방법을 알아보세요.

2026년 9월 18일약 17분 소요

Skillbox 셀프 호스팅: AI 에이전트용 버전 관리 스킬 라이브러리

Skillbox란?

Skillbox는 MIT 라이선스로 제공되는 AI 에이전트용 자체 호스팅 스킬 라이브러리입니다. 재사용 가능한 스킬 패키지를 생성, 가져오기, 버전 관리, 배포 및 감사할 수 있는 중앙 공간을 제공합니다. 애플리케이션은 React, Bun, Hono, PostgreSQL로 구축되었습니다.

새로 설치한 환경은 의도적으로 비어 있습니다. 개인 스킬, 사용자 계정, 클라이언트 키, 외부 서비스 엔드포인트 또는 유료 AI 제공업체 자격 증명을 포함하지 않습니다. Skillbox는 스킬 콘텐츠를 배포하지만 업로드된 스킬 코드를 절대 실행하지 않습니다.

주요 기능

버전 관리 편집: 변경 불가능한 리비전, 충돌 감지 및 복원을 지원하며 Markdown과 관련 파일을 편집합니다.
범위 지정 액세스: 스킬 또는 번들 권한이 있는 프로필을 생성하고 생성, 업데이트, 보관 및 제안 권한을 별도로 설정합니다.
철회 가능한 클라이언트: 개별 클라이언트 키를 발급하고 사용량을 검토하며 필요한 경우 향후 액세스를 철회합니다.
MCP 및 CLI 액세스: HTTP MCP를 직접 사용하거나 Node 또는 Bun stdio 브리지를 통해 연결하거나 체크섬 검증과 함께 패키지를 다운로드합니다.
MCP 리소스: 기본 MCP 리소스 목록 및 읽기를 통해 권한이 있고 호환되는 스킬을 노출합니다.
선택적 추천: 자체 Vercel AI Gateway 또는 TypeSafe AI 키와 함께 Jev를 사용합니다.
데이터 이동성: 기본 폴더를 가져오고 내보내며 보호된 백업을 생성하고 데이터를 명시적으로 복원합니다.
자체 호스팅 배포: Docker Compose로 실행하고, 선택적으로 HTTPS를 위해 Caddy를 앞단에 배치하거나 Umbrel 패키지를 준비합니다.

Skillbox는 범위가 지정된 클라이언트를 사용하는 단일 소유자용 자체 호스팅 애플리케이션으로 설계되었습니다. 공개 멀티 테넌트 SaaS 플랫폼이 아닙니다.

사전 요구 사항

권장 설치에는 Compose v2가 포함된 Docker Engine 또는 Docker Desktop과 Linux, macOS 또는 WSL의 Bash가 필요합니다. Docker 기반 설정에서는 호스트에 Bun이나 Node.js를 설치할 필요가 없습니다.

Skillbox 설치 및 시작

저장소를 복제하고 해당 디렉터리로 이동합니다.
```
git clone https://github.com/kitze/skillbox.git
cd skillbox
```
로컬 환경 파일을 생성합니다.
```
bash scripts/skillbox.sh setup
```
이 명령은 고유한 무작위 자격 증명으로 .env를 생성하고 권한을 0600으로 설정하며 기존 파일을 덮어쓰지 않습니다.
Docker 서비스를 시작합니다.
```
bash scripts/skillbox.sh start
```
브라우저에서 http://127.0.0.1:4791을 엽니다.
로컬 .env 파일에서 SKILLBOX_ADMIN_TOKEN을 확인하고 이를 사용해 로그인합니다. 설정 스크립트는 이 토큰을 의도적으로 출력하지 않습니다.

.env를 비공개로 유지하세요. 소유자 토큰은 관리 액세스를 제어하며 저장된 통합 자격 증명을 보호하는 데에도 사용됩니다.

원격 배포

원격 설치에서는 SKILLBOX_ORIGIN을 배포의 HTTPS 오리진으로 설정하고 TLS 리버스 프록시를 구성합니다. 프로덕션 인스턴스를 암호화되지 않은 HTTP로 노출하지 마세요. 지원되는 배포 세부 정보는 저장소의 배포 참고 사항을 확인하세요.

Docker 전용 애플리케이션 설정 없이 로컬 개발

이미 Bun과 PostgreSQL 16 이상 데이터베이스가 있다면 종속성을 설치하고 애플리케이션을 직접 시작할 수 있습니다.

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

필수 값 세 가지를 모두 소스 관리 시스템에 커밋하지 말고 보호된 환경에 저장하세요.

스킬 및 범위가 지정된 클라이언트 생성

로그인한 후 편집기에서 스킬을 생성하거나 기존 스킬 패키지를 가져옵니다. 스킬 리비전은 변경할 수 없으므로 클라이언트는 변경되는 콘텐츠에 의존하지 않고 특정 리비전을 로드하거나 가져올 수 있습니다.

그다음 프로필을 생성하고 필요한 스킬 또는 번들에 대한 액세스 권한을 부여합니다. 클라이언트의 목적에 따라 생성, 업데이트, 보관 및 제안 권한을 독립적으로 지정합니다. 마지막으로 해당 프로필을 사용해 클라이언트 연결을 생성합니다.

클라이언트 키는 한 번만 표시되며 Skillbox에는 해시만 저장됩니다. 각 키를 즉시 보호된 클라이언트 구성에 저장하세요. 소유자 토큰을 배포하지 말고 클라이언트마다 별도의 키를 사용하세요.

CLI 구성

CLI는 Skillbox URL과 클라이언트 키가 포함된 JSON 구성을 읽습니다. 기본 경로는 ~/.config/skillbox/config.json입니다.

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

파일 권한을 0600으로 설정하세요. 환경 변수 SKILLBOX_URL과 SKILLBOX_TOKEN은 구성 파일의 값을 재정의합니다. URL이 구성되지 않은 경우 CLI는 다른 사람의 서비스를 대상으로 하지 않고 안전하게 localhost를 대상으로 합니다.

cli/skillbox.mjs와 cli/package.mjs를 함께 보관하세요. 그러면 권한이 부여된 스킬을 탐색하고 가져올 수 있습니다.

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

fetch 작업은 파일을 원자적으로 작성하기 전에 경로, 파일 해시, 크기, 실행 가능 플래그 및 패키지 체크섬을 검증합니다. 코드를 실행하거나 종속성을 설치하지 않습니다.

업데이트된 스킬 게시

업데이트하려는 리비전을 예상 리비전으로 지정하여 로컬 폴더를 게시합니다.

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

예상되는 리비전은 충돌 감지를 지원합니다. 게시하려면 클라이언트 프로필에 부여된 권한도 필요합니다.

감사 호환성

소유자는 변경을 수행하지 않는 호환성 감사를 실행할 수 있습니다.

node cli/skillbox.mjs audit

호환되지 않는 패키지를 찾으면 명령이 상태 코드 1로 종료됩니다. 이 명령을 사용하면 기존 패키지를 다시 작성하지 않고 MCP Skills 호환성을 평가할 수 있습니다.

MCP를 통해 AI 에이전트 연결

bootstrap/SKILL.md를 에이전트의 skills-library 부트스트랩으로 설치합니다. HTTP MCP를 지원하는 클라이언트는 인스턴스의 /mcp 엔드포인트에 연결하고 클라이언트 키를 bearer 토큰으로 보낼 수 있습니다.

Authorization: Bearer YOUR_CLIENT_KEY

stdio가 필요한 MCP 클라이언트의 경우 포함된 브리지를 구성합니다.

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

기본 MCP 도구에는 search_skills, recommend_skills, load_skill, read_skill_file, report_skill_use가 포함됩니다. 쓰기 및 제안 도구는 클라이언트 프로필에 해당 권한이 부여된 경우에만 노출됩니다.

Skillbox는 기본 MCP의 resources/list 및 resources/read를 통해 권한이 부여된 호환 스킬도 제공합니다. 지원되는 바이너리 파일과 대용량 파일은 리소스로 액세스할 수 있지만, 리소스를 읽는다고 해서 스킬이 활성화되거나 실행되지는 않습니다.

전체 io.modelcontextprotocol/skills 지원은 아직 제공된다고 공표되지 않았습니다. 현재 구현은 기본 MCP 프로토콜을 통해 준비 기능을 제공하며, 네이티브 검색 및 협상은 여전히 SDK와 프로토콜 업그레이드에 따라 달라집니다.

검색 및 추천을 올바르게 사용

작업을 시작할 때 에이전트는 관련 있고 권한이 부여된 스킬의 목록을 확인하기 위해 계속해서 search_skills를 호출해야 합니다. 추천은 검색을 보완하는 기능이며 검색 단계를 대체하지 않습니다. 선택한 스킬을 적용하기 전에 Skillbox가 반환한 변경 불가능한 리비전을 사용해 해당 스킬을 로드합니다.

외부 추천 제공자가 없으면 CLI에서 검색할 수 있습니다.

node cli/skillbox.mjs search "database migration"

작업을 고려한 추천을 요청하려면 다음을 실행합니다.

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

이에 해당하는 MCP 작업은 recommend_skills({task, limit?, offset?})입니다. HTTP 클라이언트는 동일한 인증 JSON 본문을 POST /api/skill-recommendations로 보낼 수 있습니다.

선택적 Jev 추천 구성

Settings → Jev recommendations를 엽니다.
기본값인 Vercel AI Gateway 또는 TypeSafe AI를 선택합니다.
선택한 제공자의 API 키를 직접 입력하고 저장합니다.

제공자 키는 별도로 저장됩니다. TypeSafe를 선택해도 저장된 Gateway 키가 TypeSafe로 전송되지 않으며, 제공자를 전환해도 이전에 저장한 키가 유지됩니다. 선택한 제공자의 키를 삭제하면 해당 제공자의 모델 호출이 비활성화됩니다.

키는 SKILLBOX_ADMIN_TOKEN에서 파생된 키 자료를 사용해 AES-256-GCM으로 PostgreSQL에 암호화되어 저장됩니다. 키는 설정 API에서 반환되지 않으며 브라우저 번들에도 포함되지 않습니다. 문서화된 로테이션 절차를 따르지 않고 소유자 토큰을 변경하면 저장된 통합 자격 증명을 읽을 수 없게 됩니다.

키를 저장해도 제공자 액세스나 크레딧 구매가 확인되지는 않습니다. Jev는 작업 텍스트와 권한이 부여된 활성 스킬의 설명을 선택한 제공자에 보내므로 해당 제공자의 결제 및 데이터 처리 약관이 적용됩니다.

데이터 가져오기, 내보내기 및 백업

Bun을 사용할 수 있다면 다음 명령으로 스킬 폴더를 가져옵니다.

bun scripts/import.ts /path/to/skills

가져오기는 파일 바이트와 알 수 없는 frontmatter를 보존하고, 심볼릭 링크와 런타임 아티팩트를 건너뛰며, 식별 가능한 비밀 패턴을 격리합니다. 이 감지는 휴리스틱이므로 완전한 비밀 감사의 대체 수단이 아닙니다. 스킬 패키지에 비밀번호나 토큰을 절대 넣지 마세요.

비어 있는 대상에 스킬 콘텐츠를 내보냅니다.

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

PostgreSQL 데이터베이스가 계속해서 단일 진실 공급원 역할을 합니다. 내보낸 폴더를 편집해도 콘텐츠를 다시 게시하기 전까지 데이터베이스는 변경되지 않습니다.

보호된 백업을 생성합니다.

bash scripts/backup.sh

내보내기 파일과 백업에는 비공개 스킬 콘텐츠가 포함될 수 있습니다. 이를 공개 애플리케이션 소스와 분리해 보관하세요. 선택적 GitHub 내보내기 스크립트를 사용하려면 전용 비공개 내보내기 체크아웃을 명시적으로 구성해야 하며, 자동으로 활성화되지 않습니다.

고급 운영 팁

통합마다 클라이언트 키 하나 사용

키를 분리하면 폐기와 사용량 보고를 더 유용하게 수행할 수 있습니다. 키를 폐기하면 이후 요청은 차단되지만, 클라이언트가 이미 다운로드한 파일을 회수할 수는 없습니다.

범위를 좁게 설정한 프로필 우선 사용

각 에이전트에 필요한 스킬과 작업만 부여하세요. 번들은 현재 리프 스킬로 확장된 후 중복이 제거되지만, 참조만으로는 액세스 권한이 부여되지 않습니다.

소유자 토큰과 백업 보호

소유자 토큰은 관리 액세스를 제공하며 저장된 통합 자격 증명의 암호화 자료를 생성합니다. 데이터베이스 및 구성 백업과 함께 안전하게 보호하고, 토큰을 교체하기 전에 문서화된 로테이션 절차를 따르세요.

스킬을 신뢰할 수 있는 프로그램이 아닌 콘텐츠로 취급

Skillbox는 패키지 파일을 실행하지 않고 검증하고 배포합니다. 에이전트 워크플로에서 사용하기 전에 다운로드한 지침과 코드를 계속 검토하세요.

배포 또는 기여 검증

변경 사항을 배포하기 전에 타입 검사와 격리된 테스트 모음을 실행하세요.

bun run typecheck
bash scripts/test-isolated.sh

격리된 테스트 모음은 데이터베이스 포트를 공개하지 않고 자체 Docker Compose PostgreSQL 인스턴스를 생성하고 제거합니다. 인증, 리비전, API 및 MCP 동작, CLI, 암호화된 설정, 추천 기능을 다룹니다. 데이터베이스 테스트를 프로덕션에 연결하지 마세요.

결론

Skillbox는 재사용 가능한 AI 에이전트 스킬을 관리하기 위한 통제된 셀프 호스팅 워크플로를 제공합니다. Docker 설정으로 시작하고, 버전이 지정된 스킬을 만들고, 범위를 좁게 설정한 프로필을 할당한 다음, 각 에이전트를 전용 클라이언트 키로 연결하세요. 이후 카탈로그와 자격 증명에 대한 소유권을 유지하면서 MCP 액세스, 선택적 Jev 추천, 이식성 워크플로, 백업을 추가할 수 있습니다.