Omnilude에 에이전트 Skill을 구현해 붙여보자.
들어가며
이전에 Skill과 Agent Workflow를 소개하는 글이 있었습니다.
그 글을 읽으며 스킬이 AI 채팅에 결합되면 꽤 유용하겠다라고 생각했습니다.
이번 글은 그 생각에서 시작한 구현 기록입니다. Skill을 클로드 코드나 코덱스 같은 도구 안에서 꺼내, Agent가 실제 작업 흐름 안에서 Skill을 불러 쓰게 만들면 어떤 변화가 생기는지 직접 붙여 보려 합니다. 잘되면 낮은 스펙의 LLM으로도 점점 더 자비스에 가까워질 수 있지 않을까요?
Skill을 한 문장으로 설명하면
가장 짧게 설명하면 skill은 에이전트에게 특정 일을 어떤 순서와 기준으로 처리해야 하는지 반복 가능하게 가르쳐두는 작업 패키지입니다.
Anthropic이 공개한 skill 가이드에서도 skill은 SKILL.md를 중심으로 필요하면 scripts, references, assets를 함께 두는 폴더로 설명됩니다. 중요한 것은 겉모습보다 원리입니다. 매번 모든 지식을 통째로 프롬프트에 밀어 넣는 대신, 에이전트가 필요한 순간에만 skill 본문과 참조 파일을 단계적으로 열어보게 만듭니다.
이 점이 생각보다 중요합니다. 일반 목적 에이전트는 똑똑하지만, 반복 작업 앞에서는 쉽게 흔들립니다. 같은 저장소, 같은 작업, 같은 사람의 요청이어도 결과의 톤과 구조, 누락 포인트가 달라질 수 있습니다. skill은 그 흔들림을 줄이는 장치입니다.
여기서 제가 특히 중요하게 보는 원칙은 세 가지입니다. 첫째, 필요한 순간에만 더 깊은 문서를 여는 progressive disclosure입니다. 둘째, skill 하나가 세상을 다 해결하려 하지 않고 다른 skill과 함께 작동하는 composability입니다. 셋째, 특정 화면이나 특정 툴에만 묶이지 않게 만드는 portability입니다.
구현중인 Skill 체인
지금 제 로컬 저장소의 .codex/skills 아래에는 25개의 skill이 있습니다. 문서 생성, API 구현, 백오피스 CRUD, SSE, 스토리 파이프라인, 번역, 리뷰, 커밋처럼 반복 작업을 각자 맡고 있습니다. .agents/skills에는 같은 카탈로그를 다른 surface에서 다시 쓰기 쉽게 맞춰두었습니다.
그리고 항상 클로드 코드를 언급하다가 갑자기 코덱스가 등장한 이유도 있습니다. 최근 한국에서는 OpenAI의 Pro 요금제에 대해 카카오를 통해 거의 90% 수준의 할인 이벤트가 진행됐습니다. 좋은 기회여서 현재는 코덱스로 전환한 상태입니다.
다시 본론으로 들어가서, 위 스킬 중에서 제가 자주 쓰는 축은 꽤 명확합니다. prd-generator는 요구사항을 받아 PRD를 문서 규칙에 맞게 만들고, endpoint-implement-skill은 Entity부터 Controller까지 구현 패턴을 고정합니다. 필요하면 frontend-task-handover가 프론트엔드 작업 이관 문서로 이어지고, branch-review는 마지막에 회귀와 리스크를 다시 확인합니다.
즉, 저는 skill을 개별 기능보다 체인으로 더 자주 봅니다.
실제로 CLAUDE.md에는 작업 유형별로 어떤 skill을 우선 연결할지까지 적어두었습니다. 예를 들면 API 개발은 prd-generator -> endpoint-implement-skill -> frontend-task-handover 체인으로, 백오피스 개발은 prd-generator -> backoffice-crud-skill -> frontend-task-handover 체인으로 이어지게 해두었습니다. 이쯤 되면 skill은 단순한 보조 기능이 아니라 작업 운영 규칙에 가깝습니다.
재미있는 점은 이 글 자체도 같은 철학 위에 있다는 점입니다. 지금 쓰고 있는 blog-post-writer skill은 블로그 카테고리, reading time, tone, excerpt 길이, canonical URL, 썸네일 프롬프트, import JSON 스키마까지 한 번에 맞추도록 설계되어 있습니다. 글쓰기조차 이제는 감각만으로 하지 않고, 반복 가능한 출력 형식으로 묶는 셈입니다.
스킬과 어시스턴트
제품 안으로 들어온 skill은 더 이상 SKILL.md 하나로 설명되지 않습니다. current-weather-checker 상세 청사진을 기준으로 보면, 실제 skill은 설명문과 참조문서만이 아니라 실행 코드, 메타데이터, 네트워크 정책, 트리거 전략까지 묶여 있는 런타임 단위에 가깝습니다. 그래서 저는 이제 skill을 볼 때도 폴더 구조보다 무엇이 저장되고, 무엇이 실행되고, 무엇이 어시스턴트에 연결되는가를 같이 보게 됩니다.
스킬 구조 오버뷰
current-weather-checker 청사진을 따라가보면, skill의 실체는 생각보다 입체적입니다. 화면에서 먼저 보이는 것은 이름과 설명이지만, 실제 뒤에는 Instructions, Scripts, References, Assets, Metadata, Runtime Policy가 함께 붙어 있습니다. 이 구성이 있어야 어떤 skill은 문맥만 보강하고, 어떤 skill은 sandbox에서 직접 실행되며, 어떤 skill은 외부 네트워크까지 안전하게 통제할 수 있습니다.
요약하면 skill은 단순한 프롬프트 파일이 아니라, 설명 텍스트 + 실행 리소스 + 운영 정책이 함께 묶인 정의 객체에 가깝습니다. 특히 script skill에서는 networkPolicy와 allowedDomains 같은 실행 정책이 실제 권한을 결정하므로, body만 읽어서는 이 skill이 무엇을 할 수 있는지 끝까지 알 수 없습니다. 청사진 문서가 유용한 이유도 바로 여기 있습니다. 화면 뒤의 구조를 한 번에 복원해주기 때문입니다.
어시스턴트 연동 오버뷰
그다음 단계에서 중요한 것은 skill 자체보다도 누가 이 skill을 소유하고, 어떤 조건에서 불러오며, 선택 뒤에 어떤 경로로 실행하느냐입니다. Omnilude 쪽 구조에서는 skill이 agent에 느슨하게 매달리는 것이 아니라 assistant에 매핑되고, orchestrator가 그 매핑과 trigger 정보를 읽어 실제 실행 경로를 결정합니다. 실행형 skill은 sandbox 쪽으로 흐르고, context-only 성격의 material은 최종 응답 프롬프트 쪽으로 흘러갑니다.
격리 실행 환경
실행형 skill의 스크립트는 어시스턴트 프로세스 안에서 바로 돌지 않습니다. AssistantSkillScriptExecutor가 sandbox-bridge를 통해 별도 sandbox pod에 실행을 위임하고, 스크립트는 그 격리된 환경에서 stdin JSON을 입력으로 받아 결과를 stdout JSON으로 돌려줍니다. 이 구조 덕분에 어시스턴트 본체와 실행 코드를 분리할 수 있고, networkPolicy와 allowedDomains로 외부 접근 범위도 함께 통제할 수 있습니다.
간단히 말하면 assistant는 무엇을 실행할지를 결정하고, sandbox는 그 실행을 안전하게 처리하는 곳입니다. skill이 많아질수록 이 분리가 중요해집니다. 실행 실패를 격리할 수 있고, 네트워크 권한을 세밀하게 나눌 수 있으며, 나중에 어떤 script가 어떤 정책으로 돌았는지도 추적하기 쉬워지기 때문입니다.
이 흐름으로 보면 skill은 assistant의 부속 문서라기보다, assistant가 필요할 때 선택해서 실행하는 모듈에 가깝습니다. 그래서 attached skill이 강해질수록 중요한 것은 설명을 얼마나 길게 써두었는가보다 mapping, trigger, execution, observability를 얼마나 분명하게 설계했는가입니다. 결국 좋은 skill은 잘 쓴 문서 한 장이 아니라, 어시스턴트가 안정적으로 불러 쓰도록 구조화된 실행 표면이라고 보는 편이 더 정확합니다.
마무리
2026년 2월 18일의 workflow 글이 에이전트가 어떻게 흘러가는가를 설명했다면, 이번 글은 그 흐름을 skill이라는 구조로 어떻게 고정할 수 있는지에 대한 이야기입니다.
Skill은 마법 같은 옵션이 아닙니다. 하지만 개인과 팀의 반복 작업을 줄이고, 작업 표준과 참조 문맥, 출력 형식, 실행 경로를 하나의 단위로 묶는 데에는 꽤 강력한 도구입니다.
다음에는 이 skill과 assistant의 조합이 실제 에이전트 경험을 어떻게 끌어올리는지, 구현과 운영 관점에서 더 구체적인 사례를 가져와 보겠습니다.