AI 에이전트를 위한 스킬 만들기: 메커니즘, 모범 사례 및 플러그인 전환

rpa-skills 저장소를 개발한 저자가 AI 에이전트를 위한 스킬(skill)을 올바르게 만드는 방법을 상세히 설명한다. 스킬은 단일 마크다운 파일이 아니라, YAML 헤더(name, description)와 지시 본문을 담은 필수 SKILL.md 파일, 그리고 선택적으로 references/, scripts/, assets/ 디렉터리와 README.md 파일로 구성된 폴더다. 점진적 공개(progressive disclosure) 원칙에 따라 시스템에는 스킬의 description만 로드되고, 본문은 활성화 시점에 불러오므로 본문은 500줄 이내로 유지하고 무거운 내용은 references/로 옮겨야 한다. description 필드에는 목적과 활성화 트리거 조건을 명확히 지정하는 것이 중요하며, MUST 같은 모호한 단어를 피해 모델이 스킬을 무분별하게 활성화하지 않도록 해야 한다. 저자는 스킬과 규칙(rule)의 차이를 강조한다. alwaysApply: true로 설정된 규칙은 항상 활성 상태이며 코드 스타일이나 오류 처리에 적합하고, 스킬은 배포, 행위 주도 개발(BDD, Behavior-Driven Development), 버그 분석처럼 다단계 절차에 더 적합하다. 토큰화(tokenization) 특성상 스킬의 description과 본문은 영어로 작성해야 하는데, 키릴 문자는 평균적으로 라틴 문자보다 토큰을 두 배 더 소모하므로 컨텍스트를 절약할 수 있다. Anthropic이 제시한 실무 원칙도 소개된다: 자유도(degrees of freedom) 개념에 따라 중요한 작업에는 엄격한 가이드라인을, 창의적인 작업에는 열린 방식을 적용하고, 결정론적(deterministic) 동작은 스크립트로 옮겨야 하며, 흔히 발생하는 실수(Gotchas)를 위한 섹션을 반드시 두고, 이름은 동명사 형태(예: processing-pdfs)로 짓고, 과도한 변형은 피해 주요 해법 하나와 대안(fallback) 하나만 제시하는 것이 낫다. 스킬을 테스트할 때는 깨끗한 컨텍스트를 가진 하위 에이전트(sub-agent)를 실행해 스킬이 자동으로 활성화되는지, 어디서 오류가 발생했는지, 결과가 기대치와 일치하는지를 확인해야 한다. 서로 다른 작업과 서로 다른 모델—지시를 문자 그대로 따르는 소형 모델을 포함해—로 최소 세 번 이상 실행해볼 것을 권장한다. 마켓플레이스용 스킬은 플러그인(plugin) 형태로 패키징되는데, 이는 매니페스트 파일 plugin.json을 포함한 폴더로(Claude Code용은 .claude-plugin/에, Codex용은 .codex-plugin/에 위치), 메타데이터를 지정하며 name은 SKILL.md의 name과 일치시키고 버전도 동기화해야 한다. 플러그인에는 슬래시 명령어(slash command), 하위 에이전트, 훅(hook), 그리고 모델 컨텍스트 프로토콜(MCP, Model Context Protocol) 서버도 함께 포함될 수 있다.