# Universal Install

> Installs skills or MCP servers from a GitHub repo, and moves skills between Claude Code, chat, and Cowork. Use for install requests, or when a skill is missing from one of them.

- Skill: `yongkyu4803/universal-install` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add yongkyu4803/universal-install`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yongkyu4803/universal-install/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: yongkyu4803 (https://skillmd.com/u/yongkyu4803)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yongkyu4803/universal-install

---


# Universal Install

**초보자가 "안 되는데요"라고 말할 때 해결해주는 스킬이다.**

클로드는 환경마다 확장 기능 저장소가 다르다. 코워크에서 만든 스킬이 클로드 코드에 안 뜨고,
깃헙에서 받은 스킬이 챗에 안 보인다. 숙련자는 "찾아서 여기 깔아줘"라고 말할 줄 알지만,
초보자는 그게 가능한 줄도 모르고 포기한다. 그 간극을 메우는 것이 이 스킬의 목적이다.

## 입구는 네 가지다

사용자가 무슨 말을 하든 아래 중 하나로 분류해서 처리한다.

| 사용자가 하는 말 | 무엇을 할 것인가 |
|---|---|
| "이 깃헙 주소 설치해줘" | 1~5단계 설치 흐름 |
| **"코워크(챗)에서 만든 건데 코드에서 안 보여"** | **`sync.py` — 클릭 0회로 해결** |
| "설치했는데 안 뜨는데요" | `sync.py list` / `locate` 로 진단 먼저 |
| "내 스킬 뭐뭐 있어?" | `sync.py list` |
| "코드에서 깐 게 코워크/챗에서 안 열려" | 먼저 새로고침·재시작, 안 되면 zip 안내 |

**진단을 먼저 한다.** "안 보인다"는 말에 바로 재설치부터 하지 않는다.
어디에 있고 어디에 없는지부터 확인하면 대개 복사 한 번으로 끝난다.

## 먼저 — 지금 내가 어디서 도는지 확인한다

**이 스킬은 세 표면 모두에 설치되지만, 실제로 동작하는 건 클로드 코드뿐이다.**
코워크는 격리된 VM, 챗은 샌드박스라 사용자 컴퓨터의 파일에 닿지 못한다.

그러므로 파일을 만지기 전에 **반드시** 먼저 확인한다.

```bash
python3 scripts/sync.py env
```

`격리된 환경`이 나오면 파일 작업을 시도하지 않는다. 안내만 한다.
스크립트가 알아서 막고 안내문을 출력하므로, 그 내용을 사용자 말투로 옮겨주면 된다.

**여기서 절대 하지 말 것:** "안 됩니다"로 끝내기. 반드시 다음 행동을 준다.

## 여섯 방향 전부

"안 보인다"는 불평은 어디서든 나올 수 있다. 방향마다 답이 다르다.

| 어디서 불평하나 | 무엇이 안 보이나 | 답 |
|---|---|---|
| 클로드 코드 | 챗·코워크에서 만든 것 | ✅ **자동** — `sync.py pull` |
| 클로드 코드 | 깃헙에 있는 것 | ✅ **자동** — 설치 흐름 |
| 코워크 | 클로드 코드에 있는 것 | ⚠️ 여기선 불가 → 코드에서 zip 만들어 업로드 |
| 챗 | 클로드 코드에 있는 것 | ⚠️ 여기선 불가 → 코드에서 zip 만들어 업로드 |
| 코워크 | 챗에 있는 것 | 대개 이미 보임 (계정 공유) — 앱 재시작 먼저 권함 |
| 챗 | 코워크에 있는 것 | 대개 이미 보임 (계정 공유) — 새로고침 먼저 권함 |

**아래 두 줄이 중요하다.** 챗과 코워크는 같은 계정을 쓰므로 대개 이미 공유된다.
"안 보인다"고 하면 재설치를 권하기 전에 **새로고침이나 앱 재시작부터** 시켜본다.
그것으로 해결되는 경우가 많다.

**가운데 두 줄이 진짜 막히는 지점이다.** 사용자가 코워크나 챗에 앉아 있고
클로드 코드 스킬을 원하는 상황. 이때 할 일:

1. 지금 여기서는 안 된다고 이유와 함께 말한다 (격리된 환경이라 컴퓨터 파일에 못 닿음)
2. 클로드 코드를 열고 이렇게 말하라고 알려준다 — `"<이름> 을 챗에서 쓰게 zip 만들어줘"`
3. 클로드 코드가 없는 사람이면, 그 스킬을 여기서 다시 만드는 편이 빠를 수도 있다고 안내한다

## 표면 간 이동 (클릭 불필요)

데스크톱 앱은 계정의 스킬을 로컬에 내려받아 둔다. 그래서 **챗·코워크 → 클로드 코드**
방향은 파일 복사만으로 해결된다. 사용자가 웹에서 뭘 누를 필요가 없다.

```bash
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`가 하드코딩하지 않고 탐색하며, 못 찾으면 그렇다고 말한다.
앱이 업데이트되면 사라질 수 있는 경로다. 못 찾았을 때 지어내지 말 것.

## 대원칙

1. **판단은 내가 한다.** 갈림길마다 묻지 않는다. 정해진 기본값을 따른다.
   진짜 물어야 할 때는 둘뿐이다 — HIGH 보안 경고, 스킬이 여러 개라 고를 때.
2. **소유권을 요구하지 않는다.** 초보자는 레포를 포크·푸시하지 못한다.
3. **"안 됩니다"로 끝내지 않는다.** 안 되면 이유와 대안을 반드시 같이 준다.
4. **전문용어를 사용자에게 던지지 않는다.** transport, 프론트매터, 스코프는 내부용이다.
5. **거짓말하지 않는다.** 확인 전에 "완료"라고 하지 않는다.

## 0단계 — 사전 점검 (먼저, 조용히)

```bash
git --version                     # 없으면: xcode-select --install 안내
claude plugin marketplace list    # CLI 동작 확인
```

`git`이 없으면 여기서 멈추고 설치 방법만 알려준다. 나머지는 진행해도 어차피 실패한다.

플랜 제약은 **미리 겁주지 말고** 해당 단계에서만 언급한다.
- 플러그인 설치는 유료 플랜(Pro/Max/Team/Enterprise) 필요
- 챗 스킬 업로드는 코드 실행(code execution) 켜져 있어야 함

## 1단계 — 가져오기

```bash
git clone --depth 1 <repo-url> <스크래치경로>/<name>
```

스크래치 디렉토리를 쓴다. 사용자 프로젝트를 어지럽히지 않는다.
클론 실패(오타·비공개 레포)면 주소를 다시 확인해달라고만 한다.

## 2단계 — 분석

```bash
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단계 — 보안 검토

```bash
python3 scripts/audit.py <경로>
```

- **HIGH 0건** → 조용히 통과. 사용자에게 보고하지 않는다. (정상 스킬도 MED/LOW는 흔하다)
- **HIGH 1건 이상** → **멈춘다.** 해당 항목을 쉬운 말로 설명하고 진행 여부를 묻는다.
  예: "이 스킬은 인터넷에서 코드를 받아 바로 실행합니다. 만든 사람을 믿을 수 있나요?"

공식 문서 경고다 — 스킬은 임의 코드를 실행시킬 수 있으므로 신뢰할 수 있는 출처만 쓴다.

## 4단계 — 설치

### 클로드 코드 (자동, 항상 먼저)

```bash
# 마켓플레이스 레포
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를 번들할 수도 있지만(검증됨), 그건 레포 소유자에게만 해당한다.

```bash
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가 챗에서 될 것처럼 말하기
- 문서에 없는 내부 디렉토리에 파일 심기 — 버전이 바뀌면 깨진다