yongkyu4803 Universal Install
초보자가 "안 되는데요"라고 말할 때 해결해주는 스킬이다.
클로드는 환경마다 확장 기능 저장소가 다르다. 코워크에서 만든 스킬이 클로드 코드에 안 뜨고, 깃헙에서 받은 스킬이 챗에 안 보인다. 숙련자는 "찾아서 여기 깔아줘"라고 말할 줄 알지만, 초보자는 그게 가능한 줄도 모르고 포기한다. 그 간극을 메우는 것이 이 스킬의 목적이다.
입구는 네 가지다
사용자가 무슨 말을 하든 아래 중 하나로 분류해서 처리한다.
| 사용자가 하는 말 | 무엇을 할 것인가 |
|---|---|
| "이 깃헙 주소 설치해줘" | 1~5단계 설치 흐름 |
| "코워크(챗)에서 만든 건데 코드에서 안 보여" | sync.py — 클릭 0회로 해결 |
| "설치했는데 안 뜨는데요" | sync.py list / locate 로 진단 먼저 |
| "내 스킬 뭐뭐 있어?" | sync.py list |
| "코드에서 깐 게 코워크/챗에서 안 열려" | 먼저 새로고침·재시작, 안 되면 zip 안내 |
진단을 먼저 한다. "안 보인다"는 말에 바로 재설치부터 하지 않는다. 어디에 있고 어디에 없는지부터 확인하면 대개 복사 한 번으로 끝난다.
먼저 — 지금 내가 어디서 도는지 확인한다
이 스킬은 세 표면 모두에 설치되지만, 실제로 동작하는 건 클로드 코드뿐이다. 코워크는 격리된 VM, 챗은 샌드박스라 사용자 컴퓨터의 파일에 닿지 못한다.
그러므로 파일을 만지기 전에 반드시 먼저 확인한다.
python3 scripts/sync.py env
격리된 환경이 나오면 파일 작업을 시도하지 않는다. 안내만 한다.
스크립트가 알아서 막고 안내문을 출력하므로, 그 내용을 사용자 말투로 옮겨주면 된다.
여기서 절대 하지 말 것: "안 됩니다"로 끝내기. 반드시 다음 행동을 준다.
여섯 방향 전부
"안 보인다"는 불평은 어디서든 나올 수 있다. 방향마다 답이 다르다.
| 어디서 불평하나 | 무엇이 안 보이나 | 답 |
|---|---|---|
| 클로드 코드 | 챗·코워크에서 만든 것 | ✅ 자동 — sync.py pull |
| 클로드 코드 | 깃헙에 있는 것 | ✅ 자동 — 설치 흐름 |
| 코워크 | 클로드 코드에 있는 것 | ⚠️ 여기선 불가 → 코드에서 zip 만들어 업로드 |
| 챗 | 클로드 코드에 있는 것 | ⚠️ 여기선 불가 → 코드에서 zip 만들어 업로드 |
| 코워크 | 챗에 있는 것 | 대개 이미 보임 (계정 공유) — 앱 재시작 먼저 권함 |
| 챗 | 코워크에 있는 것 | 대개 이미 보임 (계정 공유) — 새로고침 먼저 권함 |
아래 두 줄이 중요하다. 챗과 코워크는 같은 계정을 쓰므로 대개 이미 공유된다. "안 보인다"고 하면 재설치를 권하기 전에 새로고침이나 앱 재시작부터 시켜본다. 그것으로 해결되는 경우가 많다.
가운데 두 줄이 진짜 막히는 지점이다. 사용자가 코워크나 챗에 앉아 있고 클로드 코드 스킬을 원하는 상황. 이때 할 일:
- 지금 여기서는 안 된다고 이유와 함께 말한다 (격리된 환경이라 컴퓨터 파일에 못 닿음)
- 클로드 코드를 열고 이렇게 말하라고 알려준다 —
"<이름> 을 챗에서 쓰게 zip 만들어줘" - 클로드 코드가 없는 사람이면, 그 스킬을 여기서 다시 만드는 편이 빠를 수도 있다고 안내한다
표면 간 이동 (클릭 불필요)
데스크톱 앱은 계정의 스킬을 로컬에 내려받아 둔다. 그래서 챗·코워크 → 클로드 코드 방향은 파일 복사만으로 해결된다. 사용자가 웹에서 뭘 누를 필요가 없다.
python3 scripts/sync.py list # 어디에 무엇이 있는지 표
python3 scripts/sync.py gap # 한쪽에만 있는 것
python3 scripts/sync.py pull <이름> # 챗/코워크 → 클로드 코드
python3 scripts/sync.py pull --all # 없는 것 전부
python3 scripts/sync.py locate <이름> # 어디 있는지 찾기
pull 후에는 "다음 세션부터 보입니다" 라고 알려준다. 지금 당장은 안 뜬다.
반대 방향(클로드 코드 → 챗·코워크)은 파일 복사로 안 된다. 계정에 넣어야 하고 계정에 쓰는 통로는 화면뿐이다. 그때는 zip을 만들어주고 클릭 경로를 안내한다.
<주의> 챗/코워크 스킬 저장 위치는 앱 내부 경로라 공식 문서에 없다.
sync.py가 하드코딩하지 않고 탐색하며, 못 찾으면 그렇다고 말한다.
앱이 업데이트되면 사라질 수 있는 경로다. 못 찾았을 때 지어내지 말 것.
대원칙
- 판단은 내가 한다. 갈림길마다 묻지 않는다. 정해진 기본값을 따른다. 진짜 물어야 할 때는 둘뿐이다 — HIGH 보안 경고, 스킬이 여러 개라 고를 때.
- 소유권을 요구하지 않는다. 초보자는 레포를 포크·푸시하지 못한다.
- "안 됩니다"로 끝내지 않는다. 안 되면 이유와 대안을 반드시 같이 준다.
- 전문용어를 사용자에게 던지지 않는다. transport, 프론트매터, 스코프는 내부용이다.
- 거짓말하지 않는다. 확인 전에 "완료"라고 하지 않는다.
0단계 — 사전 점검 (먼저, 조용히)
git --version # 없으면: xcode-select --install 안내
claude plugin marketplace list # CLI 동작 확인
git이 없으면 여기서 멈추고 설치 방법만 알려준다. 나머지는 진행해도 어차피 실패한다.
플랜 제약은 미리 겁주지 말고 해당 단계에서만 언급한다.
- 플러그인 설치는 유료 플랜(Pro/Max/Team/Enterprise) 필요
- 챗 스킬 업로드는 코드 실행(code execution) 켜져 있어야 함
1단계 — 가져오기
git clone --depth 1 <repo-url> <스크래치경로>/<name>
스크래치 디렉토리를 쓴다. 사용자 프로젝트를 어지럽히지 않는다. 클론 실패(오타·비공개 레포)면 주소를 다시 확인해달라고만 한다.
2단계 — 분석
python3 scripts/detect.py <경로>
recommended_path 값이 이후 분기를 결정한다.
| 값 | 의미 | 3단계에서 할 일 |
|---|---|---|
marketplace-asis |
이미 마켓플레이스 | 최선 — 세 표면 모두 같은 URL |
mcp-remote-all-surfaces |
원격 MCP | 코드는 CLI, 챗·코워크는 커넥터 |
mcp-stdio-code-only |
로컬 MCP | 코드 전용 — 이유 설명 |
wrap-into-marketplace |
이식 가능한 스킬 | zip 우선 (아래 참조) |
code-only |
로컬 의존 스킬 | 코드 전용 — 이유 설명 |
ask-user |
애매 | 내용 직접 보고 판단 |
스킬이 여러 개면 이름과 한 줄 설명을 목록으로 보여주고 어떤 걸 원하는지 묻는다. "전부"도 유효한 답이다.
3단계 — 보안 검토
python3 scripts/audit.py <경로>
- HIGH 0건 → 조용히 통과. 사용자에게 보고하지 않는다. (정상 스킬도 MED/LOW는 흔하다)
- HIGH 1건 이상 → 멈춘다. 해당 항목을 쉬운 말로 설명하고 진행 여부를 묻는다. 예: "이 스킬은 인터넷에서 코드를 받아 바로 실행합니다. 만든 사람을 믿을 수 있나요?"
공식 문서 경고다 — 스킬은 임의 코드를 실행시킬 수 있으므로 신뢰할 수 있는 출처만 쓴다.
4단계 — 설치
클로드 코드 (자동, 항상 먼저)
# 마켓플레이스 레포
claude plugin marketplace add <owner/repo>
claude plugin install <plugin>@<marketplace>
# 단독 스킬
cp -r <스킬디렉토리> ~/.claude/skills/<name>/
# 원격 MCP
claude mcp add --scope user --transport http <name> <url>
# 로컬 MCP
claude mcp add --scope user <name> -- <command> [args...]
--scope user가 기본이다. 설치 후 반드시 확인하되, 경로에 따라 명령이 다르다.
| 설치 방식 | 확인 명령 |
|---|---|
claude mcp add 로 직접 추가 |
claude mcp list |
| 플러그인에 번들된 MCP | claude plugin details <plugin> |
| 스킬 / 플러그인 | claude plugin list |
플러그인이 담은 MCP 서버는 claude mcp list에 뜨지 않는다. 별도 스코프이기 때문이다.
(우선순위: local > project > user > plugins > claude.ai 커넥터)
plugin details의 MCP servers (n) 줄로 확인한다. 실측으로 검증된 동작이다.
챗 + 코워크 (사용자 클릭 필요)
경로 선택 — 여기가 핵심이다.
| 상황 | 방법 | 이유 |
|---|---|---|
| 이미 마켓플레이스 | 레포 URL 그대로 | 소유권 불필요, 최선 |
| 그 외 스킬 | zip 생성 | 소유권 불필요 — 초보자 기본값 |
| 원격 MCP | 커넥터에 URL 입력 | 소유권 불필요, 한 단계면 끝 |
| 사용자가 레포 소유자 + 원함 | 마켓플레이스로 감싸기 | 푸시 필요 — 먼저 묻는다 |
원격 MCP는 초보자에게 오히려 쉽다. 파일도 소유권도 필요 없고
Customize > Connectors > + 에 이름과 URL만 넣으면 된다.
플러그인이 MCP를 번들할 수도 있지만(검증됨), 그건 레포 소유자에게만 해당한다.
python3 scripts/package.py zip <스킬디렉토리> --out <스크래치>/<name>.zip
감싸기(--wrap)를 기본값으로 쓰지 않는다. 레포 수정과 푸시가 필요해 초보자가 막힌다.
사용자가 그 레포의 주인이고 명시적으로 원할 때만 제안한다.
5단계 — 사용자에게 보여줄 것
이 형식을 지킨다. 표 하나와 할 일 목록.
✅ 클로드 코드 — 설치 완료. 바로 쓸 수 있습니다.
남은 작업 (각 1분):
챗에서 쓰려면
1. claude.ai 열기
2. 왼쪽 Customize > Skills > Add
3. 이 파일 올리기: <zip 전체 경로>
코워크에서 쓰려면
같은 파일을 코워크 앱에서 한 번 더 올리면 됩니다.
(챗과 코워크는 저장소가 따로라 각각 올려야 합니다)
마켓플레이스 경로일 때는 3번을 Customize > Plugins > + > Add marketplace > Add from a repository 에 레포 URL 붙여넣기로 바꾼다.
zip 파일은 전체 경로를 그대로 보여준다. 사용자가 드래그할 수 있어야 한다.
macOS면 open -R <경로> 로 파인더에서 열어줄 수 있다.
못 가는 경우는 이유를 한 문장으로. 예:
이 MCP 서버는 내 컴퓨터에서 프로그램을 직접 실행하는 방식이라 챗에서는 쓸 수 없습니다. 챗은 Anthropic 서버에서 접속하기 때문에, 인터넷에 공개된 주소가 있어야 합니다.
알아둘 것
스킬은 표면 간 동기화되지 않는다. 공식 문서 명시 사항이다.
클로드 코드의 ~/.claude/skills/, 챗 업로드, 코워크 업로드는 각각 별개 저장소다.
"한 번 올리면 다 된다"는 없다. 플러그인 마켓플레이스만이 같은 소스를 공유한다.
챗·코워크의 MCP는 Anthropic 클라우드에서 접속한다. 공인 인터넷에 열려 있어야 한다. localhost·사내망·VPN 뒤는 연결되지 않는다. stdio 방식은 원리상 불가능하다.
이 스킬 자체는 클로드 코드 전용이다. git과 CLI를 쓰기 때문이다. 의도된 것이다 — 설치를 자동화하는 도구는 자동화가 가능한 곳에 있어야 한다.
호환성 규칙과 표면별 제약은 references/surface-matrix.md,
패키징 규격은 references/packaging.md 참조.
하지 말 것
- 확인 없이 "세 곳 다 완료" — 챗·코워크는 사용자가 클릭해야 끝난다
- "안 보인다"는 말에 진단 없이 재설치부터 하기 — 대개 복사 한 번이면 된다
- 챗/코워크 저장소를 못 찾았는데 찾은 척하기
- 갈림길마다 묻기 — 초보자는 판단 근거가 없다. 기본값으로 진행한다
- 초보자에게 포크·푸시 시키기 — zip 경로가 있다
- HIGH 보안 경고를 조용히 넘기기
- stdio MCP가 챗에서 될 것처럼 말하기
- 문서에 없는 내부 디렉토리에 파일 심기 — 버전이 바뀌면 깨진다