구글의 테크니컬 라이터 Tom Johnson의 질문과 토론을 정리한 글입니다.
원문 전체를 번역한 것은 아니며, Gemini와의 대화(?)를 통해 정리한 내용입니다.
원문은 아래 링크에서 확인할 수 있습니다.
https://writethedocs.slack.com/archives/C1NEAD7D4/p1790699425280749
최근 AI 에이전트(Claude Code, Cursor 등)가 개발 생태계에 깊숙이 들어오면서, 제품 개발사와 테크니컬 라이터들 사이에서 "제품 스킬(Product Skill)" 혹은 "Agent Skill"을 정의하고 제공하는 방식에 대한 논의가 뜨겁습니다.
Tom Johnson이 던진 화두와 이에 대한 현업 전문가들의 가치 있는 통찰을 정리해 공유합니다.
질문의 시작: 스킬은 단순 문서 요약인가, 별개의 지침인가?
Tom Johnson은 AI 에이전트용 '제품 스킬'을 제작하는 현재 트렌드에 대해 다음과 같은 의문을 제기했습니다.
다른 회사들에서 만드는 '제품 스킬(Product Skill)'은 정확히 어떤 역할을 하나요? 단순히 기존 공식 문서(Documentation)의 핵심을 요약하고 링크를 모아둔 '빠른 참조 가이드(Quick Reference Guide)'인가요?
만약 후자처럼 모호성 해소, 전략적 지침, 제품 간 Cross-workflow 같은 고차원의 정보를 제공하는 것이라면, 왜 그런 중요한 정보가 처음부터 공식 문서에 들어있지 않고 스킬이라는 별도의 형태로 존재하는가?라는 의문이 듭니다.
즉, 기존 문서가 완벽하다면 스킬 파일은 중복(Redundant)일 뿐이고, 스킬 파일에만 특수한 지식이 들어간다면 기존 문서 시스템의 한계를 의미하는 것이 아니냐는 지적이었습니다.
반론: 문서와 스킬은 목적과 수신자(Audience)가 다르다
이 질문에 대해 현업에서 AI 에이전트용 스킬과 MCP(Model Context Protocol)를 직접 구축하고 테스트해 본 엔지니어들과 테크니컬 라이터들이 다양한 의견을 내놓았습니다.
스킬은 사람이 아닌 'AI(LLM) 맞춤형 지침'이다 (BrianD)
- 공식 문서(Human-facing):
사람이 읽기 위한 문서로, 기초 개념 설명("Docker란 무엇인가?")이나 문맥 이해를 위한 친절한 설명이 포함됩니다.
- 제품 스킬(Agent-facing):
LLM이 이미 학습으로 잘 알고 있는 일반적인 개념은 과감히 제거합니다.
LLM이 자주 범하는 실수나 안티패턴(Anti-pattern)을 금지하는 지침을 명시합니다.
LLM이 자신의 사전 학습 데이터(다른 경쟁사 API나 일반 지식)와 혼동하지 않도록 해당 제품만의 독자적인 차이점을 강조합니다.
AI의 '실행 순서(Order of Operations)'를 통제한다 (CT)
- 스킬의 목적은 문서 내용을 복붙하는 것이 아닙니다.
- 에이전트가 작업을 수행할 때 절차를 이탈하거나 순서를 뒤죽박죽으로 실행하는 것을 방지하기 위해 작업의 순서와 주의사항(Caveats)을 번들 형태로 제공합니다.
- 실제로 스킬 적용 여부에 따라 AI가 개발 작업을 성공적으로 완수하느냐, 아니면 API 호출을 실패하며 토큰 크레딧만 낭비하느냐의 차이가 발생합니다.
외부 접근이 불가능한 '샌드박스 환경'을 위한 필수 지침 (ravindk-minio)
- 모든 AI 에이전트가 외부 웹 문서(URL)에 직접 접근할 권한이나 curl 능력을 갖추고 있지는 않습니다.
- 격리된 샌드박스 환경에서 작동하는 에이전트에게 최소한의 올바른 제품 작동 방식과 명령어 사용법을 컨텍스트로 주입(Inject)해 주기 위해 스킬이 유용하게 사용됩니다.
주의할 점: 문서의 단순 재탕(Re-hash)은 오히려 성능을 떨어뜨린다
토론자들은 단순히 공식 문서를 요약해서 스킬로 넣어주는 방식에 대해서는 경고의 목소리를 냈습니다.
- krollins: 테스트 결과, 공식 문서를 단순 재탕하거나 대량의 문서 참조를 스킬로 구겨 넣는 경우, 오히려 AI 에이전트의 단독 작업 성능보다 결과가 더 나빠졌습니다. 스킬은 제품 지식을 우겨넣는 통로가 아니라, 에이전트의 워크플로우를 주도적으로 규정(Opinionated & Targeted)하는 용도로 쓰여야 합니다.
- ravindk-minio: 문서 내용을 컨텍스트에 무작정 많이 로드하면 'Lost in the Middle'(긴 컨텍스트 중앙의 정보를 AI가 놓치는 현상) 문제가 발생합니다. 문서는 벡터화(Vectorize/RAG)하여 AI가 필요할 때마다 검색하게 하고, 스킬은 '문서를 어떻게 검색하고 읽어야 하는가'를 안내하는 역할을 맡기는 것이 좋습니다.
핵심 요약: 테크니컬 라이터와 개발자를 위한 인사이트
| 구분 | 제품 공식 문서 (Documentation) | AI 제품 스킬 (Product Skill) |
| 주요 대상 | 사람 (개발자, 엔지니어) | AI 에이전트 (LLM) |
| 주요 목적 | 개념 이해, 전체 API 레퍼런스 제공 | 올바른 실행 순서 강제, 안티패턴 방지 |
| 작성 방식 | 친절하고 상세한 가이드 | 핵심 위주의 구체적 지침, 제약 조건 명시 |
| 주요 역할 | 전체 지식 저장소 (Single Source of Truth) | 에이전트 실행 환경의 샌드박스 가이드라인 |
결론적으로, 제품 스킬은 공식 문서를 대체하거나 요약하는 도구가 아닙니다. "사람용 문서"를 기반으로 AI가 실행 시 범하기 쉬운 착오를 보완하고 올바른 작업 순서를 지켜나가도록 조율해 주는 'AI 전용 운전면허 지침서'로 접근하는 것이 가장 효과적입니다.
