beautyfree/skiller-desktop-skills-manager

Skiller — 에이전트 가이드

Skiller는 다양한 AI 에이전트(Claude Code, Cursor, Copilot CLI 등)의 AI 에이전트 스킬을 설치, 동기화, 편집할 수 있는 크로스 플랫폼 데스크톱 앱(Electron)입니다. Bundle ID: com.beautyfree.skiller.

스택

레이어	기술
메인 / 네이티브	Electron (src/electron-main/index.ts), Node 20
UI	React 19, Vite 7 (루트 src/mainview), Tailwind CSS 4, react-router-dom
API	127.0.0.1에서 HTTP 기반 tRPC + 메인→렌더러 이벤트용 ipcMain 푸시 채널
빌드	electron-vite (개발 + 번들링) + electron-builder (패키징, 서명, 자동 업데이트)
업데이터	electron-updater (GitHub Releases, latest-*.yml + 블록맵)

저장소 구조

경로	역할
src/electron-main/	Electron 메인 프로세스: BrowserWindow, 트레이, tRPC 서버, macOS vibrancy, 플랫폼 어댑터
src/preload/	contextBridge — window.api.{invoke,on,platform}을 렌더러에 노출
src/main/	플랫폼 독립적인 메인 측 코드: 스킬 와쳐, tRPC 라우터, 마켓플레이스 캐시, 앱 업데이터 래퍼, 설정, 스캐너
src/mainview/	Vite 앱: App.tsx, 페이지, 컴포넌트, index.html, CSS 토큰
src/shared/	메인과 렌더러가 공유하는 타입 / RPC 스키마 (AppPlatform 인터페이스 포함)
agents/	번들된 에이전트 메타데이터 (electron-builder.yml의 extraResources를 통해 앱에 복사됨)
assets/icons/	런타임 아이콘: AppIcon.iconset/, app.icns, app.ico, app/icon-512.png
assets/icons/Skiller.icon/	소스 전용 (Icon Composer): scripts/build-app-icons.py가 icon.json을 통해 Assets/Image.png를 읽음
build-resources/	Hardened Runtime용 entitlements.mac.plist
scripts/	build-app-icons.py, normalize-skiller-icon-layer.py, repack-dmg.sh
docs/DEVELOPMENT.md	설정, HMR, 서명, CI, DMG 재패키징 — 릴리스/서명을 변경하기 전에 반드시 읽으세요
DESIGN.md	UI 토큰 및 제품 디자인 노트

AppIcon.iconset/, app.icns, app.ico, app/icon-512.png 아래 생성된 아이콘은 직접 편집하지 마십시오 — 소스에서 다시 생성하세요(아래 참조).

명령어

bun install

개발

• bun run dev — electron-vite 개발: main + preload를 감시하고, Vite를 포트 5180에서 렌더러용으로 HMR과 함께 실행합니다. Vite URL을 로드하는 Electron 창을 엽니다.
• bun run dev:debug — AGENTSKILLS_DEVTOOLS=1로 dev와 동일 (렌더러 DevTools가 열릴 때 자동 실행).

검사

• bun run typecheck — 렌더러의 경우 tsc --noEmit, main/preload의 경우 tsc -p tsconfig.node.json --noEmit 실행.

프로덕션 번들 (웹 + main + preload)

• bun run build — electron-vite build → out/{main,preload,renderer}/. electron-builder에서 사용.

플랫폼 설치 프로그램 (대상 OS에서 실행; electron-builder는 네이티브 모듈을 크로스 컴파일하지 않음)

• bun run dist:mac — electron-vite build && electron-builder --mac && bash scripts/repack-dmg.sh
• bun run dist:win — electron-vite build && electron-builder --win
• bun run dist:linux — electron-vite build && electron-builder --linux

서명 환경 변수 및 아티팩트 위치는 docs/DEVELOPMENT.md를 참조하세요.

아이콘

1. 정식 레이어 편집: assets/icons/Skiller.icon/Assets/Image.png (선택 사항: python3 scripts/normalize-skiller-icon-layer.py 실행)
2. 플랫폼 에셋 다시 생성: python3 scripts/build-app-icons.py AppIcon.iconset/, app.ico, app.icns, app/icon-512.png를 새로고침합니다. macOS DMG 스타일링은 scripts/repack-dmg.sh를 통해 assets/icons/app.icns를 사용합니다.

에이전트 컨벤션

• 스크립트 및 로컬 실행에는 Bun을 사용하세요 (bun, bunx). Electron 메인은 Node(내장 Node 20)에서 실행되므로 Node 호환 API만 사용하세요.
• UI 문자열 (사용자 대상 텍스트): src/mainview/i18n/ 아래에 키를 추가하고 (영어는 en.ts), 코드 주석은 영어로 유지하세요.
• 기존 패턴을 따르세요: src/mainview에서 @/ 임포트 사용 (electron.vite.config.ts / tsconfig.json 참조).
• 범위 확장을 피하세요: 작업이 명시적으로 요구하지 않는 한 node_modules/ 또는 관련 없는 마케팅 전용 경로를 변경하지 마세요.
• RPC 또는 공유 타입 변경 후에는 main 핸들러(src/main/rpc-handlers.ts)와 렌더러 호출자가 일관성을 유지하는지 확인하세요 (src/shared/ 또는 로컬 스키마 모듈).
• 네이티브 Node 모듈(better-sqlite3)은 Electron의 ABI에 맞게 재빌드하기 위해 electron-builder install-app-deps가 필요합니다. bun install만으로는 되지 않습니다.

환경 변수 (일부 목록)

변수	용도
AGENTSKILLS_TRPC_PORT	tRPC HTTP 포트 (기본값 17888; 충돌 시 +48로 fallthrough)
AGENTSKILLS_DEVTOOLS	렌더러 DevTools를 실행 시 자동으로 열기 (개발 전용)
AGENTSKILLS_DISABLE_WINDOW_BLUR	1 → macOS에서 설정이 켜져 있어도 강제로 vibrancy 비활성화
CSC_NAME, APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID	macOS 서명 + 공증. docs/DEVELOPMENT.md 참조.

추가 자료

• README.md — 제품 개요 및 설치 링크.
• docs/DEVELOPMENT.md — 개발, DMG, 업데이터, GitHub Actions 릴리스, docs/ 랜딩 페이지용 GitHub Pages.