Bluetape Skills Part 1: 팀과 공유하고 설치하는 방법

공개 묶음에는 실행에 필요한 guidance를 함께 넣고, 개인 런타임 상태는 밖에 둔다.

2026-07-11 · Bluetape Skills Part 1

이 글은 「AI와 일하는 환경을 인프라로 만들기」의 후속 작업이다. 선행 글에서는 AGENTS.md, skills, 검색, memory, hooks가 어떻게 하나의 협업 환경을 이루는지 설명했다. 이번 시리즈에서는 그 환경을 실제로 운영하면서 발견한 문제와 다른 개발자, 여러 머신에서도 재사용할 수 있도록 skill 체계를 고친 과정을 다룬다.

Codex skill은 SKILL.md 한 장으로 끝나지 않는다. 실제 작업 품질을 좌우하는 것은 그 파일에서 이어지는 reference와 template, 검사 script, 그리고 확인 순서를 적어 둔 checklist다. 이 중 하나라도 빠진 상태로 다른 개발자에게 전달하면 실행 절차가 아니라 제목과 요약만 건네는 셈이다.

그래서 Bluetape skill을 개인 머신 설정에서 분리해 설치 가능한 공개 묶음으로 정리했다.

• 저장소: bluetape4k/bluetape-skills
• 대상: Codex에서 사용하는 canonical Bluetape skill 14개
• 제외: 개인 memory, local rule, hook, config, plugin cache, secret, retired alias

이 글은 단순한 복사 방법보다, 무엇을 함께 배포해야 하고 무엇을 빼야 하는지에 초점을 둔다.

처음부터 공유 가능한 구조였던 것은 아니다

지금의 묶음은 처음부터 완성된 형태로 설계한 것이 아니다. 실제 작업에서 반복해서 드러난 문제를 하나씩 막으면서 지금의 구조가 됐다.

반복된 문제	개선한 방식	새로 추가한 장치
긴 지침 중 일부를 agent가 건너뛰거나 완료 증거 없이 체크했다	실행 항목을 차단 가능한 checklist로 바꿨다	Action, Evidence, Failure, dependency order, repair gate
bluetape4k-* 이름이 Kotlin 전용처럼 보이고 다른 언어 skill의 범위가 모호했다	workflow와 언어 이름을 분리했다	bluetape-*, bluetape-kotlin-patterns, bluetape-publish-jvm
blog 이름 때문에 README와 일반 문서 작업이 별도 영역처럼 보였다	작성 대상보다 역할을 이름에 반영했다	bluetape-writer
SKILL.md만 옮기고 reference나 검사 script를 빠뜨릴 수 있었다	skill 디렉터리 전체를 배포 단위로 고정했다	canonical 14개 allowlist와 manifest.json
live ~/.codex/skills만 고친 내용이 다음 apply에서 사라졌다	chezmoi managed source를 먼저 고치게 했다	targeted apply, source/live parity, self-audit
이름 변경 뒤 과거 문서와 GNO index가 이전 이름을 계속 반환했다	과거 기록을 억지로 다시 쓰지 않고 해석 계층을 뒀다	retired alias와 migration mapping table
공개 export에 개인 경로나 runtime 파일이 섞일 수 있었다	공개 가능한 항목을 allowlist로 export하고 fail-closed 검증을 넣었다	validate.sh, portable path, private/runtime exclusion

각 문제는 달라 보이지만 원인은 비슷했다. 사람은 “당연히 같이 옮길 것”, “앞에서 이미 확인했을 것”, “다음 apply에도 남을 것”이라고 생각한다. 하지만 자동화에서는 이런 암묵적인 전제가 가장 먼저 빠진다. 그래서 기대에 맡기던 내용을 파일 구조와 검사 명령으로 명시했다.

지침을 길게 쓰는 것만으로는 누락을 막지 못했다

초기 skill에도 해야 할 일은 적혀 있었다. 문제는 실행 항목이 설명문 안에 섞여 있으면 agent가 뒤 단계의 성공을 앞 단계의 증거로 오해하기 쉽다는 점이었다. Build가 통과했다는 이유로 계획 승인, 영향 범위 확인, locale parity까지 모두 끝난 것처럼 보고하는 식이다.

그래서 checklist 항목마다 세 가지를 강제했다.

Action   -> 지금 실행할 한 가지 작업
Evidence -> 통과를 증명할 command, file, URL, count
Failure  -> 증거가 없거나 실패했을 때 멈추고 복구할 방법

체크되지 않은 항목은 뒤따르는 단계를 막는다. UNKNOWN은 PASS가 아니며, SKIPPED도 허용하지 않는다. 적용되지 않는 항목은 N/A라고만 쓰지 않고, 왜 적용되지 않는지 범위를 증명하는 근거를 남긴다. 이미 순서를 건너뛰었다면 뒤 단계의 성공으로 덮지 않는다. 누락된 gate부터 복구한 뒤 영향을 받은 검증을 다시 실행한다.

이 checklist contract가 $bluetape-workflow와 각 세부 skill의 공통 기반이 됐다. Part 2에서 실제 실행 순서를 더 자세히 설명한다.

이름부터 canonical 기준으로 정리했다

처음에는 bluetape4k-*라는 이름이 많았다. 하지만 Kotlin/JVM이 아닌 Go, Python, Rust 작업에도 같은 접두사가 붙으면 skill의 범위가 실제보다 좁아 보인다. 그래서 canonical 이름은 bluetape-*로 정리했다.

예를 들면 다음과 같다.

이전 이름	canonical 이름	역할
bluetape4k-code-patterns	bluetape-kotlin-patterns	Kotlin/JVM 구현과 검토
bluetape4k-blog	bluetape-writer	README, 블로그, 문서 현지화
bluetape4k-publish	bluetape-publish-jvm	JVM 라이브러리 publish
bluetape4k-workflow	bluetape-workflow	작업 분류와 workflow routing

기존 이름은 개인 환경에 호환용 alias로만 남길 수 있다. 공개 묶음에는 새 이름만 넣었다. 새 문서나 자동화가 retired 이름을 다시 퍼뜨리지 않도록 한 선택이다.

이전 이름을 한 번에 삭제하지 않은 데에도 이유가 있다. 이미 GNO에 index된 과거 plan, lesson, issue, PR, rollout log에는 당시 이름이 남아 있다. 이런 기록을 모두 다시 쓰면 실제 작성 시점의 역사까지 바뀐다. 대신 매핑 표로 이전 이름과 canonical 이름을 연결하고, retired skill은 정확한 새 이름만 알려 주는 얇은 forwarding alias로 남겼다.

Alias에는 실제 reference를 복제하지 않았다. 같은 규칙이 canonical skill과 alias에서 서로 다르게 바뀌는 일을 막기 위해서다. 현재 사용하는 지침은 새 이름으로 바꾸고, 과거 기록은 매핑 표로 해석한다. 모든 사용 머신에 migration을 적용하고 일정 기간 이전 이름 호출이 없을 때 alias를 제거할 수 있다.

배포 단위는 skill 디렉터리 전체다

공개 저장소의 skills/ 아래에는 canonical skill 14개가 있다. 각 디렉터리를 통째로 설치해야 한다.

skills/
  bluetape-workflow/
    SKILL.md
    references/
    templates/
  bluetape-diagram/
    SKILL.md
    references/
    scripts/

이 구조는 두 가지 누락을 막는다.

첫째는 SKILL.md가 가리키는 reference가 사라지는 문제다. Workflow gate나 writer의 한국어 문체 checklist는 SKILL.md만 복사해서는 온전히 작동하지 않는다.

둘째는 실행 가능한 검사 도구가 빠지는 문제다. Diagram skill의 SVG audit처럼 규칙과 검증 script가 한 쌍인 경우에는 둘 다 있어야 “다이어그램을 만들었다”에서 그치지 않고 “PNG까지 확인했다”고 말할 수 있다.

설치는 검증부터 시작한다

다른 개발자는 다음 명령으로 설치할 수 있다.

git clone https://github.com/bluetape4k/bluetape-skills.git
cd bluetape-skills
./scripts/validate.sh
./scripts/install.sh

validate.sh는 canonical skill 14개의 inventory와 front matter를 확인한다. memory, rules, hooks, .system, secret-like file, macOS metadata처럼 공개하면 안 되는 payload가 들어오면 실패한다.

install.sh는 기본적으로 ${CODEX_HOME:-~/.codex}/skills에 설치한다. 이미 같은 이름의 skill이 있으면 조용히 덮어쓰지 않는다. 실제 교체가 필요할 때만 다음처럼 쓴다.

./scripts/install.sh --force

기존 디렉터리는 타임스탬프가 붙은 백업 디렉터리로 먼저 옮긴다. 새 버전을 시험하다 문제가 생겨도 원래 skill로 돌아갈 수 있게 하는 최소한의 안전장치다.

업데이트도 같은 순서다.

git pull --ff-only
./scripts/validate.sh
./scripts/install.sh --force

설치하거나 업데이트한 뒤에는 Codex를 다시 시작해야 새 skill을 인식한다.

사용할 때는 router 하나로 시작한다

여러 skill의 이름을 모두 외울 필요는 없다. Bluetape 생태계 작업이라면 $bluetape-workflow부터 호출한다. 이 skill이 작업을 bugfix, fast track, full feature, maintenance처럼 분류하고 다음에 필요한 skill을 고른다.

reproducible defect  -> $bluetape-bugfix
small bounded change -> $bluetape-fast-track
new module or broad API -> $bluetape-full-feature
Kotlin/JVM work -> $bluetape-kotlin-patterns
documentation -> $bluetape-writer

이 routing은 모든 작업에 가장 무거운 절차를 적용하지 않도록 해 준다. README 문구 수정에는 release checklist가 필요 없다. 반대로 새 모듈이나 publish 작업을 가벼운 확인만으로 끝내서는 안 된다. Skill의 가치는 지침을 많이 적는 데 있지 않다. 작업 규모에 맞는 확인을 빠뜨리지 않게 하는 데 있다.

공개 묶음과 개인 설정의 경계

개인 Codex 환경에는 업무 이력과 선호하는 도구, 로컬 hook, 다른 프로젝트의 규칙이 섞여 있다. 이를 그대로 공개하면 설치자에게 불필요한 정책까지 전달된다. 개인 정보나 운영 설정이 노출될 위험도 있다.

그래서 공개 묶음에는 재사용할 수 있는 guidance만 담는다. 개인 memory와 hook은 설치하지 않고, bluetape4k-* alias도 포함하지 않는다. Alias는 기존 환경을 안전하게 옮기기 위한 장치이지, 새 환경에서 사용할 API가 아니다.

반대로 canonical skill 안의 reference와 template은 함께 배포한다. 특정 사용자의 정보가 아니라 skill의 실행 계약에 속하기 때문이다.

공개 묶음은 skill 실행에 필요한 계약을 함께 배포하되, 개인 runtime과 호환용 alias는 경계 밖에 둔다.

공개 export를 처음 검증할 때는 이식성을 해치는 문제가 두 가지 드러났다. macOS가 만든 .DS_Store가 skill 디렉터리에 딸려 들어왔고, diagram reference 일부에는 특정 사용자의 /Users/... 절대 경로가 남아 있었다. Export 단계에서 .DS_Store를 제외하는 데서 끝내지 않고 validator에도 차단 규칙을 넣었다. 절대 경로는 CODEX_HOME이나 PATH에서 찾을 수 있는 명령으로 바꿨다.

이 경험 이후 “현재 머신에서 실행된다”와 “다른 개발자에게 배포할 수 있다”를 서로 다른 검증으로 보기 시작했다. 공개 묶음은 canonical inventory, front matter, private/runtime directory, secret-like file, OS metadata를 따로 검사한다.

Live 파일 수정에서 source-first 관리로 바꿨다

Skill 개선 내용이 한 세션에서는 잘 동작하다가 다음 chezmoi apply 뒤에 사라지는 일이 있었다. 원인은 단순했다. ~/.codex/skills의 live 파일만 고치고 managed source에는 반영하지 않았기 때문이다.

지금은 사용자 범위의 skill을 바꿀 때 다음 흐름 전체를 하나의 작업으로 본다.

Live 파일 하나의 성공이 아니라 managed source부터 공개 bundle 검증까지 이어지는 전체 경로를 동기화 단위로 본다.

여기서 chezmoi apply 한 번만으로 전체 동기화가 증명되지는 않는다. config.toml, hooks, .system skill처럼 소유권이 따로 있는 live 영역이 있기 때문이다. 변경 대상의 source와 target을 먼저 확인하고, 실제로 바꾼 범위가 서로 일치하는지 증명한다.

공개 배포를 위해 export-bluetape-skills도 추가했다. 이 script는 ~/.codex 전체를 무작정 복사하지 않는다. canonical 디렉터리 14개만 복사하고 retired alias, memory, rules, hooks, config, plugin cache는 export 대상에서 뺀다.

다음 변경을 안전하게 공유하려면

Skill을 수정할 때는 canonical source를 먼저 고치고, 공개 묶음으로 export한 뒤 검증한다. 공개 저장소의 skills/manifest.json은 배포 대상 목록을 기계가 읽을 수 있는 형태로 제공한다. 이름을 바꾸거나 reference를 추가했다면 manifest와 installer, 두 README, 검증 결과를 함께 확인해야 한다.

이 흐름은 조금 더디게 보일 수 있다. 하지만 다른 개발자가 설치한 뒤 reference 누락이나 개인 경로 때문에 작업을 멈추는 것보다는 훨씬 비용이 적다. 공유 가능한 skill은 문장만 잘 쓴 지침이 아니다. 다른 머신에서도 같은 구조로 설치하고 검증하며 업데이트할 수 있는 지침이다.

다음 글

설치 다음에는 실제 사용이 남는다. Part 2에서는 $bluetape-workflow가 요청을 어떻게 분류하는지 설명한다. 첫 계획 승인 전에는 왜 파일을 고치지 않는지, Action·Evidence·Failure checklist가 다음 단계를 어떻게 막거나 여는지도 살펴본다.

시리즈 글

• 먼저 읽기: AI와 일하는 환경을 인프라로 만들기
• Bluetape Skills Part 1: 팀과 공유하고 설치하는 방법
• Bluetape Skills Part 2: bluetape-workflow로 작업을 시작하는 방법
• Bluetape Skills Part 3: 중단된 workflow를 이어서 복구하는 방법

Repository

• bluetape4k/bluetape-skills