만약 당신의 팀이 AI 코딩 에이전트 (AI coding agents)를 위한 기술 (skills)을 사용하기 시작했다면, 아마 이미 이런 상황을 겪었을 것입니다: 누군가가 기존 기술을 사용하거나 특정 방식으로 테스트 스위트 (test suite)를 실행하기 위해 기술을 구축합니다. 2주 후, 다른 누군가가 동일한 작업을 위해 자신만의 방식으로 이를 수행합니다 — 단계도 다르고, 컨벤션 (conventions)도 다르고, 결과도 다릅니다 — 왜냐하면 첫 번째 기술이 존재한다는 사실을 전혀 몰랐기 때문입니다. 이제 에이전트는 당신의 컴퓨터에서는 한 가지 방식으로, 다른 사람의 컴퓨터에서는 또 다른 방식으로

그리고 여기서 놓치기 쉬운 핵심적인 이점이 있습니다. 모든 사람이 동일한 기술 (skill)을 사용하게 되면, 카탈로그는 피드백 루프 (feedback loop)가 됩니다. 누군가 불안정한 단계, 누락된 케이스, 에이전트가 계속 잘못 읽는 프롬프트와 같은 문제점 (rough edge)을 발견하면, 그들은 단 하나의 정전 (canonical) 기술에서 이를 수정합니다. 그러면 그 수정 사항이 팀 전체에 즉시 적용됩니다. 문제 해결 (troubleshooting)은 각자가 개인적으로 조용히 반복하는 작업이 아니라 _축적_되는 과정이 됩니다. 즉, 공유된 기술은 누군가 사용할 때마다 점점 더 정교해집니다. 반면, 12개의 개인용 복사본은 그저 12가지의 서로 다른 방식으로 고장 난 채로 남아 있을 뿐입니다.

이는 멋진 아이디어입니다. 하지만 기술을 추가하는 것이 번거로운 일이 되는 순간, 이 아이디어는 부패하기 시작합니다.

함정: 수동으로 카탈로그를 만드는 것은 바로 그것을 망치는 마찰 (friction)입니다

신뢰성을 만드는 부분: 잘못된 동작을 거부하는 것

단순한 버전이라면 카탈로그를 기꺼이 오염시킬 것입니다. 진짜 가치는 게이트(gates)에 있습니다. 즉, 카탈로그를 만드는 대신 동작을 중단하는 경우들입니다.

• 프론트매터 (frontmatter) 누락. 만약 name이나 description이 없다면, 해당 기술을 misc로 복사하지만 README나 마스터 테이블(master table)은 건드리지 않습니다. 그런 다음 어떤 필드가 누락되었는지 정확히 알려줍니다. 결함이 있는 기술이 신뢰할 수 있는 정보원 (source of truth)을 조용히 오염시키는 일은 결코 발생하지 않습니다.
• 이름 불일치 (Name divergence). 폴더 이름은 foo인데 프론트매터에 name: bar라고 되어 있다면, 이는 위험 신호(red flag)입니다. 시스템은 원래 폴더 이름 아래로 복사하되, 카탈로그 등록은 거부하고 불일치 사항을 보고합니다.

이러한 "거부 및 보고 (refuse and report)" 동작이야말로 편리한 스크립트를 팀이 카탈로그에 실행하도록 신뢰할 수 있는 무언가로 탈바꿈시키는 핵심입니다.

직접 구축하는 방법

제 리포지토리(repo)가 필요한 것이 아니라, 패턴이 필요한 것입니다. 이를 복제하려면 다음과 같이 하세요:

1. 카탈로그 리포지토리 만들기. skills/<category>/ 디렉토리, 마스터 테이블이 포함된 루트 README, 카테고리당 하나의 README를 만듭니다. 카테고리는 적고 명확하게 유지하세요.
2. 신뢰할 수 있는 정보원 (source of truth) 결정하기. 저는 루트 테이블을 사용합니다. 규칙은 "테이블에 없으면 존재하지 않는 것이다"입니다. 여러분만의 기준을 정하고 이를 명시적으로 만드세요.
3. 메타 기술 (meta-skill) 작성하기. 위의 네 단계를 SKILL.md로 인코딩하세요. 눈에 보이지 않는 핵심 작업은 장부 관리 규칙입니다: 알파벳순 삽입, 원본 리포지토리의 git 원격(remote) 및 커밋(commit)으로부터의 퍼머링크(permalink) 해결, 그리고 일관된 테이블 재생성입니다.
4. 게이트 (gates) 추가하기. 여러분에게 "유효하지 않음"이 무엇을 의미하는지(필드 누락, 이름 불일치, 잘못된 구조 등) 결정하고, 잘못된 항목을 밀어넣는 대신 기술이 거부하고 보고하게 만드세요.
5. 진입 장벽을 제로로 낮추기. 이 모든 전략의 핵심은 기여 비용이 들지 않을 때만 카탈로그가 생존한다는 것입니다. 메타 기술은 바로 그 비용을 해결해 주는 도구입니다.

이것이 전부입니다. 카탈로그를 최신 상태로 유지하는 것이 이제 번거로운 일이 아니라 단 한 번의 명령어가 되었기 때문에 카탈로그는 최신 상태를 유지하며, 팀은 이미 보유하고 있는 기술을 다시 구축하는 일을 멈추게 됩니다.

모든 기능이 구현된 전체 버전(게이트 케이스 포함)은 여기에서 확인할 수 있습니다: github.com/edpittol/skills. 이를 분해하여 카테고리와 규칙을 귀하의 팀에 맞게 조정하고, 에이전트가 기록을 계속 관리하도록 하세요.