기술 개발(Skills Development)의 흔한 함정과 해결 방법

저는 최근 런던에서 열린 AI Engineer Europe에서 이 강연의 버전을 진행했습니다. 이어지는 내용은 더 자세한 이야기입니다 — 우리가 수천 개의 기술(skills)을 조사했을 때 발견한 것, 무엇이 잘못되는지, 그리고 어떻게 해결할 수 있는지에 대한 내용입니다.

영화 '매트릭스(The Matrix)'의 그 장면을 기억하시나요? 네오(Neo)의 머리 뒤에 스파이크가 꽂히고, 쿵푸가 그의 뇌로 직접 업로드되자 그는 그냥... 그것을 알게 됩니다.

그것이 AI 코딩 에이전트(AI coding agent)에게 기술(skill)이란 무엇인가를 보여줍니다. 여러분이 마크다운(markdown) 파일인 SKILL.md를 작성하면, 에이전트는 작업이 일치할 때 이를 로드합니다. 갑자기 에이전트는 여러분 팀의 배포 프로세스나, 여러분의 API가 페이지네이션(pagination)을 처리하는 방식, 또는 여러분이 세미콜론(semicolons)을 절대 사용하지 않는다는 사실을 알게 됩니다.

이것은 코드가 아닙니다. 컨텍스트(context)입니다. 적절한 순간에 주입되는 절차적 지식(Procedural knowledge)입니다.

문제는 — 네오의 업로드는 완벽하게 작동했다는 점입니다. 우리의 것은요? 항상 그렇지는 않습니다.

기술(Skills)은 이제 어디에나 있습니다

우리는 기본적으로 모든 공개 GitHub를 분석하는 데 시간을 보냈습니다. 작년 11월에는 12개의 리포지토리(repos)에 SKILL.md 파일이 있었습니다. 3월에는 5,460개가 되었습니다. 이는 14주 만에 450배 성장한 수치입니다.

기술(Skills)은 3개월 만에 모든 에이전트 설정(agent config) 활동의 0%에서 27%로 급증했습니다. 이는 CLAUDE.md, AGENTS.md 또는 그 이전의 어떤 도트파일(dotfile) 형식보다 빠른 채택 속도입니다. 그리고 현재 GitHub에서 병합된 PR(merged PRs) 12개 중 1개는 에이전트 설정 파일(agent config file)을 건드립니다 — 이는 18개월 전 거의 0%였던 것에서 8.4%로 증가한 수치입니다.

이것은 더 이상 틈새 영역(niche)이 아닙니다. 이것이 사람들이 일하는 방식입니다.

Watch on YouTube

하지만 그것들이 활력을 불어넣고 있을까요?

에이전트 설정 파일의 90%는 생성된 이후 한 번도 업데이트되지 않습니다. 한 번 쓰고, 영원히 잊혀집니다.

여러분의 코드베이스는 매일 진화합니다. 의존성(Dependencies)은 변합니다. API 계약(API contracts)은 바뀝니다. 하지만 여러분이 에이전트에게 준 지침은 어떤가요? 시간 속에 얼어붙어 있습니다.

Gemini 파일의 경우 상황은 훨씬 더 심각합니다. 97%가 한 번 쓰고 버려집니다. 그리고 목적에 맞게 구축된 "제품으로서의 기술(skill-as-product)" 리포지토리들은 어떨까요? 절반 이상이 50킬로바이트(kilobytes) 미만입니다. 래퍼(Wrapper) 리포지토리들입니다. 상당수가 AI에 의해 생성되었습니다. 변화율(Churn)은 높지만, 지속력은 낮습니다.

우리는 기술(skills)의 폭발적인 증가를 목격하고 있지만, 그중 대부분은 커밋(commit)되는 순간 바로 노후화됩니다.

우리가 이를 해결하기 위해 한 일

Tessl의 DevRel 팀은 몇 달 동안 상당히 실무적인 작업을 수행했습니다. 우리는 SKILL.md 파일이 포함된 오픈 소스 프로젝트들을 찾아 나섰습니다. 그리고 그것들을 우리의 리뷰 도구(review tooling)로 검토했습니다. 개선할 수 있는 부분에서는 풀 리퀘스트(Pull Requests, PRs)를 보냈습니다. 모르는 사람들에게 말이죠. 인터넷을 통해서요.

622개의 PR. 559개의 서로 다른 리포지토리. 거의 6,000개의 기술에 손을 댔습니다.

우리는 단순히 무엇이 잘못되었는지 이론만 세우고 있었던 것이 아닙니다. 우리는 참호 속에 들어가 다른 사람들의 기술을 읽고, 수정하고, 메인테이너(maintainer)들의 반응으로부터 배우고 있었습니다.

이 글을 쓰는 시점을 기준으로, 해당 PR 중 96개가 머지(merge)되었습니다. 140개는 닫혔습니다. 나머지는 여전히 열려 있습니다. 이는 모르는 사람의 리포지토리에 보내는 콜드 PR(cold PRs)에 대한 머지율이 15%라는 것을 의미하며, 솔직히 말해 나쁜 수치는 아닙니다.

그리고 그 과정에서 우리는 기술이 정확히 어디에서 망가지는지 배웠습니다.

함정 #1: 모호한 설명 (Vague descriptions)

설명(description) 필드는 여러분의 활성화 신호(activation signal)입니다. 이는 에이전트가 여러분의 기술을 로드할지 결정하기 전에 평가하는 if-절(if-clause)과 같습니다. 설명이 일반적이라면, 에이전트는 신호를 얻지 못합니다. 에이전트는 여러분을 무시하거나, 더 나쁜 경우에는 잘못된 작업에서 활성화됩니다.

수정 전:

"코드 리뷰 및 품질 향상을 위한 유용한 기술"

수정 후:

"프로젝트 규칙에 따라 ESLint를 실행하고, 타입 안전성(type-safety) 위반을 표시하며, 수정 사항을 제안합니다. TypeScript PR을 리뷰하거나 프리 커밋(pre-commit) 체크를 실행할 때 사용하세요."

우리의 활동 결과, 머지된 PR 중 105개가 구체적으로 설명을 수정한 것이었습니다. 이는 단일 항목 중 가장 흔한 수정 사항이었습니다.

그리고 저희 연구팀은 이를 측정했습니다. 기술(Skills)이 설치되었음에도 에이전트(Agent)가 이를 사용하도록 강제되지 않을 때, 활성화율(Activation)은 41%로 떨어집니다. 절반도 되지 않는 수치입니다. 기술은 바로 그곳에 설치되어 준비되어 있지만, 에이전트는 그냥 지나쳐 버립니다.

활성화의 가장 강력한 예측 변수는 저희가 "구별성 충돌 위험 (distinctiveness conflict risk)"이라고 부르는 것입니다. 즉, 당신의 설명이 에이전트가 자신의 내장된 동작(Built-in behaviours)과 당신의 기술을 구별할 수 있을 만큼 충분히 고유한 용어를 사용하고 있는가 하는 점입니다.

"Remotion", "Calendly", "path-traversal-finder"와 같이 강력한 도메인 특화 명사(Domain-specific nouns)를 가진 기술들은 활성화가 잘 됩니다. 반면 "API", "code", "debugging"과 같은 일반적인 용어로 설명된 기술은 어떻게 될까요? 이들은 에이전트 자체의 능력과 경쟁하게 되고 결국 패배합니다.

중요한 것은 기술이 얼마나 상세한가가 아닙니다. 설명이 에이전트가 이미 할 줄 아는 일과 중복되지 않는, 구체적이고 경계가 명확한 작업(Concrete, bounded task)을 신호하고 있는지가 핵심입니다.

함정 #2: 신급 기술 (God skills)

저희는 50개의 파일이 포함된 Microsoft Foundry 기술을 발견했습니다. 무려 50개입니다. 점진적 공개 (Progressive disclosure) 방식을 사용하더라도, 어떤 에이전트도 그 모든 컨텍스트(Context)를 효과적으로 로드할 수 없습니다.

그리고 저희의 리뷰 점수는 그것이 괜찮다고 말했습니다. 평가(Evals)도 통과했습니다. 하지만 세 가지 시나리오로는 50개 파일의 표면적을 모두 커버할 수 없습니다. 그 기술에는 테스트 가능한 범위를 넘어선 내용이 들어있습니다.

이것이 바로 "신급 기술 (God Skill)" 문제입니다. 모든 것을 하려고 시도하는 기술은 설명이 너무 광범위해져서, 아예 활성화되지 않거나 잘못된 이유로 활성화됩니다. 하나의 기술에는 하나의 워크플로우 (One skill, one workflow). 이것이 규칙입니다.

올해 초 발표된 SkillsBench 논문이 이를 확인해 주었습니다. 84개의 작업 중 16개에서 기술 델타(Skill deltas)가 음수로 나타났습니다. 기술이 오히려 에이전트의 성능을 떨어뜨린 것입니다. 대개 모델이 이미 잘 처리하고 있는 작업에 대해 상충하는 가이드라인을 제공하거나 불필요한 복잡성을 도입했기 때문입니다.

함정 #3: 컨텍스트 비대화 (Context bloat)

우리는 더 간결한 기술(Skills)이 더 나은 성능을 발휘한다는 것을 알고 있습니다. 저희 사용자 중 한 명은 기술을 최적화한 후, 소스 코드를 직접 스캔할 때보다 토큰 사용량은 40% 줄어들고 완료 시간은 절반으로 단축되었다고 보고했습니다.

하지만 여기에 아이러니가 있습니다. 저희가 자체 최적화 도구(Optimiser)를 실행하면, 출력 결과가 입력값보다 평균 17% 더 길어집니다. 기계는 예시, 주의 사항, 예외 케이스(Edge cases)를 추가합니다. 철저하긴 하지만, 이러한 철저함은 컨텍스트 창(Context window)을 소모합니다.

사람이 작성한 기술에는 LLM이 이미 알고 있는 내용이 포함되는 경우가 많습니다. REST API가 무엇인지 설명할 필요는 없습니다. TypeScript 제네릭(Generics)이 무엇인지 정의할 필요도 없습니다. 에이전트는 이미 알고 있습니다. 에이전트가 모르는 것은 바로 당신만의 특정 컨벤션(Conventions)입니다.

해결책은 점진적 공개(Progressive disclosure)입니다. 핵심 지침은 본문에 두고, 상세 참조 자료는 별도의 리소스 파일에 담아 필요할 때만 로드하도록 합니다. 처음부터 모두 로드하는 것이 아닙니다.

저희를 괴롭혔던 관련 미묘한 문제도 하나 있습니다. 평가 시나리오(Eval scenarios)를 자동으로 생성할 때, 시나리오 설명이 에이전트에게 높은 점수를 받기 위해 무엇을 해야 하는지 의도치 않게 알려줄 위험이 있습니다. 저희는 이를 기준 유출(Criteria leakage)이라고 부릅니다. 작업 내용이 "구조화된 JSON 출력으로 감사 로깅(Audit logging)을 구현하세요"라고 되어 있는데, 채점 루브릭(Scoring rubric)이 구조화된 JSON 출력을 확인하는 식입니다. 이 경우 기술(Skill) 없이 작업 설명만 읽어도 기준 점수가 80%에 달하게 됩니다.

저희 연구팀은 이를 측정했습니다. 자동 생성된 시나리오의 30%에서 의미 있는 유출이 발생했습니다. 그리고 유출이 심한데 시나리오가 일반적일 경우, 기술(Skill)을 사용했을 때 오히려 기준점(Baseline)보다 점수가 더 낮게 나올 수 있습니다. 유출된 정보가 기술 없이도 에이전트에게 충분하기 때문에, 기술은 그저 노이즈만 추가할 뿐입니다.

만약 기준 점수가 의심스러울 정도로 높다면, 시나리오가 에이전트의 숙제를 대신 해주고 있는 것일지도 모릅니다.

함정 #4: 에이전트에 따라 활성화 방식이 다름

활성화(Activation)는 단순히 설명(Description)에 관한 것만이 아닙니다. 에이전트 하네스(Agent harness)에 따라 극적으로 달라집니다.

설정 (Setup)	활성화율 (Activation Rate)
Claude Code (강제)	98%
...

통제된 테스트 환경에서 단 하나의 기술 (skill)만 설치했을 때 활성화율은 62%입니다. 여기에 9개의 기술을 더 추가하면 58%로 떨어집니다. 그리고 너무 많은 기술을 설치하면 기술 간의 충돌이 발생할 수 있습니다. 즉, 에이전트가 어떤 기술을 사용해야 할지 혼란을 겪거나, 잘못된 것을 선택하거나, 혹은 아무것도 선택하지 않게 됩니다.

저희 동료 중 한 명이 MCP를 통해 보안 리뷰 기술 (security review skill)을 테스트한 후 다음과 같이 보고했습니다: "에이전트가 힌트를 얻더니 그냥 자기 할 일을 계속했습니다" — 기술 지침 (skill instructions)을 완전히 무시한 것입니다. 에이전트는 기술이 존재한다는 것은 인지했지만, 이를 따르지는 않았습니다.

솔직한 이야기

"우리는 Tessl의 지침 중 일부에 강력히 반대합니다. 저희 기술에 대한 자동화된 재작성 (automated rewrites) 제출을 중단해 주세요." — 오픈 소스 유지 관리자 (Open source maintainer)

모두가 저희의 풀 리퀘스트 (pull requests)를 좋아했던 것은 아닙니다. 그리고 그것은 당연한 일입니다.

기술 (skill)을 리뷰한다는 것은 단순히 마크다운 (markdown) 형식을 확인하는 것이 아닙니다. 만약 기술이 라이브러리 (library)를 확장하는 것이라면, 그 안에는 조직의 지식 (institutional knowledge)이 녹아 있습니다. 해당 기술은 조직이 운영되는 방식에 대한 독점적인 세부 사항을 인코딩하고 있을 수도 있습니다. 프로젝트의 테스트 스위트 (test suite), 외부 API, 전체 컨텍스트 (full context)에 대한 접근 권한 없이 리뷰를 수행한다면, 그 "개선"이 실제로 무엇인가를 개선했는지 증명할 수 없습니다.

저희는 설명 (description)이 모범 사례 (best practices)를 따르는지 말씀드릴 수 있습니다. 구조 (structure)가 올바른지도 말씀드릴 수 있습니다. 하지만 실제 워크로드 (workload)에 적용해 보지 않고서는, 해당 콘텐츠가 귀하의 특정 도메인 (domain)에 정확한지는 말씀드릴 수 없습니다.

이것이 바로 평가 (evals)가 중요한 이유입니다. 정적 리뷰 (Static review)는 필요하지만 충분하지는 않습니다. 이는 정적 분석 (static analysis)과 실제로 테스트를 실행하는 것의 차이와 같습니다.

해결책: 컨텍스트 개발 라이프사이클 (The Context Development Lifecycle)

그렇다면 이 모든 문제를 실제로 어떻게 해결할 수 있을까요? 저희의 Patrick Debois가 이를 컨텍스트 개발 라이프사이클 (Context Development Lifecycle)이라는 주제로 글을 썼습니다. 핵심 아이디어는 컨텍스트 (context)에도 공유 라이브러리에 부여하는 것과 동일한 수준의 엔지니어링 엄격함 (engineering rigour)과 규율 (discipline)이 필요하다는 것입니다.

생성 (Generate): 암묵적 지식 (implicit knowledge)을 포착하세요. 당신의 관습, 아키텍처 결정, API의 특이 사항(quirks) 등을 포함해야 합니다. 에이전트가 초안을 작성할 수는 있지만, 무엇이 사실인지는 인간이 결정합니다.

평가 (Evaluate): 테스트하세요. 리뷰를 통해 구조를 점검합니다. 태스크 평가 (task evals)를 통해 해당 기술이 있을 때와 없을 때의 실제 시나리오에서 에이전트를 실행하여 그 차이를 측정하세요. 그것만이 알 수 있는 유일한 방법입니다.

배포 (Distribute): 버전을 관리하고, 게시하고, 보안을 확보하세요. 기술 (skills)에는 소유자, 변경 이력 (changelogs), 그리고 유의적 버전 (semver)이 필요합니다. 버전 이력이 없는 기술은 공유되는 순간부터 기술 부채 (technical debt)가 됩니다.

관찰 (Observe): 프로덕션 환경에서 어떤 일이 일어나는지 지켜보세요. 활성화 (activation)를 모니터링하고, 준수 여부 (adherence)를 확인하세요. 피드백 루프 (close the loop)를 완성하세요.

승리하는 팀은 가장 좋은 모델을 가진 팀이 아닐 것입니다. 그들은 가장 좋은 컨텍스트 (context)를 가진 팀이 될 것입니다.

중요한 수치들

1,200개의 기술을 대상으로 한 대규모 평가 (eval) 연구 결과, 에이전트가 기술에 접근할 수 있을 때 정확도가 절대적으로 약 20% 향상되는 것으로 나타났습니다. 더욱 흥미로운 점은, 좋은 기술이 주어지면 더 작고 저렴한 모델들도 더 큰 모델들과 경쟁력을 유지한다는 것입니다. 이는 직접적인 비용 절감으로 이어집니다.

또한 적절하게 최적화하면 — 불필요한 부분을 제거하고, 설명을 수정하며, 점진적 공개 (progressive disclosure)를 사용하면 — 40% 적은 토큰으로 절반의 시간 만에 동일한 결과를 얻을 수 있습니다.

하지만 여기에는 주의 사항이 있습니다. 인간이 큐레이션한 기술은 성능을 16퍼센트 포인트 이상 향상시킵니다. 반면 스스로 생성한 기술은? 효과가 미미하거나 심지어 부정적이기까지 합니다. 기술의 품질이 엄청나게 중요합니다.

프로젝트 전반에 걸친 기술 준수율 (skill adherence)은 19%에서 94% 사이이며, 평균은 62%입니다. 편차가 매우 큰데, 바로 이 격차가 좋은 엔지니어링 관행이 차이를 만들어내는 지점입니다.

기술은 단순히 있으면 좋은 것이 아닙니다. 그것은 승수 (multiplier)입니다. 하지만 오직 당신이 그것을 소프트웨어처럼 다룰 때만 그렇습니다.