설치

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

설치

글로벌

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

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

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

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

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

로컬

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

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

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

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

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

네임스페이스 접두사 제거

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

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 사용을 참조하십시오.

디렉토리 구조

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

<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”**라고 말하면 다음 릴리스까지 알림을 숨깁니다.

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

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

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

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

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

제거

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

# 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을 실행하십시오.