# 설치

kstack은 GitHub에서 최신 태그 릴리스를 가져와 에이전트의 스킬 디렉토리에 생성하여 설치됩니다. 동일한 한 줄 부트스트랩이 Claude Code와 `PATH`의 지원되는 모든 에이전트를 처리합니다.

## 설치

### 글로벌

머신의 모든 프로젝트에서 스킬을 사용할 수 있도록 "글로벌" 모드로 kstack을 설치하려면 다음을 실행하십시오:

```bash
curl -sS https://kstack.sh/install | bash
```

이는 [kubetail-org/kstack](https://github.com/kubetail-org/kstack)의 최신 태그 릴리스를 `~/.config/kstack/upstream/`에 클론하고 각 스킬을 `PATH`에서 찾은 모든 에이전트 CLI의 스킬 디렉토리에 렌더링합니다. 스크립트가 완료된 후 에이전트 세션을 열면 kstack 스킬을 사용할 수 있습니다:

```bash
$ claude
───────────────────────────────────
❯ /kstack-cluster-status
───────────────────────────────────
```

기본적으로 `install` 스크립트는 스킬 이름에 `kstack-*` 네임스페이스 접두사를 붙입니다. 설치 스크립트 실행 시 `--no-prefix` 플래그로 비활성화할 수 있습니다 (아래 참조).

### 로컬

에이전트가 단일 프로젝트 디렉토리에서 실행될 때만 스킬을 사용할 수 있도록 "로컬" 모드로 kstack을 설치하려면 다음을 실행하십시오:

```bash
cd myproject
curl -sS https://kstack.sh/install | bash -s -- --local
```

이는 [kubetail-org/kstack](https://github.com/kubetail-org/kstack)의 최신 태그 릴리스를 `<project>/.kstack/upstream/`에 클론하고 스킬을 `<project>/.<agent>/skills/`에 렌더링합니다. 스크립트가 완료된 후 해당 프로젝트 디렉토리에서 에이전트 세션을 열면 kstack 스킬을 사용할 수 있습니다:

```bash
$ cd myproject && claude
───────────────────────────────────
❯ /kstack-cluster-status
───────────────────────────────────
```

기본적으로 `install` 스크립트는 스킬 이름에 `kstack-*` 네임스페이스 접두사를 붙입니다. 설치 스크립트 실행 시 `--no-prefix` 플래그로 비활성화할 수 있습니다 (아래 참조).

### 네임스페이스 접두사 제거

`kstack-*` 네임스페이스 접두사 없이 스킬을 설치하려면 `--no-prefix` 플래그를 사용하십시오:

```bash
curl -sS https://kstack.sh/install | bash -s -- --no-prefix
```

위 예시에서 `/kstack-cluster-status`는 `/cluster-status`가 되고, `/kstack-events`는 `/events`가 됩니다. 이 옵션은 글로벌 및 로컬 설치 모두에서 작동합니다.

### 특정 에이전트 지정

기본적으로 부트스트랩은 `PATH`에서 감지하는 지원되는 모든 에이전트에 설치됩니다. 설치를 하나의 에이전트로 제한하려면 `--agent <name>`을 전달하십시오:

| 에이전트            | 플래그               | 글로벌 설치 경로               |
|---------------------|----------------------|-------------------------------|
| Claude Code         | `--agent claude`     | `~/.claude/skills/`           |
| OpenAI Codex CLI    | `--agent codex`      | `~/.codex/skills/`            |
| OpenCode            | `--agent opencode`   | `~/.config/opencode/skills/`  |
| Cursor              | `--agent cursor`     | `~/.cursor/skills/`           |
| Factory Droid       | `--agent factory`    | `~/.factory/skills/`          |
| Slate               | `--agent slate`      | `~/.slate/skills/`            |
| Kiro                | `--agent kiro`       | `~/.kiro/skills/`             |
| Hermes              | `--agent hermes`     | `~/.hermes/skills/`           |

로컬 설치는 프로젝트 디렉토리 아래에 이 구조를 미러링합니다 (예: `<project>/.codex/skills/`). 에이전트별 참고 사항은 [Claude가 아닌 에이전트와 함께 kstack 사용](/ko/guides/non-claude-agents/)을 참조하십시오.

### 디렉토리 구조

부트스트랩 스크립트는 다음 디렉토리 구조를 생성합니다:

```
<kstack-root>/
├── upstream/        # pinned checkout of kubetail-org/kstack at the release tag
├── bin/
│   ├── upgrade      # helper used by "upgrade kstack"
│   └── uninstall    # helper used below
├── cache/           # per-context cache (query results, log buffers)
└── state/           # per-context learned state (detected integrations, fingerprints)
```

추가로 감지된 에이전트별 디렉토리가 생성됩니다. 예: `~/.claude/skills/cluster-status/`, `~/.claude/skills/events/` 등.

## 업그레이드

kstack 스킬을 실행하면 에이전트가 조용히 최신 kstack 릴리스가 있는지 확인하고, 발견되면 응답 상단에 한 줄 알림을 표시합니다. **"upgrade kstack"**이라고 말하면 에이전트가 사용자를 대신하여 업그레이드 헬퍼를 실행합니다. **"dismiss"**라고 말하면 다음 릴리스까지 알림을 숨깁니다.

헬퍼를 직접 실행할 수도 있습니다:

```bash
# Global install
~/.config/kstack/bin/upgrade

# Local install (from the project directory)
<project-root>/.kstack/bin/upgrade
```

헬퍼는 기존 업스트림 체크아웃에 최신 태그를 가져오고 스킬을 제자리에 재렌더링합니다. 업그레이드는 멱등적이며 언제든지 안전하게 실행할 수 있습니다 — `cache/` 및 `state/` 디렉토리가 보존되므로 kstack은 클러스터에 대해 이미 학습한 내용을 유지합니다.

curl 부트스트랩을 다시 실행해도 동일한 결과가 생성됩니다. 전용 헬퍼는 설치 위치를 확인하는 네트워크 왕복을 건너뜁니다.

## 제거

제거하려면 설치 시 번들된 `uninstall` 스크립트를 실행하십시오:

```bash
# Global install
~/.config/kstack/bin/uninstall

# Local install (from the project directory)
<project-root>/.kstack/bin/uninstall
```

헬퍼는 항목을 제거하기 전에 확인을 요청합니다. 설치 루트(`~/.config/kstack` 또는 `<project>/.kstack`)와 설치했던 모든 에이전트의 kstack 소유 스킬 슬롯을 지웁니다. 동일한 에이전트 디렉토리의 사용자 작성 스킬은 그대로 유지됩니다 — 제거 스크립트는 자체적으로 작성한 슬롯만 제거합니다.

제거해도 kstack이 클러스터에서 생성했을 수 있는 리소스(디버그 컨테이너, 파드 복제본, watcher Job)에는 영향을 미치지 않습니다. 이를 제거하려면 스킬을 여전히 사용할 수 있는 동안 제거하기 **전에** [`/cleanup`](/ko/reference/skills/cleanup/)을 실행하십시오.