시작하기
AgentKit CLI(ak)를 설치하고 이메일 또는 API 키로 인증해 키트를 설정하거나, 기존 ClaudeKit CLI(ck)에서 이전하세요.
ak는 새로운 AgentKit CLI입니다. 기존 ClaudeKitckCLI를 대체하며, macOS, Linux, Windows에서 Node.js나 Bun 없이 실행되는 단일 네이티브 바이너리입니다. Claude Code와 Codex용 AgentKit 워크플로 키트를 관리할 수 있습니다.ck에서 이전하시나요? 기존 ck CLI에서 이전을 확인하세요.
설치
macOS / Linux
curl -fsSL https://agentkit.best/install.sh | sh
네트워크에서 제품 도메인을 차단한다면 신뢰할 수 있는 직접 릴리스 별칭을 사용하세요.
curl -fsSL https://releases.agentkit.best/install.sh | sh
두 명령은 같은 릴리스 관리형 설치 프로그램을 실행하며, 서명된 채널 포인터, 고정된 부트스트랩 검증기, 아카이브 체크섬 체인을 그대로 유지합니다. 네트워크 또는 엔드포인트 보호 오류를 우회하려고 검증을 비활성화하지 마세요.
설치 프로그램은 운영체제와 아키텍처를 감지하고 stable 채널의 최신 릴리스를 내려받아 서명된 릴리스 매니페스트의 SHA-256 값과 대조한 뒤 ak를 ~/.local/bin에 설치합니다. 여러 번 실행해도 안전하며 채널의 최신 릴리스를 항상 확인합니다. 같은 한 줄 명령을 다시 실행하면 기존 바이너리를 덮어써 현재 위치에서 업그레이드합니다. 이미 최신 버전이라면 같은 버전을 다시 설치합니다.
환경 변수로 설치 방식을 조정할 수 있습니다.
# Install to a custom directory curl -fsSL https://agentkit.best/install.sh | AK_INSTALL_DIR="$HOME/bin" sh # Install the latest public beta build (default channel: stable) curl -fsSL https://agentkit.best/install.sh | AK_CHANNEL=beta sh # Pin an exact version curl -fsSL https://agentkit.best/install.sh | AK_VERSION=1.0.0 sh
Windows (PowerShell)
irm https://agentkit.best/install.ps1 | iex
네트워크에서 제품 도메인을 차단한다면 신뢰할 수 있는 직접 릴리스 별칭을 사용하세요.
irm https://releases.agentkit.best/install.ps1 | iex
직접 별칭도 기본 명령과 같은 서명 검증 체인을 사용합니다. Windows 보안 제어를 활성화한 상태로 유지하세요. 보안 경고는 설치 실패를 뜻하며, 제외 항목을 추가하라는 뜻이 아닙니다.
ak.exe를 %USERPROFILE%\bin에 설치하고 해당 디렉터리를 사용자 PATH에 자동으로 추가합니다. 설치 후 새 터미널을 여세요. 셸 설치 프로그램과 마찬가지로 여러 번 실행해도 안전하며 채널의 최신 릴리스를 확인합니다. 다시 실행하면 현재 위치에서 업그레이드합니다. 파이프로 전달하기 전에 다음과 같이 설정할 수 있습니다.
# Install the latest public beta build (default channel: stable) $env:AK_CHANNEL = "beta"; irm https://agentkit.best/install.ps1 | iex # Pin an exact version $env:AK_VERSION = "1.0.0"; irm https://agentkit.best/install.ps1 | iex # Install to a custom directory $env:AK_INSTALL_DIR = "$env:USERPROFILE\Programs\AgentKit"; irm https://agentkit.best/install.ps1 | iex
설치 확인
ak --version ak doctor
ak doctor는 환경을 검사하고 확인이 필요한 항목을 알려 줍니다.
비공개 GitHub 릴리스: 공개 R2 beta 채널에 없는, 이름이 지정된 비공개 프리릴리스에만 이 방식을 사용하세요. 먼저 GitHub CLI에 인증한 뒤 해당 릴리스의 설치 프로그램을 명시적으로 내려받습니다.
gh auth login -h github.com gh release download <private-prerelease-tag> --repo bestagentkits/agentkit -p install.sh -O - \ | AK_VERSION=latest-beta AK_DOWNLOAD_MODE=gh sh$env:AK_VERSION = "latest-beta" $env:AK_DOWNLOAD_MODE = "gh" gh release download <private-prerelease-tag> --repo bestagentkits/agentkit -p install.ps1 -O install.ps1 --clobber & .\install.ps1공개 R2 beta에는 위의
AK_CHANNEL=beta를 사용하세요. 기본 HTTP 모드에서AK_VERSION=latest-beta를 함께 사용하면 안 됩니다.
인증
CLI에서는 이메일 또는 API 키로 로그인할 수 있으며, 두 방식 모두 CLI 세션을 엽니다. 사용자 API 키는 계정 대시보드에서 확인하세요.
이메일 — 일회용 코드(OTP)를 전송합니다. 안내가 나오면 코드를 붙여 넣으세요. 로컬 사용에 권장합니다.
ak login --email [email protected]
API 키 — 웹 프로필의 사용자 API 키를 사용합니다. CI와 비대화형 환경에 적합합니다.
ak login --api-key ak_live_... --no-interactive
세션과 사용 권한을 확인하세요.
ak whoami ak licenses
라이선스 키는 AgentKit Desktop App을 활성화하며 CLI 인증에는 사용되지 않습니다.
ak login --license-key ak_license_...는 CLI 세션을 여는 대신 데스크톱 앱의 기기 활성화를 수행합니다. CLI에서는--api-key를 사용하세요.
공용 컴퓨터에서는 ak logout으로 자격 증명을 삭제하세요. API 키를 커밋하거나 공유하지 마세요. 키를 가진 사람은 누구나 해당 사용 권한을 이용할 수 있습니다.
키트 설치
인증을 마친 뒤 코딩 에이전트용 키트를 설치하세요.
# Engineer kit for Claude Code, available in every project ak kit init engineer --target claude-code --global # Marketing kit ak kit init marketing --target claude-code --global # Codex as the target agent ak kit init engineer --target codex --global
스킬을 선택해 키트의 일부만 설치할 수도 있습니다.
ak kit init engineer --target claude-code --global --skills ak-cook,ak-plan ak kit init engineer --target claude-code --global --exclude-skills ak-video
--select-skills는 대화형 선택기를 엽니다. Claude Code에서는 ak: 슬래시 접두사로 키트 스킬을 실행합니다.
/ak:cook # develop a new feature /ak:plan # scan, analyze, and plan an implementation /ak:fix # fix bugs with root-cause analysis /ak:ask # ask anything with project-aware context
ak kit list-kits로 사용 가능한 키트 이름을 확인하고, ak versions로 로컬에 설치된 버전을 확인할 수 있습니다.
다른 코딩 에이전트에서 키트 사용(Portable target)
Claude Code와 Codex는 AgentKit이 네이티브로 지원하는 우선 대상입니다. Cursor, Antigravity, OpenCode, Grok 등 다른 코딩 에이전트에서는 portable target으로 키트를 설치하세요.
# Portable export of the Engineer kit for any coding agent ak kit init engineer --target portable # Marketing kit, portable profile ak kit init marketing --target portable
portable target은 특정 도구 이름 대신 일반적인 기능 표현(파일 읽기, 파일 수정, 파일 검색, 셸 명령 실행)을 사용하도록 스킬과 에이전트 지침을 변환한 중립적인 best-effort 프로필을 생성합니다. 생성된 portable kit 폴더를 사용 중인 에이전트에 가져오면 됩니다.
Portable은 네이티브 지원 전까지 사용하는 임시 연결 방식입니다. 현재 전용 어댑터가 없는 에이전트에는 가장 적합하지만, Claude Code와 Codex용 네이티브 키트 대비 약 80~90% 수준의 기능을 기대해야 하며 런타임 호환성을 보장하지 않습니다.
업데이트
# Check for a binary update, then apply it ak self-update --check ak self-update --yes # Refresh an installed kit and remove stale generated files ak kit refresh engineer --global --yes # Preview updates to an AgentKit-managed project, then apply them ak update ak update --yes
ak self-update는 ak 바이너리를 업데이트하고, ak update는 AgentKit이 관리하는 프로젝트 콘텐츠를 갱신하며, ak kit refresh <kit> --yes는 오래된 생성 파일 제거를 포함해 설치된 런타임 키트를 갱신합니다. ak self-update --dry-run과 ak update --dry-run은 읽기 전용 미리보기입니다. ak kit init은 대화형 확인(스크립트에서는 --yes)을 사용하고 기본적으로 알 수 없거나 사용자가 수정한 파일을 보존합니다. 키트 갱신은 추적 중인 콘텐츠를 다시 쓰기 전에 스냅샷으로 저장합니다.
기존 ck CLI에서 이전
기존 ck CLI(claudekit-cli npm 패키지)는 더 이상 사용되지 않습니다. ak migrate는 인식 가능한 ClaudeKit 설치를 한 번만 안전하게 인계하기 위한 전환 도구이며, 일반적인 키트 업데이트 흐름에는 사용하지 않습니다.
# Preview the migration — read-only, this is the default ak migrate --from=ck # Apply it non-interactively (CI-friendly) ak migrate --from=ck --dry-run=false --yes --no-interactive
ak migrate는 --dry-run=false --yes를 전달하기 전까지 읽기 전용으로 동작합니다. 쓰기 전에 상태를 스냅샷으로 저장하므로 필요한 경우 ak migrate rollback으로 되돌릴 수 있습니다. 직접 이전하려면 아래 단계를 따르세요.
1. 기존 ck 설치를 찾아 제거합니다. PATH의 앞쪽에 오래된 ck가 남아 있으면 AgentKit을 설치한 뒤에도 기존 ClaudeKit 스크립트가 실행될 수 있습니다.
# macOS / Linux — inspect every ck on PATH, then remove the npm package which -a ck npm uninstall -g claudekit-cli # or: bun remove -g claudekit-cli
# Windows Get-Command ck -All npm uninstall -g claudekit-cli
2. 위의 한 줄 명령으로 ak를 설치한 다음 이메일 또는 API 키로 인증합니다.
3. (선택 사항) ck를 별칭으로 유지합니다. ak 바이너리는 ck로 실행된 경우를 감지하고 동일하게 동작하므로 기존 스크립트를 계속 사용할 수 있습니다.
# macOS / Linux — symlink (future ak updates apply automatically) ln -sf ~/.local/bin/ak ~/.local/bin/ck
# Windows — copy next to ak.exe, or add a profile function Copy-Item $env:USERPROFILE\bin\ak.exe $env:USERPROFILE\bin\ck.exe
심 링크가 올바르게 연결되는지 확인하세요.
ak doctor --check ck_shim_collision
명령 매핑
기존 ck 명령 | 새로운 ak 명령 |
|---|---|
npm install -g claudekit-cli | curl -fsSL https://agentkit.best/install.sh | sh |
ck new | ak new |
ck init | ak init |
ck update | ak update |
ck setup | ak setup |
ck skills / ck agents | ak skills / ak agents |
ck doctor | ak doctor |
ck versions | ak versions |
ck config | ak config |
ck uninstall | ak uninstall |
| GitHub PAT 인증 | ak login --email <you>(또는 --api-key <key>) |
| — | ak kit init <kit> --target <agent> --global(키트 수명 주기) |
| — | ak self-update, ak audit, ak gui(ak의 새 기능) |
문제 해결
| 증상 | 해결 방법 |
|---|---|
설치 후 ak: command not found가 표시됨 | 설치 디렉터리가 PATH에 있는지 확인하세요. echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc(또는 ~/.bashrc)를 실행한 뒤 새 셸을 여세요. |
Windows에서 설치 후 ak를 인식하지 못함 | 설치 프로그램이 %USERPROFILE%\bin을 사용자 PATH에 추가했습니다. 새 터미널을 여세요. |
| Windows에서 설치 프로그램을 차단함 | 보안 제어를 활성화한 상태로 유지하세요. 기본 명령을 다시 시도한 다음 신뢰할 수 있는 직접 별칭 irm https://releases.agentkit.best/install.ps1 | iex를 사용하세요. 둘 다 실패하면 중단하고 정확한 경고 메시지와 함께 지원팀에 문의하세요. |
| 체크섬 또는 서명 검증 실패 | 설치를 중단하고 한 번 다시 시도하세요. 기본 도메인이 차단되었다면 위의 신뢰할 수 있는 직접 릴리스 별칭을 사용하세요. 검증을 우회하면 안 됩니다. |
ck를 입력하면 기존 ClaudeKit이 실행됨 | 오래된 ck 바이너리가 PATH의 앞쪽에 있습니다. which -a ck(또는 Get-Command ck -All)를 실행하고 ak를 가리키지 않는 항목을 제거한 뒤 ak doctor --check ck_shim_collision을 실행하세요. |
ak login 실패 | API 키가 /account에 표시된 값과 정확히 일치하는지 확인하세요. 앞뒤 공백이 없어야 합니다. --email을 사용했다면 OTP 코드가 만료되지 않았는지 확인하세요. 계속 문제가 발생하면 아래 지원 채널로 문의하세요. |
| 사용 권한 누락으로 키트 설치 실패 | 라이선스는 특정 키트(Engineer, Marketing 또는 Bundle)를 포함합니다. ak licenses로 확인하세요. |
도움이 필요하면 Discord에 참여하거나 [email protected]로 이메일을 보내세요.
지원 종료: ClaudeKit
ckCLI는 새로운 AgentKitakCLI로 대체되었습니다. 이 페이지는 기존 설치 사용자를 위해 유지됩니다. 새로 설정할 때는 AgentKit CLI (ak) 탭을 사용하세요. 단계별 이전 가이드가 포함되어 있습니다.
방법 1: 수동 설정
agentkit-engineer저장소의 모든 디렉터리와 파일을 프로젝트에 복사합니다..claude/*docs/*plans/*CLAUDE.md.mcp.json
- Google AI Studio에서 API 키를 발급받은 뒤
.mcp.json을 열어 “human-mcp” 환경 변수에 붙여 넣습니다.- 권장: 매 프로젝트에서 다시 설치하지 않고 사용할 수 있도록
user범위로 “Human MCP”를 설치하세요.claude mcp add-json human -s user '{"command": "npx", "args": ["@goonnguyen/human-mcp@latest", "-e", "GOOGLE_GEMINI_API_KEY"], "env": { "GOOGLE_GEMINI_API_KEY": "..." }}'
- 권장: 매 프로젝트에서 다시 설치하지 않고 사용할 수 있도록
- 작업 프로젝트에서 Claude Code를 시작합니다.
claude(또는claude --dangerously-skip-permissions) /docs:init명령을 실행해 Claude Code가 전체 프로젝트를 스캔하고 명세를 생성하도록 합니다.docs디렉터리에 “codebase-summary.md”, “code-standards.md”, “system-architecture.md” 등의 Markdown 파일이 생성됩니다.- 이제 개발을 시작할 준비가 되었습니다. 다음 명령을 살펴보세요.
/cook: 새 기능 개발/fix:fast: 사소한 버그 수정(빠른 모드)/fix:hard: 복잡한 버그 수정/plan: Claude Code가 구현할 내용을 스캔, 분석하고 계획하도록 실행/bootstrap: Claude Code와 함께 새 프로젝트를 단계별로 구성/brainstorm: 프로젝트 컨텍스트를 바탕으로 Claude Code와 아이디어 논의/ask: 자유롭게 질문- ...
방법 2: 기존 ClaudeKit CLI (ck)
설치
npm install -g claudekit-cli
# or with Bun bun add -g claudekit-cli ck --version
새 프로젝트 만들기
# Interactive mode ck new # With options ck new --dir my-project --kit engineer # Specific version ck new --kit engineer --version v1.0.0
기존 프로젝트 업데이트
# Interactive mode ck update # With options ck update --kit engineer # Specific version ck update --kit engineer --version v1.0.0
인증
CLI가 비공개 저장소에서 릴리스를 내려받으려면 GitHub Personal Access Token(PAT)이 필요합니다. 인증은 다음 순서로 대체 수단을 확인합니다.
- GitHub CLI: GitHub CLI가 설치되고 인증되어 있으면
gh auth token을 사용합니다. - 환경 변수:
GITHUB_TOKEN또는GH_TOKEN을 확인합니다. - 운영체제 키체인: 시스템 키체인에 저장된 토큰을 가져옵니다.
- 사용자 입력: 토큰 입력을 요청하고 안전하게 저장할 수 있도록 안내합니다.
Personal Access Token 만들기
- GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)으로 이동합니다.
- 비공개 저장소에 접근할 수 있도록 repo 범위가 있는 새 토큰을 생성합니다.
- 토큰을 복사합니다.
환경 변수로 토큰 설정
export GITHUB_TOKEN=ghp_your_token_here
이전할 준비가 되었나요?
새로운 ak CLI는 GitHub PAT 인증을 이메일 또는 API 키 로그인으로 대체하고, 체크섬으로 다운로드를 검증하며, Claude Code와 Codex를 모두 지원합니다. AgentKit CLI (ak) 탭의 이전 가이드를 확인하세요.