claude-kit으로 더 스마트한 Claude Code 워크플로 구축하기

claude-kit이 제공하는 기능

claude-kit은 Claude Code를 위한 독립형 스킬, 에이전트, 모음 및 모드 모음입니다. 각 항목은 저장소의 plugins/ 디렉터리에 있으므로 필요한 기능만 설치할 수 있습니다.

• savvy-flow: 세션에서 작업을 계획하고, 계층화된 작업자 서브에이전트에게 작업을 위임하며, 결과를 검토할 수 있게 해 주는 스킬 및 에이전트 패키지입니다. 수동으로 설치한 경우 /savvy-flow로 호출하고, 마켓플레이스를 통해 설치한 경우 플러그인 네임스페이스를 사용합니다.
• savvy-progress: 프롬프트 위에 진행률 표시줄과 실시간 에이전트 패널을 추가하는 모드입니다. savvy-flow를 위해 설계되었지만 모든 서브에이전트도 표시할 수 있습니다.

두 플러그인은 독립적으로 작동합니다. 둘 다 설치하면 savvy-flow가 진행률 표시줄을 제어하고 작업자들이 에이전트 패널에 진행 상황을 보고합니다.

마켓플레이스에서 claude-kit 설치

마켓플레이스 방식은 Claude Code에 플러그인을 설치하는 가장 간단한 방법입니다.

1. Claude Code를 엽니다.
2. 저장소를 마켓플레이스로 추가하고 원하는 플러그인을 설치합니다.

/plugin marketplace add johnnyvizz/claude-kit
/plugin install savvy-flow@claude-kit
/plugin install savvy-progress@claude-kit

설치 후 세션을 다시 시작합니다. 마켓플레이스에서 설치한 스킬과 에이전트에는 네임스페이스가 붙습니다. 따라서 savvy-flow 스킬은 /savvy-flow:savvy-flow로 호출하고, 에이전트에는 savvy-flow:savvy-careful과 같은 이름을 사용합니다.

워크플로에 더 적합하다면 플러그인 하나만 설치할 수 있습니다. 계획 워크플로와 시각적 진행 표시를 함께 사용하려면 두 플러그인을 모두 설치합니다.

구성 요소 수동 설치

수동 설치는 스킬을 Claude Code 설정에 복사하거나 로컬 체크아웃에서 직접 모드를 불러오고 싶을 때 유용합니다.

저장소 복제

git clone https://github.com/johnnyvizz/claude-kit.git ~/claude-kit

savvy-flow 스킬 및 에이전트 복사

이 방식으로 설치하면 스킬에 플러그인 시스템이 필요하지 않습니다. 스킬 폴더를 Claude Code 스킬 디렉터리로 복사합니다.

cp -R ~/claude-kit/plugins/savvy-flow/skills/savvy-flow ~/.claude/skills/

그런 다음 제공된 에이전트 정의를 에이전트 디렉터리로 복사합니다.

cp ~/claude-kit/plugins/savvy-flow/agents/*.md ~/.claude/agents/

이 방식을 사용하면 이름이 짧게 유지됩니다. 스킬에는 /savvy-flow를 사용하고, 에이전트에는 savvy-careful과 같은 이름을 사용합니다.

한 세션 동안 savvy-progress 불러오기

특정 Claude Code 세션에서만 진행률 모드를 불러오려면 플러그인 디렉터리를 지정하여 Claude Code를 시작합니다.

claude --plugin-dir ~/claude-kit/plugins/savvy-progress

모든 세션에서 savvy-progress 불러오기

데스크톱 앱을 포함한 모든 세션에서 모드를 사용할 수 있게 하려면 ~/.claude/settings.json에서 CLAUDE_CODE_PLUGIN_DIRS를 설정합니다.

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "~/claude-kit/plugins/savvy-progress"
  }
}

여러 플러그인 폴더를 설정하는 경우 :로 구분합니다. CLAUDE_CODE_PLUGIN_DIRS에 이미 값이 있다면 기존 항목을 대체하지 말고 새 폴더를 추가합니다.

기본 워크플로 실행

savvy-flow를 설치한 후 계획 및 조정이 필요한 작업을 전달합니다. 예를 들어 스킬을 수동으로 복사한 경우 다음과 같이 실행합니다.

/savvy-flow review the authentication changes and identify missing tests

마켓플레이스에서 설치한 경우 네임스페이스 형식을 사용합니다.

/savvy-flow:savvy-flow review the authentication changes and identify missing tests

세션 모델은 작업을 계획하고, 작업자 서브에이전트에게 작업을 위임하며, 결과를 검토합니다. savvy-progress도 활성화되어 있으면 진행률 표시줄과 에이전트 패널에서 해당 활동을 실시간으로 확인할 수 있습니다.

구체적인 작업은 사용자가 정할 수 있습니다. 계획 및 위임 작업의 이점을 얻을 수 있는 코드 리뷰, 조사 또는 기타 개발 작업을 전달하면 됩니다.

저장소 구조 이해

각 플러그인은 예측 가능한 구조를 따릅니다. 마켓플레이스 카탈로그와 플러그인 매니페스트가 Claude Code에서 구성 요소를 검색하는 방법을 정의합니다.

.claude-plugin/marketplace.json   `/plugin marketplace add`가 읽는 카탈로그
plugins/<name>/
  .claude-plugin/plugin.json      매니페스트
  skills/<skill>/SKILL.md         스킬
  agents/*.md                     함께 제공되는 서브에이전트
  hooks/hooks.json                모드: hooks 모듈을 가리킴
  hooks/register.tsx              모드: 모듈 자체
  types/index.d.ts                모드: 해당 모드의 $.state 계약

이 구조에서 스킬은 SKILL.md 파일로 설명되며 에이전트 정의를 함께 제공할 수 있습니다. 모드는 훅 구성과 등록 모듈을 사용하며, 형식 선언에서 $.state 계약을 문서화합니다.

게시 전 플러그인 검증

Claude Code의 검증 명령을 사용하여 개별 플러그인 또는 마켓플레이스 카탈로그를 확인합니다.

claude plugin validate plugins/<name>
claude plugin validate .

첫 번째 명령은 플러그인 디렉터리를 검증합니다. 두 번째 명령은 저장소 루트에서 저장소 카탈로그를 검증합니다.

수동 설치 최신 상태 유지

복제한 저장소에서 직접 모드를 불러오는 경우 다음 명령으로 업데이트합니다.

cd ~/claude-kit
git pull

해당 디렉터리에서 로드된 모드는 업데이트된 파일을 사용합니다. ~/.claude/skills/에 복사한 스킬은 자동으로 업데이트되지 않으므로, 새 변경 사항을 가져온 후 스킬 및 에이전트 파일을 다시 복사해야 합니다.

고급 고려 사항

네임스페이스 명령과 짧은 명령을 의도적으로 선택하기

마켓플레이스 설치는 /savvy-flow:savvy-flow와 같은 네임스페이스 이름을 통해 플러그인을 격리합니다. 수동 스킬 설치는 플러그인 시스템을 사용하지 않으며 명령을 짧게 유지합니다. 마켓플레이스 관리와 로컬 파일에 대한 직접 접근 중 어느 쪽을 우선하는지에 따라 가장 적합한 방법을 사용하세요.

모드 호환성 고려하기

모드는 초기 액세스 단계인 Claude Code API인 hooks/register.tsx를 통해 함수 훅을 사용합니다. 이 저장소는 Claude Code 2.1.286에서 테스트되었으며, API는 릴리스마다 변경될 수 있습니다.

마켓플레이스에서 설치한 모드가 나타나지 않으면 --plugin-dir을 사용해 수동으로 로드하거나 CLAUDE_CODE_PLUGIN_DIRS를 통해 해당 폴더를 구성하세요.

가시성이 필요할 때 플러그인 결합하기

savvy-flow는 savvy-progress 없이도 작동하며, savvy-progress도 savvy-flow 없이 작동합니다. 두 플러그인을 모두 설치하는 것이 가장 많은 정보를 제공하는 구성입니다. 워크플로가 작업을 조정하고 모드가 진행 상황과 활성 에이전트 상태를 표시합니다.

결론

claude-kit은 Claude Code 사용자에게 모듈식 계획, 위임, 검토 및 진행 상황 모니터링 도구를 제공합니다. 관리형 설정을 사용하려면 마켓플레이스에서 savvy-flow와 savvy-progress를 설치하고, 수동으로 구성하려면 저장소를 복제한 후 구성 요소를 복사하거나 로드하세요. 네임스페이스 차이를 기억하고, 게시하기 전에 변경 사항을 검증하며, 저장소에서 로드한 모드와 복사한 스킬은 별도로 업데이트해야 합니다.