현재 대부분의 팀이 에이전트 스킬 (agent skills)을 구축하는 방식에는 조용한 가정이 깔려 있습니다. 바로 SKILL.md 파일을 작성하는 사람이 개발자여야 한다는 것입니다. 표면적으로는 말이 됩니다. 스킬은 .claude/skills/ 또는 ~/.openclaw/skills/에 존재하며, YAML 프론트매터 (YAML frontmatter)를 포함하고, 리포지토리 (repo)에 커밋되기 때문입니다. 이는 개발자의 영역입니다.

또한 이것이 수많은 에이전트 스킬들이 조용히 평범한 수준에 머물러 있는 이유이기도 합니다.

당신이 인코딩하려는 워크플로우 (workflow)를 실제로 알고 있는 사람(환불이 실제로 어떻게 처리되는지 아는 지원 팀장, 송장이 나가기 전 10단계를 알고 있는 운영 매니저, 어떤 소스를 신뢰해야 하는지 아는 연구원)은 YAML을 편집하는 사람인 경우가 거의 없습니다. 그래서 개발자는 간접적인 설명을 바탕으로 그럴싸해 보이는 스킬을 작성하게 되고, 결과적으로 읽기에는 좋지만 중요한 상황에서 잘못 작동하는 스킬을 얻게 됩니다.

한 단계 높은 수준의 의도 격차 (The intent gap)

AI와 문서화 (documentation)에 관한 논쟁을 지켜봐 왔다면, 코드가 의도 (intent)를 포착할 수 없다는 주장을 보았을 것입니다. 스킬 역시 한 단계 높은 수준에서 동일한 격차를 가지고 있습니다. 스킬은 코드가 아니라 절차적 지식 (procedural knowledge)입니다. 즉, 순서, 판단, "고객이 엔터프라이즈라면 대신 이렇게 하세요"와 같은 것입니다. 그 지식은 리포지토리를 소유하고 있는 사람이 아니라, 실제로 업무를 수행하는 사람들의 머릿속에 들어 있습니다.

리포지토리 접근 권한과 YAML 작성이 기여의 대가가 될 때, 당신은 스킬을 훌륭하게 만들 수 있는 지식을 가진 사람들을 정확히 걸러내게 됩니다. 당신은 '누가 아는가'가 아니라 '누가 커밋할 수 있는가'에 최적화하게 되는 것입니다.

스킬을 설정 파일이 아닌 아티팩트로 취급하세요

해결책은 더 나은 에디터 (editor)를 도입하는 것이 아닙니다. 생산 환경의 동작을 변경하는 다른 모든 것을 다루는 방식처럼 스킬을 다루는 것입니다. 즉, 명확한 저자 (authorship), 테스트 (testing), 버전 관리 (versioning), 그리고 리뷰 (review)를 적용하는 것입니다. 별도의 도구 없이도 오늘 바로 수동으로 이 중 대부분을 시작할 수 있습니다.

1. 자신을 위해서가 아니라, 트리거 (trigger)를 위한 설명을 작성하세요.
스킬은 에이전트가 실제로 그 스킬을 호출할 때만 도움이 되며, description 필드는 모델이 매칭을 수행하는 기준이 됩니다. 내부적인 라벨이 아니라 사용자가 사용할 법한 단어로 작성하세요. "환불, 차지백(chargeback), '내 돈 어디 있나요' 질문 처리"가 "환불 프로세싱 v2"보다 훨씬 낫습니다. 언제 실행되어야 하는지 구체적으로 작성하세요.

2. 배포하기 전에 실제로 실행되는지 테스트하세요.
사용자가 실제로 보낼 법한 실제 프롬프트(prompt) 3~4개를 붙여넣고, 에이전트가 해당 스킬을 선택하는지 확인하세요. "에이전트가 내 스킬을 무시했다"는 문제의 대부분은 2분 안에 잡아낼 수 있는 트리거 (trigger) 문제입니다. 수정한 후에도 누구나 다시 실행할 수 있도록 해당 테스트 프롬프트들을 스킬 옆에 보관하세요.

3. 코드처럼 버전을 관리하세요. 왜냐하면 그것은 코드이기 때문입니다.
스킬은 동작을 변화시키므로, 잘못된 편집은 프로덕션 버그 (production bug)가 됩니다. 스킬을 git에 보관하고, 동작이 왜 변했는지 설명하는 커밋 메시지 (commit message)를 작성하며, 롤백 (roll back)이 가능한지 확인하세요. 만약 "지난주에 이 스킬에서 무엇이 변했는지, 그리고 누가 승인했는지"에 답할 수 없다면, 당신은 단 한 번의 부주의한 편집으로 에이전트가 모든 사용자에게 동시에 자신 있게 잘못된 행동을 하게 만드는 상황에 직면할 수 있습니다.

4. 작성 (authoring)과 배포 (rollout) 사이에 리뷰 (review) 단계를 두세요.
이것은 사람들이 가장 많이 건너뛰는 단계입니다. 게시된 스킬은 모든 에이전트와 모든 사용자에게 동시에 도달하므로, 코드 변경과 마찬가지로 "머지 (merge) 전 다른 사람이 확인한다"는 기준을 적용해야 합니다. 거창할 필요는 없습니다. 리뷰어 한 명, 승인 한 번이면 충분하며, 그 후에 배포하면 됩니다.

실제로 품질을 높이는 부분

대부분의 팀이 놓치는 전환점은 바로 이것입니다: 작성 (authoring)과 배관 (plumbing)을 분리하는 것입니다. 지식을 가진 사람이 실질적인 내용을 작성하게 하고, 개발자가 배관(프론트매터 (frontmatter), 허용된 도구, 동기화 배선 등)을 담당하게 하세요. 전문가는 잘못된 단계를 수정하기 위해 git을 배울 필요가 없어야 하며, 개발자는 지원 스킬을 배포하기 위해 지원 전문가가 될 필요가 없어야 합니다.

목표는 간단합니다: 워크플로우(workflow)를 아는 사람이 안전하게 스킬을 변경할 수 있어야 하며, 누군가가 승인하기 전까지는 그 어떤 것도 모든 에이전트에게 전달되어서는 안 됩니다.

'전문가에 의한 작성(authorship by the expert)과 배포 전 검토(review before rollout)'라는 이 하나의 원칙은 그 어떤 양의 프롬프트 튜닝 (prompt-tuning)보다 스킬의 품질 향상에 더 큰 도움이 됩니다.

제가 이 일을 시작한 이유

솔직히 말씀드리겠습니다. 제가 Contexory를 만드는 이유는 저 자신이 정확히 이 벽에 계속 부딪혔기 때문입니다. 이 서비스는 위에서 언급한 네 가지 사항(YAML 처리가 자동화된 협업 작성, 트리거 테스트, 버전 히스토리, 그리고 검토/승인 단계)을 자동화한 다음, 승인된 스킬을 OpenClaw 및 Claude Code와 동기화합니다. 하지만 이것이 이 글의 핵심은 아닙니다. git, 몇 가지 테스트 프롬프트, 그리고 스킬이 배포되기 전에 반드시 검토를 거쳐야 한다는 규칙만 있다면 대부분의 이점을 얻을 수 있습니다. 어떤 도구를 사용하든, 그것부터 먼저 실행하십시오.

만약 자동화된 버전을 확인하고 싶으시다면, 오늘 정식 출시되었으며 Product Hunt에도 올라와 있습니다. 그곳에서의 솔직한 피드백은 무엇보다 소중합니다:

• https://www.contexory.com
• https://www.producthunt.com/products/contexory

여러분의 팀은 현재 이 문제를 어떻게 처리하고 계신가요? 특히 개발자가 아닌 사람들이 난장판을 만들지 않으면서도 실제 스킬을 기여하게 만든 사례가 있는지 매우 궁금합니다.