npm 패키지의 에이전트 스킬: 에이전트에 라이브러리 지식 전달하기

이 글에서는 AI 에이전트 지시사항을 위한 오픈 포맷인 Agent Skills를 npm 패키지를 통해 배포하는 방법을 다룬다. 에이전트가 새로운 라이브러리를 처음 접했을 때 소스 코드를 탐색하는 것은 효과적이긴 하지만 비효율적이다. 저자는 핵심 사항을 이미 알고 있으므로, 이를 패키지 내 skills/ 디렉터리 안의 SKILL.md 파일에 담아 인코딩할 수 있다. 이 파일에는 YAML 메타데이터와 지시사항이 포함되며, 세부 내용을 위한 선택적 references/ 디렉터리도 둘 수 있다. 예를 들어 @teqfw/db 패키지에는 이런 스킬이 포함되어 있어, 에이전트가 프라이빗 API를 사용하지 않고, 트랜잭션 경계를 존중하며, DB 재구축 시 임의로 가정하지 않도록 패키지를 올바르게 사용하는 방법을 알려준다. 스킬을 npm 패키지와 함께 번들링하면 에이전트가 버전에 맞는 지시사항을 받게 되고, 설치 및 롤백 시에도 함께 업데이트된다는 이점이 있다. 다만 node_modules 안에 스킬이 존재한다고 해서 자동으로 활성화되는 것은 아니며, 프로젝트에서 예를 들어 .agents/skills 안에 심볼릭 링크를 만드는 방식으로 명시적으로 연결해야 한다. 이는 어떤 의존성이 에이전트의 동작에 영향을 미칠 수 있는지를 통제하기 위함이다. 저자는 이 방식을 @teqfw/di, cfg, cli, log, db 및 @flancer32/teq-web 같은 TeqFW 패키지들에 구현했다. 한계점으로는 잘못된 해석 가능성, 오래된 스킬 정보, 그리고 컨텍스트 비대화 등이 있으며, 따라서 스킬은 간결하게 작성되어 코드, 타입, README를 보완하는 역할에 그쳐야 한다. 관련 작업으로는 Agent Skills 저장소의 RFC와 skills-npm 프로젝트가 있다. 저자는 이러한 패턴을 'Dependency-bound Agent Skills'라고 부른다.