Skillcaddy
English · 中文
로컬 AI 스킬 중앙 라이브러리 + 범위 지정 심볼릭 링크 활성화 기능입니다. 하나의 AISkills 디렉터리가 모든 스킬 소스를 담고 있으며, 필요한 것을 프로젝트, 공유 사용자 레벨 Agents 디렉터리 또는 Hermes에 필요할 때만 심볼릭 링크로 연결합니다.
Skillcaddy를 사용하는 이유?
여러 프로젝트에서 Claude Code, Codex, OpenCode, Pi 등을 사용한다면 결국 다음과 같은 문제 중 하나에 직면하게 됩니다:
- 동일한 스킬이 세 개의 리포지토리에 각각 존재하며, 매번 약간씩 다릅니다.
- 새로운 프로젝트가 생길 때마다 스킬을 복사하고 어떤 버전이 최신인지 궁금해합니다.
- 상위(upstream) 스킬이 업데이트되었지만 로컬 사본은 몇 주나 뒤처져 있습니다.
- Claude Code 전용 항목이 agents 측 목록과 공존해야 합니다.
- 보관된(archived) 스킬이 아무도 막지 않아 다시 사용되는 경우가 생깁니다.
Skillcaddy는 하나의 AISkills 디렉터리를 진실의 원천(source of truth)으로, 명시적인 프로젝트/전역/Hermes 심볼릭 링크 범위를 전달 메커니즘으로 사용하여 이 문제를 해결합니다.
- 하나의 진실의 원천 —
~/AISkills/가 official / github / personal / archived / skills를 통합합니다.
- 프로젝트 오염 제로(Zero project pollution) —
.agents/skills/에 심볼릭 링크로 활성화하며, 절대 복사하지 않습니다.
- 프로젝트 또는 전역 범위 — 프로젝트 링크는 로컬에 유지되며, 전역 링크는
~/.agents/skills/로만 연결됩니다.
- 독립적인 Hermes 범위 —
official/github/personal 스킬은 명시적으로 ~/.hermes/skills/에 링크하며, HERMES_HOME을 무시하고 프로젝트/전역 범위를 변경하지 않습니다.
- 기본 다중 에이전트(Multi-Agent by default) — 하나의 심볼릭 링크가 표준 경로를 통해 Claude Code, Codex, OpenCode, Pi에 도달합니다.
- 독립적인 활성화/비활성화 — agents 측과 Claude Code 측은 별도로 추적됩니다.
- 기본 안전성(Safe by default) — 비활성화는 심볼릭 링크만 제거할 뿐입니다.
archived/는 명시적인 이름 지정이 필요합니다.
- 기여하기 쉬움(Contribute-friendly) — 새로운 스킬은
skills/<name>/ 아래에 SKILL.md + agents/openai.yaml과 함께 배치되며, 리포지토리에 포함되어 배포됩니다.
개인적으로 수많은 저장소(repo)를 가진 개발자이든, 공유 스킬을 표준화하려는 소규모 팀이든, 또는 재사용 가능한 것을 출판하는 작가이든 — 계약은 동일합니다: 스킬은 특정 프로젝트에 속하는 것이 아니라 당신의 라이브러리에 속해야 합니다.
설치 (Installation)
git clone https://github.com/chenweil/skillcaddy.git
cd skillcaddy
npm install
...
Node.js >= 20이 필요합니다. 웹 관리자(web manager)는 고정된 기본 URL http://127.0.0.1:4173을 사용합니다. 페이지에서 대상 프로젝트 경로를 채우고, 스킬을 활성화/비활성화하세요. 만약 해당 포트가 일시적으로 점유되어 있다면, PORT=<다른-포트> npm start로 시작하세요.
번들된 spec-pipeline 스킬 (Bundled spec-pipeline skills)
이 저장소는 docs/research/0037에서 설명한 방향 확인 게이트(direction-confirmation gate)를 구현하는 skills/spec-pipeline/ 아래의 세 가지 스킬을 제공합니다. 이들은 git에 추적되므로 클론에는 내용이 포함되어 있지만, 설계상 프로젝트 활성화 링크는 포함되어 있지 않습니다: ADR 0011 Decision 4는 프로젝트 활성화를 라이브러리 이미지에서 제외합니다 (lib/libraryImage.js는 global 및 hermes 트리플만 담고 있습니다). 체크아웃할 때마다 링크를 다시 생성해야 합니다:
npm run enable:spec-pipeline
npm run enable:spec-pipeline -- --dry-run
그런 다음 이 저장소의 모든 spec이 게이트를 만족하는지 확인하세요:
두 명령어 모두 반복 실행해도 문제가 없습니다(idempotent). check:specs는 또한 npm test의 일부입니다. specs/ 디렉토리가 없는 저장소는 통과하며, --strict 옵션은 이를 반전시킵니다.
Web 라이브러리는 프로젝트, 전역(global), 그리고 Hermes 활성화 기능을 독립적으로 유지합니다. 스킬을 전역으로 활성화한다고 해서 해당 스킬의 프로젝트 액션이 비활성화되는 것은 아닙니다. 즉, 특정 프로젝트가 자체 설정, Claude Code 동기화 또는 명시적인 프로젝트 레벨 우선순위가 필요할 때 동일한 스킬을 현재 프로젝트에 추가할 수 있습니다. 컬렉션 액션은 별도의 프로젝트/전역/Hermes 진행 상황을 보여주며, 텍스트 검색은 일치하는 컬렉션을 확장하여 표시하고, 소스 및 태그 필터는 간결한 탐색을 위해 컬렉션을 접힌 상태로 유지합니다. 활성화된 패널에서는 프로젝트 에이전트(Agents)와 Claude Code를 나란히 채널 슬롯으로 보여주며, 그 아래에는 전체 너비의 전역 및 Hermes 슬롯이 있습니다. 공유된 활성화 스킬 검색 기능은 긴 목록을 스크롤할 필요 없이 이름이나 소스를 찾을 수 있게 해줍니다.
Global CLI / TUI 명령어
이 저장소에서 클론 기반 명령어를 전역으로 설치합니다 (로컬 npm link를 사용하며, npm 패키지를 다운로드하지 않습니다):
npm run install:cli
npm run check:cli
설치된 skillcaddy 명령어는 CLI와 TUI 모두를 제공합니다. 이전의 install:tui / check:tui 이름은 호환성 별칭으로 남아 있습니다. 또한 클론에서 npm run tui -- install cli를 실행하거나, TUI 내부에서 '11. 설치/확인 전역 CLI + TUI 명령어'를 선택할 수도 있습니다.
로컬 CLI/TUI 명령어를 한 번 연결한 후에는 동일한 진입점(entry point)이 웹 서버를 관리하고 모든 프로젝트의 스킬을 검사하거나 업데이트할 수 있습니다:
skillcaddy start [projectPath]
skillcaddy stop
skillcaddy restart [projectPath]
...
-a는 읽기 전용(read-only)이며 소스 폴더를 생성하거나, 설치하거나, 활성화하거나 메타데이터를 작성하지 않습니다. -u는 기존의 fast-forward 전용 Git 소스 업데이트 흐름을 재사용하며 명시적인 현재 프로젝트 경로가 필요합니다. 글로벌 링크도 동일한 업데이트에서 확인됩니다. start는 이미 실행 중인 Web 프로세스를 재사용하고, stop과 restart는 Skillcaddy 소유권을 확인할 수 있는 프로세스에 대해서만 작동하므로 포트에 외부 서비스가 있어도 종료되지 않습니다. --root는 소스 및 분석 작업을 위한 중앙 라이브러리를 선택하며, Web 생명주기(lifecycle) 명령어는 실행 파일을 제공하는 클론을 사용합니다. 인자 없이 skillcaddy를 실행하면 여전히 TUI가 열립니다.
프로세스 소유권 검사(process-ownership probe)가 없는 플랫폼에서는 Web stop/restart가 어떤 프로세스를 종료할지 추측하는 대신 실패하여 닫힙니다(fail closed).
아직 글로벌 명령을 연결하고 싶지 않다면, 리포지토리 로컬 엔트리에서 동일한 명령어를 지원합니다:
npm run tui -- start --no-open
npm run tui -- stop
npm run tui -- -a /path/to/project
터미널 UI (TUI)
대화형 터미널 관리자를 사용하려면 다음을 실행합니다:
npm run tui -- /path/to/project
npm run tui -- --root ~/AISkills /path/to/project
모든 프로젝트에서 클론된 라이브러리를 사용하려면, CLI/TUI 명령을 한 번 연결해야 합니다:
npm run install:cli
npm run check:cli
...
install:cli는 로컬 npm link를 사용합니다. npm 레지스트리에서 Skillcaddy를 다운로드하거나 복사하지 않습니다. 글로벌 skillcaddy 명령어는 이 클론에 계속 연결되어 있으며, 이는 중앙 라이브러리로 남아있고 git pull로 업데이트할 수 있습니다. 인자 없이 skillcaddy를 실행하면 현재 디렉토리를 관리하며, skillcaddy /path/to/project는 다른 프로젝트를 선택합니다. 설치 프로그램은 다른 클론에 연결된 글로벌 skillcaddy 패키지를 대체하는 것을 거부합니다.
TUI는 브라우저가 필요 없이 완전한 키보드 기반 인터페이스를 제공합니다.
- 활성화된 스킬 보기 (View enabled skills) — 에이전트(Agents)와 Claude Code 열을 나란히 표시합니다.
- 스킬 라이브러리 탐색/검색 (Browse/search skill library) — 키워드 검색, 소스 필터, 라이브러리 드릴다운 기능을 제공합니다.
- 스킬 활성화 (Enable skill) —
.agents/skills/에 심볼릭 링크(symlink)를 생성하고 Claude Code를 자동 동기화합니다.
- 전역으로 활성화 (Enable globally) — 프로젝트가 필요하지 않은 경우에도
~/.agents/skills/ 아래에 명시적인 공유 링크를 추가합니다.
- 활성화된 스킬 정리 (Clear enabled skill) — 프로젝트 심볼릭 링크만 제거하며, 소스는 안전하게 유지됩니다.
- 전역 스킬 관리 (Manage global skills) — 옵션 13은
~/.agents/skills/ 아래에 있는 이 중앙 라이브러리가 소유한 링크를 검사하고, 활성화하며, 안전하게 제거하는 기능을 제공합니다.
- Hermes 스킬 관리 (Manage Hermes skills) — 옵션 14는
~/.hermes/skills/ 아래에서 적격한 링크들을 명시적으로 검사하고, 활성화하며, 안전하게 제거하는 기능을 제공합니다.
- Claude Code 동기화 (Sync Claude Code) —
.claude/skills/를 .agents/skills/와 원클릭으로 동기화합니다.
- 메타데이터 편집 (Edit metadata) — 스킬별 인라인 노트, 태그, 자동 활성화 토글을 제공합니다.
- 진단 보기 (View diagnostics) — 중복 항목, 깨진 링크, 소스 이탈(source drift)에 대한 조언을 제공합니다.
- 컬렉션 설정 추적 (Track collection setup) — 활성화된 링크와 프로젝트 준비 상태의 구성을 구분하고 대화형 설정을 안내합니다.
- 중복 이름 해결 (Resolve duplicate names) — 소스를 이름을 변경하지 않고 제안되거나 사용자 지정한 프로젝트 별칭(alias) 아래에 선택된 소스 스킬을 활성화할 수 있습니다.
- 프로젝트 새로고침 (Refresh project) — 상태를 다시 로드하고 프로젝트 경로를 전환합니다.
- GitHub 소스 업데이트 (Update GitHub sources) —
github/ 리포지토리를 일괄적으로 패스트 포워드(fast-forward) 풀합니다.
- 일괄 중국어 노트 처리 (Batch Chinese notes) — 영어 설명만 있는 스킬의 누락된 중국어 '노트' 필드를 채우기 위한 대화형 흐름(옵션 10)입니다.
- 전역 명령어 설치/확인 (Install/check the global command) — 옵션 11은 이 클론에서 CLI + TUI 명령어를 설치합니다.
- 원격 소스 확보 (Acquire remote sources) — 중앙 라이브러리에 완전한 HTTPS/SSH/SCP Git 리포지토리, 공개 HTTP(S) ZIP 파일 또는 안정적인 직접 HTTP(S)
/SKILL.md 파일을 추가하는 기능입니다.
이제 라이브러리 브라우징은 스킬들을 간결한 페이지네이션 테이블로 보여줍니다 (n/p를 눌러 페이지 이동, a는 일괄 활성화). 스킬 소개 시에는 메타데이터의 note 필드를 원본 영어 description보다 우선하여 사용합니다.
메뉴 탐색은 액션을 위해 숫자 키(1-14)를 사용하고, /키워드로 검색하며, b는 뒤로 가기, q는 종료합니다. 빠른 터미널 워크플로우나 헤드리스 환경에 이상적입니다.
모든 프로젝트의 AI 에이전트가 번들된 skillcaddy-manager 스킬을 사용할 수 있도록 하려면, 전역 진입점(global entry)을 한 번 설치해야 합니다:
npm run install:manager
npm run check:manager
이렇게 하면 ~/.agents/skills/skillcaddy-manager에 관리되는 심볼릭 링크(symlink)가 생성되며, 이는 skills/skillcaddy-manager를 가리킵니다. 이 과정은 다른 곳을 가리키는 기존 파일, 디렉터리 또는 심볼릭 링크를 덮어쓰지 않습니다.
또한 URL을 통해 프로젝트 경로를 전달할 수도 있습니다:
해당 페이지가 즉시 프로젝트를 로드하고, 최근 사용된 프로젝트 경로는 브라우저 로컬 히스토리에 유지하며, 라이브러리 수준의 + 버튼을 사용하여 사용 가능한 모든 스킬을 일괄 활성화할 수 있게 합니다. 활성화된 패널은 프로젝트 에이전트(Agents), Claude Code, 전역 에이전트(global Agents), 그리고 Hermes를 명시적인 채널 슬롯에 그룹화하고, 활성화된 항목 전체에서 하나의 공유 검색 기능을 제공합니다. 만약 라이브러리가 실수로 활성화되었다면, 라이브러리 수준의 × 버튼을 사용하여 해당 라이브러리를 Agents와 Claude Code 양쪽 모두에서 정리할 수 있습니다.
스킬 메타데이터
SKILL.md는 에이전트가 참조하는 계약(contract)으로 유지됩니다. 사용자 친화적인 메모 및 분류 정보는 Skillcaddy에 의해 .skillcaddy/metadata/.../skillcaddy.json에 저장되어 외부 소스 레포지토리가 깔끔하게 유지되도록 합니다:
{
"note": "실행을 체계적으로 관리하기 위해 코드 변경 전후에 유용합니다.",
"tags": ["개발자 도구", "품질", "워크플로우"]
...
}
런타임 스캔과 웹 UI는 로컬 사이드카(sidecar) 저장소에서만 메타데이터를 읽습니다. 태그는 필터 탭 및 배지 형태로 표시되며, 메모는 각 스킬 카드에 표시됩니다. autoEnable을 false로 설정하면, 라이브러리 수준의 일괄 활성화 시 사용 중단되었거나 위험할 수 있는 스킬이 제외되지만 여전히 단일 스킬의 수동 활성화는 가능합니다. 이는 상위 소스 레포지토리를 깔끔하게 유지하면서도 대규모 로컬 스킬 라이브러리를 탐색하기 쉽게 만듭니다.
v0.15.0부터는 일반 런타임 스캔이 레거시 <skill-dir>/skillcaddy.json 파일을 무시합니다. 마이그레이션 명령어는 해당 파일을 명시적으로 발견하며, v0.15.x를 통해 계속 사용할 수 있지만 v0.16.0에서는 제거됩니다. 다음 명령어로 미리 확인하고 마이그레이션을 적용하세요:
npm run migrate:metadata
npm run migrate:metadata -- --yes
적용 명령어는 동등한 사이드카(sidecar) 메타데이터를 작성하고 롤백을 위해 레거시 파일을 유지합니다. 런타임 동작 변경은 사이드카가 작성된 후에만 발생합니다.
컬렉션 설정 라이프사이클
일부 컬렉션은 스킬이 활성화된 후 프로젝트별로 한 번의 초기 설정을 필요로 합니다. Skillcaddy는 이러한 계약(contracts)을 collection-metadata/<source>/<collection>.json 아래에 서드파티 클론 외부로 유지합니다. /api/state는 구성된 각 컬렉션을 missing, partial, ready, 또는 invalid로 보고합니다. 전역 활성화(Global enablement)는 절대 실행되거나 프로젝트 설정을 요청하지 않습니다.
라이브러리 수준의 활성화는 공유 계획을 적용하기 위해 명시적인 scope(project, global, 또는 hermes)를 사용하여 POST /api/enable-plan 및 POST /api/enable-collection을 사용합니다. 프로젝트 범위(Project scope)에는 선언된 설정 가이드가 포함되며, 전역 범위는 ~/.agents/skills 링크만 생성하고, Hermes 범위는 official, github, 및 personal 스킬을 수용하며 ~/.hermes/skills/ 아래에 직접적인 링크를 생성합니다. 하나의 라이프사이클은 모든 후보를 enabled, unchanged, skipped, 또는 failed로 분류합니다. 활성화 링크는 계속 허용되지만, 불완전한 프로젝트 컬렉션은 ready가 아닌 pending으로 표시됩니다. 대화형 설정(Interactive setup)은 절대 조용히 실행되지 않으며, 컬렉션 메타데이터는 실행 가능한 셸 명령을 제공할 수 없습니다.
플랫폼 호환성
| Platform | Status | Notes |
|---|
| macOS | ✅ Fully supported | Native directory symlinks |
| ... | | |
Windows 전제 조건
Skillcaddy는 Node의 fs.symlink(..., 'dir')를 통해 디렉토리 심볼릭 링크를 생성합니다. Windows에서 이 호출은 다음 중 하나가 필요하거나 EPERM 오류를 발생시킵니다:
