공개 저장소 Agent Skill Garden에 AI 작업 환경에서 쓰던 스킬을 하나씩 옮기고 있다. 브랜치 정리, E2E 검증, 블로그 작성, 프론트엔드 리뷰처럼 반복해 온 절차를 다른 환경에서도 사용할 수 있는 형태로 정리했다. 이 작업을 시작한 배경은 개인 설정에서 공개 스킬 가든으로 옮긴 기록에 먼저 적었다.

스킬이 늘어나자 다음 질문이 생겼다.

새 기기에서 이 저장소만 클론하면 지금의 작업 환경을 다시 만들 수 있을까?

스킬 파일만 설치하는 것으로는 부족했다. 에이전트가 스킬을 먼저 찾게 하는 사용자 규칙이 필요하고, 블로그 저장소나 초안 경로처럼 사용자마다 다른 값도 연결해야 한다. 그렇다고 현재 ~/.codex를 통째로 공개 저장소에 넣을 수는 없다. 그 안에는 기기 설정, 인증 상태, 특정 환경에서만 유효한 규칙이 함께 들어 있기 때문이다.

그래서 설정을 백업하는 대신, 새 환경에서 작업 기반을 다시 조립하는 방법을 만들고 PR #6으로 병합했다.

~/.codex를 그대로 백업하지 않은 이유

처음 떠올리기 쉬운 방법은 현재 설정 디렉터리를 저장소에 올리는 것이다.

현재 ~/.codex
  -> Git 저장소에 백업
  -> 새 기기에서 그대로 복원

빠르지만 경계가 모호하다. 이 디렉터리에는 서로 성격이 다른 정보가 섞일 수 있다.

  • 여러 환경에서 계속 쓰고 싶은 판단 규칙
  • Codex에서 스킬을 발견하게 하는 사용자 지침
  • 현재 기기의 저장소와 문서 경로
  • 특정 서비스의 workspace와 channel 별칭
  • provider 설정과 인증 상태
  • 한 조직 안에서만 유효한 절차와 용어
  • 대화 기록과 임시 실행 상태

이것을 한 덩어리로 복원하면 공개할 수 없는 정보가 따라가고, 새 환경에 맞지 않는 경로와 권한도 함께 살아난다. 업무 환경에서 유효했던 규칙이 개인 환경에서도 적용될 수 있고, 반대로 개인 발행 경로가 다른 환경과 섞일 수도 있다.

가져가야 하는 것은 디렉터리의 현재 모습이 아니라, 그 환경을 다시 만들 수 있는 구조와 절차였다.

네 영역으로 나눴다

이번 작업에서는 스킬과 설정을 네 영역으로 구분했다.

영역 들어가는 것 저장 위치
Core workflow 재사용 가능한 판단, 절차, 검증, 안전 경계 공개 core/
Integration recipe Jekyll, Slack 같은 서비스·엔진의 공통 동작 공개 integrations/
Environment profile 실제 경로, 저장소, 브랜치, URL, workspace, 별칭 로컬 또는 개인 비공개 저장소
Private extension 특정 조직에서만 통하는 정책과 업무 절차 비공개 스킬

예를 들어 블로그 글을 쓰고 발행하는 순서는 공용 워크플로가 될 수 있다. Jekyll 저장소에서 _posts로 옮기고 공개 URL을 확인하는 방식도 재사용 가능한 integration이다.

하지만 내 블로그 저장소가 어디에 있는지, 초안을 어느 폴더에 두는지, 공개 주소가 무엇인지는 내 환경값이다. 내가 선호하는 문체도 부트스트랩 설정이 아니라 별도의 글쓰기 프로필에 남아야 한다.

이 경계가 생기면 공개 스킬 안의 경로를 찾아 바꾸지 않아도 된다. 새 사용자는 공용 절차를 그대로 두고 자기 프로필만 채우면 된다.

새 환경에서 부트스트랩하기

새 기기에서는 저장소를 클론한 뒤 다음 명령을 실행한다.

./scripts/bootstrap.sh --target codex

기본 동작은 dry run이다. 실제로 만들 파일과 링크를 PLAN으로 보여줄 뿐 아무것도 변경하지 않는다. 내용을 확인한 뒤에만 적용한다.

./scripts/bootstrap.sh --target codex --apply

Codex 기준으로 준비하는 것은 세 가지다.

~/.codex/AGENTS.md
  -> 스킬 우선 선택과 변경 권한, 검증에 관한 사용자 규칙

~/.agents/skills
  -> 공개 저장소의 canonical skills를 가리키는 링크

~/.agent-garden/profile.ini
  -> 이 기기에서 사용할 경로와 integration 설정

스킬은 저장소를 가리키는 심볼릭 링크로 설치한다. 저장소를 안정적인 경로에 두고 업데이트하면 연결된 스킬도 함께 갱신된다. 반면 사용자 규칙과 프로필은 기존 파일이 있으면 덮어쓰지 않는다. 새 환경 초기화와 기존 설정 병합은 다른 작업이기 때문이다.

공개 템플릿은 아무 서비스도 사용한다고 가정하지 않는다

환경 프로필의 공개 예시에는 블로그와 Slack 설정 모양이 들어 있다.

[profile]
schema_version = 1
name = personal
visibility = local

[integration.blog]
enabled = false
driver = jekyll-git
repository = ~/Sites/example-blog
drafts = ~/Documents/example-blog-drafts

중요한 값은 enabled = false다. 예시 경로가 있다는 이유만으로 해당 서비스가 준비됐다고 판단하지 않는다. 사용자가 실제 경로를 입력하고 integration을 활성화해야 한다.

개인 프로필은 기본적으로 ~/.agent-garden/profile.ini에 둔다. 여러 기기에서 같은 값을 관리해야 한다면 개인 비공개 저장소에 보관하고 환경변수로 선택할 수도 있다.

AGENT_GARDEN_PROFILE="$HOME/path/to/private-profile.ini" \
  ./scripts/bootstrap.sh --target codex --apply

프로필에는 경로와 별칭만 둔다. token, password, cookie, API key, private key 같은 인증 정보는 넣지 않는다. 프로필이 어떤 발행 방식이나 메시징 작업공간을 설명하더라도, 그것이 commit, push, 발행, 메시지 전송 권한을 뜻하지도 않는다.

복구하지 않는 것도 계약이다

부트스트랩이 의도적으로 다루지 않는 항목이 있다.

  • ~/.codex/config.toml
  • provider 인증과 connector 로그인
  • token, cookie, SSH key
  • 대화 기록과 telemetry
  • 조직 전용 규칙과 내부 식별자
  • 외부 시스템을 변경할 권한

이것은 아직 구현하지 못한 목록이 아니다. 공개 저장소가 복구해서는 안 되는 범위다.

인증은 새 환경의 호스트에서 다시 설정하고, 비공개 정책은 별도의 저장소나 로컬 스킬에서 관리한다. 읽기 가능한 도구가 연결됐다고 쓰기 권한까지 얻은 것으로 간주하지 않는다. 복구 대상을 명시하는 것만큼 복구하지 않을 대상을 고정하는 것도 중요했다.

글을 쓰면서 PR을 다시 검증했다

이 글을 정리하면서 PR을 네 가지 질문으로 다시 읽었다.

1. 공개 템플릿이 작성자의 환경을 정답으로 두고 있지 않은가?

모든 integration은 비활성 상태로 시작한다. 개인 경로와 서비스 별칭은 공용 스킬이 아니라 로컬 프로필에만 들어간다.

2. 기존 설정을 조용히 덮어쓸 수 있는가?

기존 AGENTS.md나 같은 이름의 스킬이 있으면 충돌로 중단한다. 자동 백업이나 자동 병합도 하지 않는다. 사용자가 기존 설정과 공개 adapter를 직접 비교해야 한다.

3. 잘못된 프로필로 일부 파일만 설치될 수 있는가?

기존 프로필이 있으면 설치 전에 doctor를 실행한다. schema가 잘못됐거나 활성화한 블로그 경로가 존재하지 않거나 비밀 정보를 나타내는 키가 있으면 설치를 시작하지 않는다.

4. 프로필이 외부 변경 권한을 암묵적으로 부여하는가?

프로필은 사용 가능한 사실과 연결 방식만 설명한다. commit, push, 발행, 메시지, 배포 같은 외부 변경은 현재 대화에서 별도의 명시적 요청이 필요하다.

기능 목록으로 읽을 때는 bootstrap.sh, profile.ini, doctor가 각각 따로 보였다. 글로 설명해 보니 세 요소가 같은 질문에 답하고 있는지 확인할 수 있었다.

공개할 수 있는 작업 방식과 공개하면 안 되는 환경 상태를 어디에서 나눌 것인가?

설명하기 어려운 부분이 있었다면 문장 문제가 아니라 설계 경계가 덜 정리된 것일 가능성이 컸다. 이번에는 네 질문 모두 코드와 문서에서 같은 답을 가리키고 있었다.

새 스킬에도 같은 질문을 적용한다

환경 프로필을 한 번 만들고 끝내면 시간이 지나면서 다시 개인 설정이 스킬 안으로 들어갈 수 있다. 그래서 새 스킬을 공개 저장소에 추가하거나 비공개 스킬을 옮길 때, 먼저 다음 질문을 하도록 workflow-maintenance에 넣었다.

재사용 가능한 판단인가?             -> core
서비스의 공통 동작인가?              -> integrations
실제 경로와 저장소, URL, 별칭인가?   -> local profile
조직 안에서만 유효한 절차인가?       -> private extension

한 스킬에 여러 종류가 섞여 있으면 파일명만 일반화하지 않고 분리한다. 다른 사용자가 SKILL.md를 열어 내 경로를 자기 경로로 바꿔야 한다면 아직 이식 가능한 스킬이 아니다.

현재 상태

PR #6에는 다음 변경이 들어 있다.

  • Codex, Claude Code, Cursor 사용자 환경을 위한 보수적인 부트스트랩
  • 공개 워크플로와 환경값을 구분하는 environment-profile
  • 로컬·개인 비공개·팀 프로필의 가시성 계약
  • Jekyll Git과 host connector 방식의 Slack 연동 계약
  • 기존 설정 충돌과 잘못된 프로필을 막는 검사
  • 새 환경 복구 절차를 담은 한국어·영어 문서
  • 새 스킬을 네 영역으로 분류하는 유지보수 규칙

공개 스킬 21개, 자연어 라우팅 사례 27개, 단위 테스트 22개를 검증했다. context budget과 공개 안전성 검사, GitHub Actions를 모두 통과한 뒤 main에 병합했다.

설정이 아니라 경험을 가져간다

블로그 스킬을 공개했을 때는 내 문체와 경로를 넣는 대신, 각 사용자가 자기 블로그에서 프로필을 만드는 절차를 남겼다. 이번에는 그 질문을 개인 AI 작업 환경 전체로 넓혔다.

환경을 옮긴다는 것은 이전 디렉터리를 완벽하게 복사하는 일이 아니었다. 여러 환경에서 계속 유효한 판단과 절차를 공개 저장소에 남기고, 새 환경에서 달라지는 값은 작은 프로필로 다시 연결하는 일에 가까웠다.

그래서 이번 PR은 ~/.codex의 백업이 아니다.

지금의 설정을 보존한 것이 아니라, 다음 환경에서 다시 시작할 수 있는 계약을 만들었다.