my-cursor는 잘 작동했지만, Agent Skill Garden으로 다시 시작했다

개인 AI 설정 저장소를 다시 설계한 과정을 바탕으로 썼다. 비공개 스킬과 업무 식별자는 제외하고, 공개 저장소에서 확인할 수 있는 구조와 판단만 다룬다.

한동안 나는 my-cursor라는 저장소를 잘 사용했다.

이름 그대로 개인 Cursor 설정을 관리하는 저장소였다. 자주 쓰는 스킬과 슬래시 커맨드, 반복 작업을 돕는 스크립트, Cursor 규칙을 모아두고 로컬 환경과 동기화했다. 공개 저장소에는 비공개 경로와 식별자를 제거한 버전을 올렸다. 새 환경에서는 저장소를 복제하고 설치 스크립트를 실행하면 익숙한 작업 환경을 다시 만들 수 있었다.

백업도 됐고, 설치도 됐고, 다른 사람에게 구조를 보여줄 수도 있었다.

그러니 my-cursor는 실패한 저장소가 아니다. 오히려 해결하려던 문제를 꽤 잘 해결했다.

그런데 Cursor 사용을 멈추고 Claude Code와 Codex를 함께 쓰기 시작하면서 저장소의 이름과 구조가 조금씩 어색해졌다. 도구는 바뀌었지만 내가 반복해서 맡기는 일은 남아 있었다. 작업을 시작하기 전에 범위를 정리하고, 변경 뒤에는 부작용을 확인하고, 외부 시스템을 바꾸기 전에는 권한을 구분하고, 끝났다고 말하기 전에 결과를 다시 읽어 확인하는 순서는 사라지지 않았다.

그때 질문이 바뀌었다.

내가 보존하려던 것은 Cursor 설정이었을까, 아니면 Cursor를 통해 다듬은 나의 업무 방식이었을까?

이 질문에 답하고 나니 기존 저장소를 계속 일반화하는 대신 새로운 공개 저장소에서 다시 시작해야 하는 이유가 보였다.

Agent Skill Garden은 그렇게 만들어졌다.

TL;DR

my-cursor는 Cursor 설정을 백업하고 설치하기 위한 공개 미러였다.
실제 사용 환경이 Cursor에서 Claude Code와 Codex로 넓어지자, 도구별 설정 파일보다 오래 남는 업무 절차가 보이기 시작했다.
비공개 원본에서 민감 정보를 제거해 공개본으로 동기화하면 원본과 사본이 계속 갈라지고, 공개 안전성은 마지막 필터에 의존하게 된다.
기존 저장소의 공개 범위를 넓히거나 이력을 고치는 대신, 공개 가능한 내용을 처음부터 작성하는 새 저장소를 만들었다.
공통 업무 절차는 core, 제품별 연결은 adapters, 선택과 안전성 검증은 evals와 scripts로 분리했다.
설치됐다는 사실과 실제로 쓰였다는 사실은 다르므로, 로컬 세션 기록에서 스킬 적용 근거와 반복 업무 범주를 확인하는 감사 순환을 넣었다.
목표는 프롬프트를 많이 공개하는 것이 아니라, 다른 개발자가 자기 업무에 맞게 복제하고 가꿀 수 있는 운영 구조를 공개하는 것이다.

my-cursor가 해결했던 문제

my-cursor를 만들 때 해결하고 싶었던 문제는 구체적이었다.

Cursor를 오래 쓰다 보니 개인 설정 아래에 여러 종류의 자산이 쌓였다.

특정 요청에서 사용하는 스킬
반복 실행하는 슬래시 커맨드
저장소나 브랜치를 다루는 보조 스크립트
항상 적용할 Cursor 규칙
외부 도구를 연결하는 설정 예시
나중에 다시 참고할 운영 메모

이것들을 로컬 디렉터리에만 두면 컴퓨터를 바꾸거나 설정이 꼬였을 때 복구하기 어렵다. 어떤 규칙이 현재 원본인지도 알기 어렵다. 그래서 저장소를 하나 만들고, 로컬 설정을 저장소로 동기화하고, 다시 저장소에서 로컬 환경으로 설치하는 흐름을 만들었다.

구조는 단순했다.

로컬 Cursor 설정
  -> 공개할 수 없는 내용 제거
  -> my-cursor에 동기화
  -> Git으로 이력 관리
  -> 새 환경에 다시 설치

이 구조의 장점은 분명했다.

첫째, 설정이 파일로 남았다. 프롬프트 입력창이나 기억 속에만 있던 작업 방식이 버전 관리 가능한 자산이 됐다.

둘째, 새 환경을 만드는 비용이 줄었다. 설치 스크립트와 경로 규칙이 있으니 매번 파일을 찾아 복사하지 않아도 됐다.

셋째, 공개할 수 있는 예시가 생겼다. 다른 사람이 나와 같은 설정을 그대로 쓸 필요는 없지만, 어떤 단위로 규칙과 스킬을 나눴는지는 참고할 수 있었다.

넷째, 동기화가 습관이 됐다. 로컬에서 유용한 규칙을 만들면 저장소로 옮기고, 저장소의 최신 상태를 다시 로컬에 반영했다.

이 시점의 목표가 “Cursor 개인 설정을 안전하게 백업하고 공유한다”였다면 my-cursor의 설계는 꽤 합리적이었다.

문제는 목표가 바뀌었다는 데 있었다.

잘 작동하던 구조가 어색해진 세 가지 이유

1. 저장소의 주어가 도구였다

my-cursor의 디렉터리는 Cursor가 이해하기 쉬운 단위로 구성돼 있었다. 규칙은 Cursor rules 경로에 있었고, 명령은 슬래시 커맨드 형식이었으며, 설치 역시 Cursor의 개인 설정 위치를 기준으로 했다.

이 구조는 Cursor 안에서는 자연스럽다.

하지만 Claude Code와 Codex를 함께 쓰기 시작하자 같은 업무 절차가 서로 다른 위치와 문법으로 표현됐다.

예를 들어 “요청에 맞는 스킬을 먼저 찾는다”는 원칙은 제품과 무관하다. 반면 스킬을 발견하는 디렉터리, 항상 읽히는 지침 파일, 명시적으로 스킬을 호출하는 방법은 제품마다 다르다.

도구 중심 저장소에서는 이 둘이 쉽게 섞인다.

오래 남는 판단
+ 특정 도구의 설정 문법
+ 특정 도구의 설치 경로
= 다른 도구로 옮기기 어려운 한 덩어리

Cursor가 주 사용 도구일 때는 이 결합이 불편하지 않았다. Cursor 사용을 멈추자 무엇이 Cursor의 편의 기능이고 무엇이 내가 계속 지키고 싶은 업무 원칙인지 다시 나눠야 했다.

2. 공개본이 원본의 뒤를 따라갔다

my-cursor의 공개 README 첫 문장은 이 저장소가 비공개 설정에서 민감 정보를 제거한 공개 미러라는 사실을 밝힌다.

이 방식에는 현실적인 이유가 있었다. 실제 환경에는 외부에 공개할 수 없는 경로와 식별자, 인증 정보, 업무 전용 절차가 섞일 수 있다. 그것들을 그대로 공개 저장소에 올릴 수는 없다. 그래서 동기화 단계에서 제외하거나 예시 값으로 바꿨다.

하지만 운영할수록 공개본은 원본의 사본이라는 사실이 부담이 됐다.

비공개 원본이 먼저 바뀐다.
동기화 스크립트가 공개 가능한 부분을 고른다.
민감 정보 제거 규칙이 누락되지 않았는지 확인한다.
공개 저장소가 최신 상태인지 다시 확인한다.
새 도구에서도 같은 의미인지 또 확인한다.

원본이 하나인 것처럼 보여도 실제로는 판단 지점이 여러 개였다.

특히 공개 안전성이 마지막 단계의 검색과 치환에 기대고 있다는 점이 마음에 걸렸다. 민감한 내용을 먼저 만든 뒤 나중에 잘 지우는 것보다, 공개 저장소에는 처음부터 공개 가능한 문장만 쓰는 편이 안전하다. 단순히 문자열을 바꾼다고 특정 조직에서만 의미가 있는 전제까지 범용 지식이 되는 것도 아니다.

공개할 수 없는 이름을 example.com으로 바꿔도, 절차 전체가 특정 조직의 시스템 구조를 전제로 한다면 다른 개발자에게는 쓸모가 없다.

그래서 공개 과정에는 민감 정보를 제거하는 것보다 한 단계 앞선 판단이 필요하다고 보게 됐다.

무엇을 지울 것인가가 아니라, 무엇을 범용 절차로 다시 쓸 가치가 있는가?

3. 설치를 사용으로 착각하기 쉬웠다

심볼릭 링크가 만들어지고 파일이 올바른 디렉터리에 있으면 설치는 성공한 것이다.

하지만 그 스킬이 실제 요청에서 선택됐다는 뜻은 아니다.

나는 이미 스킬 53개를 만들고 3개만 쓰고 있었다는 글에서 이 차이를 확인했다. 파일은 존재했지만 자연어 선택이 막혀 있거나, 설명에 적힌 문장과 내가 실제로 사용하는 말이 달라 스킬이 선택되지 않았다.

여러 도구에 같은 파일을 복사한다고 이 문제가 해결되지는 않는다. 오히려 다음 질문이 더 필요해진다.

호스트가 스킬을 발견했는가?
요청과 맞는 스킬을 골랐는가?
일반적인 탐색을 시작하기 전에 스킬을 읽었는가?
스킬에 적힌 권한 경계를 지켰는가?
작업 뒤에 결과를 다시 확인했는가?

my-cursor가 “설정을 복구할 수 있는가”를 잘 해결했다면, 다음 저장소는 “업무 절차가 실제로 선택되고 지켜지는가”까지 다뤄야 했다.

도구는 바뀌었지만 반복 업무는 남았다

Cursor 사용을 중단한 뒤에도 기존에 만들었던 모든 것이 사라지지는 않았다.

사라진 것은 특정 메뉴와 명령 형식, 설정 경로였다. 남은 것은 그 위에서 반복하던 판단이었다.

나는 Claude Code와 Codex에 서로 다른 일을 맡기고 있었다. Claude Code는 저장소 안에서 파일을 읽고 구현하는 작업에 오래 머무르는 경우가 많았다. Codex는 여러 도구와 문서를 오가며 확인하고, 작업을 조율하고, 반복 점검을 유지하는 경우가 많았다.

둘의 역할을 완전히 나눌 수는 없지만 자주 서는 자리는 달랐다.

그런데 다음 원칙은 두 도구 모두에 필요했다.

모호한 요청을 바로 구현하지 않고 작업 단위로 정리한다.
관련된 스킬이 있으면 일반 탐색보다 먼저 읽는다.
읽기 전용 조사와 외부 시스템 변경 권한을 구분한다.
코드 변경 뒤에는 직접 수정한 파일만 보지 않고 소비처와 실행 경로를 추적한다.
완료했다고 말하기 전에 실제 결과 상태를 다시 읽는다.
반복되는 실패는 다음 작업을 위한 규칙으로 남긴다.

이것은 Cursor의 기능 목록도, Claude Code의 명령어도, Codex의 도구 이름도 아니다.

내가 여러 에이전트에게 기대하는 업무 방식이었다.

같은 규칙, 다른 일에서 썼듯이, 여러 에이전트의 실행법과 로그 형식까지 같게 만들 수는 없다. 그래도 어떤 판단을 먼저 하고 어떤 상태를 완료로 볼지는 공유할 수 있다.

여기서 저장소의 새로운 주어가 정해졌다.

Cursor가 어떻게 동작해야 하는가
        ↓
내가 반복하는 업무를 에이전트가 어떻게 처리해야 하는가

도구가 저장소의 주인이 아니라 어댑터가 되어야 했다.

기존 저장소를 고치지 않고 새로 시작한 이유

처음에는 my-cursor의 이름을 바꾸고 디렉터리를 일반화할 수도 있다고 생각했다.

하지만 그렇게 하면 기존 저장소가 해결하던 문제와 새 저장소가 해결하려는 문제가 한 이력 안에 섞인다.

my-cursor는 다음 사실을 솔직하게 보여주는 기록이다.

Cursor를 중심으로 개인 설정을 관리했다.
로컬 설정을 저장소로 동기화했다.
공개할 수 없는 내용을 제거한 미러를 운영했다.
스킬과 슬래시 커맨드, 스크립트를 함께 관리했다.

그 이력을 억지로 “원래부터 멀티 에이전트용이었다”는 모습으로 바꾸고 싶지 않았다.

기존 비공개 저장소의 visibility를 바꾸는 것도 선택하지 않았다. 현재 트리에서 민감한 파일을 지우더라도 Git 이력에는 남을 수 있다. 공개 전에 전체 이력을 다시 감사하거나 history rewrite를 해야 한다. 더 중요한 문제는 민감 정보만 제거한다고 공개 프로젝트의 목적이 생기지는 않는다는 점이다.

그래서 새 저장소에는 깨끗한 기준을 적용했다.

공개 가능한 내용만 처음부터 작성한다.
실제 환경에서 가져올 때는 파일을 복사하지 않고 판단과 절차를 다시 쓴다.
특정 조직과 프로젝트를 알아야만 이해할 수 있는 절차는 넣지 않는다.
제품별 차이는 어댑터로 격리한다.
다른 개발자가 복제해도 안전한 설치와 검증 경로를 함께 제공한다.

이 결정은 마이그레이션보다 승격(promotion)에 가깝다.

private configuration
  -> 반복해서 유효했던 판단 발견
  -> 특정 조직과 도구의 전제 제거
  -> 공개 가능한 절차로 다시 작성
  -> 합성 사례와 설치 흐름으로 검증
  -> public core로 승격

기존 파일을 정기적으로 복사하는 동기화와는 목적이 다르다.

동기화는 두 위치를 같게 만드는 일이다. 승격은 실제 경험 중 다른 사람에게도 유효한 부분을 선택해 새로운 원본으로 만드는 일이다.

두 저장소를 나란히 놓고 보니

변화를 가장 짧게 정리하면 다음과 같다.

	`my-cursor`	`agent-skill-garden`
출발점	Cursor 개인 설정	반복되는 실제 개발 업무
공개 방식	비공개 설정에서 민감 정보를 제거한 미러	공개 가능한 내용을 처음부터 작성
관리 방식	로컬 설정을 저장소로 동기화	검증된 판단을 공개 코어로 승격
구성 단위	rules, commands, scripts	policies, skills, adapters, evals
도구 범위	Cursor 중심	Cursor 경험, Claude Code·Codex 적용
설치 목표	Cursor 환경 복구	호스트별 발견 경로 연결
완료 기준	파일이 설치·동기화됨	선택·실행·검증·감사 근거가 있음
공개 가치	개인 환경 참고	자기 업무 체계로 복제하는 출발점

이 표에서 가장 중요한 행은 “구성 단위”보다 “완료 기준”이다.

파일을 어디에 둘지는 문서로 해결할 수 있다. 하지만 에이전트가 그 절차를 실제로 적용하고, 변경 권한을 지키고, 결과를 검증했는지는 별도의 운영 문제가 된다.

새 저장소는 그 문제를 피하지 않기로 했다.

core에는 도구 이름보다 오래 갈 것을 둔다

Agent Skill Garden의 core에는 두 가지가 있다.

core/
  policies/  # 여러 업무에 공통으로 적용할 원칙
  skills/    # 특정 요청에서만 불러올 절차

현재 공개판에는 9개의 스킬만 넣었다.

모호한 요청을 작업 단위로 정리하는 intake
시작 전 상태를 확인하는 work-start
작업 성격과 분할 방식을 정하는 work-triage
배포를 막을 문제에 집중하는 critical-review
소비처와 회귀 경로를 추적하는 side-effect-check
여러 에이전트의 작업 충돌을 확인하는 collaboration-awareness
완료 조건과 인수인계를 정리하는 work-closeout
스킬 사용 근거를 확인하는 skill-usage-audit
스킬을 유지·개선·병합·정리하는 workflow-maintenance

개인 환경에 있는 모든 스킬을 옮기지 않았다.

많이 공개하는 것이 목적이라면 목록은 더 길어질 수 있다. 하지만 목록이 길어질수록 설명 메타데이터가 차지하는 컨텍스트도 늘고, 비슷한 스킬끼리 요청을 두고 경쟁하며, 외부 사용자는 어디서 시작해야 할지 알기 어려워진다.

대표적인 업무 흐름을 보여주면서도 서로의 역할을 설명할 수 있는 정도로 줄였다.

공통 정책은 세 가지로 더 작게 만들었다.

Skill-first

요청과 맞는 스킬이 있다면 일반적인 저장소 탐색이나 브라우저 조작보다 먼저 읽는다. 사용자가 정확한 스킬 이름이나 슬래시 명령을 알 필요는 없다. 사용자의 자연스러운 표현이 라우팅 인터페이스가 되어야 한다.

Change boundary

스킬을 선택했다는 사실이 외부 변경 권한을 뜻하지 않는다. 분석, 초안, 로컬 파일 변경, GitHub·메신저·티켓·배포 같은 외부 변경을 구분한다.

Verification

명령이 성공했다고 결과까지 성공한 것은 아니다. 변경 후 실제 상태를 다시 읽고, 확인하지 못한 부분은 통과가 아니라 제한 사항으로 남긴다.

이 세 가지는 특정 도구의 기능이 아니다. 모델이나 제품이 바뀌어도 오래 가져가고 싶은 작업 기준이다.

제품별 차이는 어댑터에 둔다

공통 SKILL.md 안에 Claude Code, Codex, Cursor의 설정 문법을 모두 넣으면 스킬 본문이 빠르게 복잡해진다.

그래서 제품별 차이는 adapters에 둔다.

adapters/
  claude/
  codex/
  cursor/

어댑터가 담당하는 것은 다음과 같다.

각 호스트가 스킬을 찾는 경로
항상 읽는 지침 파일에 넣을 최소한의 라우팅 원칙
호스트에서만 의미가 있는 설정 문법
현재 확인한 호환 범위

Cursor와 Codex는 공통 .agents/skills를 사용하고, Claude Code는 .claude/skills를 사용한다. Cursor의 현재 Agent Skills 문서에도 .agents/skills가 탐색 경로로 안내돼 있다.

중요한 것은 같은 스킬 본문을 세 벌 만들지 않는 것이다.

core/skills/intake
  ├─ Claude Code가 자기 탐색 경로에서 발견
  ├─ Codex가 자기 탐색 경로에서 발견
  └─ Cursor가 자기 탐색 경로에서 발견

같은 내용을 세 위치에 복사하면 언젠가 한쪽만 수정된다. 새 저장소의 설치기는 하나의 원본 스킬을 각 탐색 경로에 심볼릭 링크로 연결한다.

어댑터는 “세 도구가 완전히 같다”는 주장이 아니다. 오히려 무엇이 공통이고 무엇이 다른지 드러내는 경계다.

설치기는 기존 환경을 침범하지 않아야 했다

공개 저장소를 clone할 수 있다고 해서 다른 개발자가 자기 환경에 안전하게 적용할 수 있는 것은 아니다.

개인 AI 설정에는 이미 사용 중인 규칙과 스킬이 있을 수 있다. 설치 스크립트가 같은 이름의 디렉터리를 덮어쓰면 다른 사람의 작업 방식을 망가뜨린다.

그래서 설치기는 기본적으로 아무것도 바꾸지 않는다.

./scripts/install.sh \
  --target all \
  --scope project \
  --root work/demo-project \
  --skill intake \
  --skill critical-review

이 명령은 실제 설치 대신 PLAN을 출력한다. 사용자가 원본과 목적지를 확인한 뒤 --apply를 붙여야 심볼릭 링크를 만든다.

동일한 이름의 경로가 있으면 SKIP으로 알리고 종료한다. 자동 병합도, 자동 덮어쓰기도 하지 않는다.

전체 9개를 한 번에 설치할 수 있지만 문서에서는 2~3개로 시작하라고 권한다. 작은 목록이 라우팅을 관찰하고 실패 원인을 찾기 쉽기 때문이다.

이 과정에서 공개 저장소다운 작은 문제도 만났다.

선택 설치는 잘 됐지만 전체 설치 스모크 테스트가 macOS 기본 Bash에서 실패했다. 빈 배열과 set -u의 조합이 최신 Bash와 다르게 동작했기 때문이다. 선택한 스킬 개수를 별도로 관리하도록 고치고, macOS와 Ubuntu CI에서 전체 설치와 선택 설치를 함께 확인하도록 만들었다.

내 환경에서 한 번 성공한 스크립트와 다른 개발자가 복제할 수 있는 스크립트는 다르다.

“설치됨” 다음에 “사용됨”을 확인한다

스킬 파일이 탐색 경로에 있다는 사실은 설치 근거다.

새 세션의 목록에서 보인다면 발견 근거가 된다.

같은 요청에서 SKILL.md를 읽었다면 적용 근거가 된다.

스킬 절차대로 안전 경계와 완료 조건을 지켰다면 비로소 실행 품질을 이야기할 수 있다.

filesystem presence
  -> 호스트 탐색
  -> 요청 라우팅
  -> procedure execution
  -> result verification

이 단계들을 하나로 뭉쳐 “잘 된다”고 말하지 않으려고 했다.

저장소에는 합성 라우팅 사례를 넣었다. 각 사례는 자연어 요청, 기대하는 스킬, 발생하면 안 되는 외부 변경을 함께 가진다.

예를 들어 리뷰 요청이라면 단순히 critical-review가 선택됐는지만 보지 않는다. 사용자가 요청하지 않은 GitHub 리뷰 게시가 일어나지 않아야 한다. 작업 시작 요청이라면 상태를 확인할 수 있지만, 명시하지 않은 브랜치 변경이나 티켓 상태 변경은 하지 않아야 한다.

스킬 선택과 부작용을 일으킬 권한은 별도 계약이다.

이 구분이 중요한 이유는 에이전트가 더 많은 도구에 연결될수록 “할 수 있음”과 “해도 됨”의 거리가 커지기 때문이다.

외부 Grafana 없이도 개인 사용 순환은 만들 수 있었다

스킬을 운영하려면 결국 실제 사용 기록을 봐야 한다.

어떤 요청이 반복됐는지, 관련 스킬이 있었는지, 스킬을 늦게 읽지는 않았는지 확인하지 않으면 목록은 다시 쌓이기만 한다.

처음에는 이 과정에 외부 대시보드나 관측 시스템이 필요하다고 생각하기 쉽다. 팀 전체의 비용과 성능을 운영하려면 그런 도구가 필요할 수 있다.

하지만 한 개발자가 자기 스킬을 가꾸기 위한 첫 단계에는 이미 로컬에 충분한 근거가 남아 있다.

Claude Code의 로컬 세션
Codex의 로컬 세션
명시적인 스킬 호출
SKILL.md를 읽은 도구 호출
요청과 도구 호출의 순서

Agent Skill Garden의 skill-usage-audit는 이 기록을 로컬에서 읽는다.

python3 core/skills/skill-usage-audit/scripts/audit_usage.py --days 7

결과에는 프롬프트 원문을 넣지 않는다. 요청은 메모리에서 키워드 기반 업무 범주로 분류하고 다음과 같은 집계만 출력한다.

최근 요청에서 자주 나타난 업무 범주
스킬 적용 근거가 있었던 요청
일반 도구보다 먼저 스킬을 읽은 요청
설치됐지만 해당 기간에 근거를 찾지 못한 스킬
반복되지만 스킬 근거가 약한 업무 범주

이 결과를 “나는 이 업무에 시간을 가장 많이 썼다”라고 읽으면 안 된다. 요청 수는 작업 시간과 같지 않고, 자동화나 긴 작업은 이벤트 수를 다르게 만든다.

대신 다음 질문을 던지는 신호로 사용한다.

내가 생각하는 집중 업무와 반복 요청의 범주가 비슷한가?
같은 요청을 매번 처음부터 설명하고 있지는 않은가?
스킬은 있는데 설명이 내 실제 말투와 어긋나지 않았는가?
비슷한 스킬이 너무 많아 서로 경쟁하지 않는가?
지금은 더 이상 쓰지 않는 복잡성을 유지하고 있지 않은가?

나도 모르게 자주 맡기고 있는 일을 정리하면, 내가 최근 무엇에 집중하고 있는지도 보이기 시작한다.

다만 이것은 생산성 점수도, 근무 시간 측정도 아니다. 개인 워크플로를 개선하기 위한 탐색 도구다.

실제 로그를 읽자 파서도 틀렸다는 것을 알게 됐다

합성 픽스처를 통과한 감사 스크립트를 실제 로컬 기록에 실행했을 때 첫 결과는 이상했다.

Codex의 사용자 역할 이벤트를 단순히 세자 과거 대화가 현재 요청처럼 반복해서 잡혔다. 서로 다른 세션의 턴 식별자를 하나로 합칠 가능성도 있었다. 그 결과 실제 집중 업무가 아니라 주입된 맥락 속 단어가 상위 범주를 차지했다.

역할이 user라고 모두 사람이 새로 입력한 요청은 아니었다.

파서를 실제 신규 사용자 이벤트 기준으로 바꾸고, 스킬 근거는 같은 세션과 turn 흐름 안에서만 연결했다. 원문이 결과에 포함되지 않는지도 테스트로 고정했다.

이 경험은 저장소가 지키려는 태도와 잘 맞았다.

숫자가 나왔다는 사실은 측정이 유효하다는 뜻이 아니다.

정적 검사와 합성 픽스처는 필요하지만 실제 실행 경로를 완전히 대신하지 못한다. 반대로 실제 로그만 보고 코드를 계속 바꾸면 개인정보와 재현성 문제가 생긴다.

그래서 순환을 두 층으로 나눴다.

공개 저장소
  -> 정적 검증
  -> 합성 라우팅 사례
  -> parser unit test

개인 로컬 환경
  -> 집계형 사용 감사
  -> 필요한 경우에만 제한된 원문 진단
  -> keep / tune / merge / retire 판단

공개 저장소에는 합성 사례와 집계 결과의 계약만 남긴다. 실제 대화 원문은 올리지 않는다.

토큰을 줄일 수 있다는 말도 작게 했다

스킬을 필요할 때만 읽으면 모든 절차를 항상 컨텍스트에 넣는 것보다 비용을 줄일 가능성이 있다.

하지만 “몇 퍼센트의 토큰을 절약한다”는 숫자는 만들지 않았다.

호스트마다 스킬 목록을 모델에 노출하는 방식이 다르고, 모델마다 토크나이저가 다르며, 같은 스킬을 읽어도 작업 성공률과 재시도 횟수가 달라질 수 있다. 문자 수만 보고 실제 토큰 절감률을 단정할 수 없다.

대신 저장소가 통제할 수 있는 것만 측정한다.

항상 보이는 skill metadata의 문자 수
요청할 때만 읽는 skill body의 문자 수
스킬 목록이 정한 예산을 넘는지
비슷한 설명이 불필요하게 길어지는지

python3 scripts/context_report.py

실제 토큰 비용을 말하려면 같은 종류의 요청을 같은 조건에서 전후 비교하고 제공자가 기록한 사용량을 확인해야 한다.

목표는 가장 짧은 프롬프트가 아니다.

성공적으로 끝낸 업무 하나당 필요한 컨텍스트와 재탐색을 줄이는 것.

이 정도가 지금 공개 저장소에서 정직하게 주장할 수 있는 범위다.

무엇을 옮기지 않았는가

새 저장소를 만들 때 무엇을 넣었는지만큼 무엇을 넣지 않았는지가 중요했다.

개인 환경의 모든 스킬

공개 가치가 분명한 대표 절차만 골랐다. 반복해서 썼다는 이유만으로 특정 조직의 업무 절차를 공개할 수는 없고, 다른 사람에게 재사용 가치가 없는 스킬도 있다.

비공개 연결 정보

인증 정보, 내부 URL, 개인 경로, 실제 메시지와 티켓, 고객 정보, 로컬 인증서는 넣지 않았다.

특정 제품의 명령 문법

공통 절차 안에는 가능한 한 제품 명령을 넣지 않았다. 필요한 내용은 어댑터나 별도 문서에 둔다.

실제 대화 원문

감사 스크립트는 로컬에서만 원문을 읽고 집계 결과를 출력한다. 공개 예제는 합성 문장으로 작성한다.

자동 변경

사용량이 낮다고 스킬을 자동으로 삭제하지 않는다. 호출 근거가 없다는 사실은 발견 실패, 로그 누락, 최근에 해당 업무가 없었던 상황을 모두 포함할 수 있다.

거대한 범용 프레임워크라는 주장

Agent Skills 설치, 평가, 동기화, 사용량 분석을 다루는 다른 프로젝트는 이미 있다. Agent Skill Garden은 새로운 표준을 발명했다고 주장하지 않는다.

경쟁력은 개별 기능의 최초 구현보다 다음이 한 흐름으로 연결돼 있다는 데 있다.

실제 업무
  -> 반복 절차 발견
  -> 공개 가능한 스킬로 승격
  -> 호스트 어댑터로 연결
  -> 안전하게 설치
  -> synthetic eval
  -> local audit
  -> keep / tune / merge / retire

이것은 내가 실제로 사용하는 환경을 다른 개발자가 복제 가능한 형태로 정리한 참조 구현이다.

다른 개발자는 어디서 시작하면 될까

저장소를 clone한 뒤 모든 스킬을 설치할 필요는 없다.

첫 단계는 자기 업무에서 반복되는 요청 두세 개를 떠올리는 것이다.

예를 들면 다음과 같다.

모호한 요청을 받으면 항상 범위와 완료 조건부터 정리한다.
코드 변경 뒤에는 직접 수정한 파일 밖의 소비처를 확인한다.
작업이 끝나면 테스트뿐 아니라 실제 변경 상태와 인수인계를 정리한다.

그 절차와 가까운 스킬만 임시 프로젝트에 설치한다.

git clone https://github.com/changbaebang/agent-skill-garden.git
cd agent-skill-garden
./scripts/validate.sh

mkdir -p work/demo-project
./scripts/install.sh \
  --target all \
  --scope project \
  --root work/demo-project \
  --skill intake \
  --skill side-effect-check

dry run의 목적지를 확인한 뒤 --apply한다.

그다음 새 세션에서 세 종류의 요청을 시험한다.

스킬이 분명히 선택돼야 하는 요청
평소 자신이 실제로 사용하는 자연스러운 문장
비슷해 보이지만 해당 스킬을 사용하면 안 되는 요청

설치 경로만 확인하고 끝내지 않는다. 어떤 스킬을 읽었는지, 스킬보다 다른 도구를 먼저 사용하지 않았는지, 요청하지 않은 외부 변경이 없었는지 확인한다.

며칠 사용한 뒤 로컬 감사를 실행하고 다음 중 하나를 결정한다.

keep: 역할과 트리거가 분명하다.
tune: 실제 말투가 설명에 없다.
merge: 비슷한 스킬이 같은 요청에서 경쟁한다.
retire: 유지 비용에 비해 현재 가치가 없다.
create: 반복 요청이 있지만 안정적인 절차가 아직 없다.

garden이라는 이름은 이 순환에서 나왔다.

스킬은 한 번 만들어 영구 보관하는 명령 목록이 아니다. 실제로 쓰이는 것은 가꾸고, 경쟁하는 것은 합치고, 더 이상 필요하지 않은 것은 정리해야 한다.

포트폴리오로서 보여주고 싶었던 것

공개 저장소를 포트폴리오로 사용하려면 파일 개수보다 판단이 보여야 한다고 생각했다.

누구나 SKILL.md를 하나 만들 수 있다. 인터넷에는 더 많은 스킬 목록과 더 정교한 에이전트 프레임워크가 있다.

내가 보여줄 수 있는 것은 다른 종류의 경험이다.

실제 업무에서 반복 절차를 발견한 과정
자연어 트리거와 라우팅 실패를 수정한 경험
read-only 분석과 외부 mutation 권한을 나눈 기준
여러 호스트의 공통 정책과 서로 다른 증거를 구분한 판단
비공개 설정을 그대로 공개하지 않으면서 범용 지식을 남긴 방법
설치, 검증, 감사, 유지보수를 하나의 순환으로 연결한 구조
측정할 수 없는 토큰 절감률과 생산성 수치를 과장하지 않은 경계

my-cursor도 이 이야기에서 숨길 필요가 없다.

오히려 이전 저장소가 있기 때문에 왜 새 저장소가 필요한지 설명할 수 있다. 처음부터 완성된 구조를 설계한 것이 아니라, 실제로 백업하고 동기화하고 도구를 바꿔본 뒤 무엇이 오래 남는지 알게 됐다는 증거이기 때문이다.

my-cursor는 당시의 문제를 해결한 기록으로 남는다.

Agent Skill Garden은 지금 해결하고 싶은 문제의 시작점이 된다.

이전 글에서 한 단계 더 나아간 것

지난 AI 도구를 바꾸는 비용을 낮추는 법에서는 작업 규칙을 제품 밖에 두면 도구를 바꿀 때 다시 만들 것이 줄어든다고 썼다.

그다음에는 스킬이 파일로 존재하는 것과 실제로 선택되는 것이 다르다는 사실을 확인했다. Claude Code와 Codex가 같은 정책을 서로 다른 이벤트와 증거로 보여준다는 점도 정리했다.

이번 저장소에서는 그 경험을 공개 구조로 묶었다.

도구 밖에 규칙을 둔다
  -> 실제로 선택되는지 확인한다
  -> 호스트마다 다른 증거를 구분한다
  -> 다른 개발자가 복제할 수 있게 공개한다

전에는 내 환경을 옮기는 것이 목표였다.

지금은 내 환경에서 유효했던 판단을, 다른 사람이 자기 환경에서 검증할 수 있는 형태로 제공하는 것이 목표다.

아직 끝난 것은 아니다

공개 저장소를 만들었다고 구조가 완성된 것은 아니다.

이제 해야 할 일은 공개판을 실제 Claude Code와 Codex 환경에 적용하고 계속 사용하는 것이다.

공개판의 설명만으로 자연어 라우팅이 잘 되는가?
두 호스트에서 같은 정책이 의도한 결과를 만드는가?
선택 설치가 기존 개인 스킬과 충돌하지 않는가?
합성 eval이 실제 실패를 충분히 대표하는가?
로컬 감사 범주가 지나치게 거칠거나 편향되지 않았는가?
9개 중 실제로 유지할 가치가 없는 스킬은 없는가?

이 질문은 README 한 번으로 답할 수 없다.

일정 기간 직접 사용한 뒤 어떤 스킬을 유지하고, 트리거를 바꾸고, 합치고, 정리했는지 다시 기록할 생각이다. 공개판도 내 개인 환경과 마찬가지로 정원이라면 자라거나 줄어들어야 한다.

변화가 없다는 것은 완성됐다는 뜻보다 관찰하지 않고 있다는 뜻일 수 있다.

마무리

my-cursor는 내 Cursor 환경을 복원하기 위한 저장소였다.

Agent Skill Garden은 내가 반복하는 업무 방식을 발견하고 가꾸기 위한 저장소다.

둘의 차이는 지원하는 도구 개수만이 아니다.

설정을 보관한다
        ↓
판단과 절차를 보존한다

비공개 원본에서 민감 정보를 제거한다
        ↓
공개 가능한 지식을 처음부터 작성한다

파일을 동기화한다
        ↓
유효한 절차를 승격한다

설치 여부를 확인한다
        ↓
선택·실행·검증 근거를 확인한다

다시 시작한 이유는 이전 저장소가 실패했기 때문이 아니다.

잘 사용해봤기 때문에 다음에는 무엇을 저장소의 주인으로 삼아야 하는지 알게 됐다.

도구는 바뀐다. 탐색 경로도 바뀌고, 설정 문법과 로그 형식도 바뀐다.

하지만 모호한 일을 정리하고, 필요한 절차를 먼저 찾고, 변경 권한을 구분하고, 결과를 검증하는 방식은 더 오래 남는다.

내가 공개하고 싶었던 것도 결국 프롬프트 파일이 아니었다.

여러 AI 에이전트를 같은 업무 기준으로 운영하고, 그 기준이 실제로 쓰이는지 확인하며, 다시 개선하는 방법.

Agent Skill Garden은 그 방법을 공개 가능한 형태로 다시 시작한 첫 버전이다.