I built a governance layer for AI agent skills — with an AI agent as my pair programmer

개요

AI 에이전트 스킬의 거버넌스 레이어를 구축하는 작업은 AI 개발 및 배포의 신뢰성과 보안을 보장하는 데 초점을 맞추고 있으며, 특히 AGENTS.md 및 SKILL.md와 같은 개방형 표준에 대한 체계적인 평가 및 감사 기능을 제공합니다.

주요 내용

* 문제 인식 및 해결 방안:
* 다양한 출처에서 생성된 SKILL.md 파일들이 보안 취약성, 플랫폼 호환성 문제, 또는 의도하지 않은 부작용을 포함할 수 있어 신뢰하기 어렵다는 문제점을 인식했습니다.
* 이를 해결하기 위해 AGENTS.md 및 SKILL.md 표준을 기반으로 하는 거버넌스 레이어를 구축하여 스킬의 품질, 보안, 이식성을 평가하고 감사하는 시스템을 개발했습니다.
* skill-governance-toolkit의 기능:
* 6가지 메타 스킬: skill-find (스킬 검색), skill-evaluate (스킬 품질 평가), skill-compare (스킬 비교), library-audit (라이브러리 감사), skill-build-portable (이식 가능한 스킬 구축), integration-init (통합 도구 초기화) 기능을 제공합니다.
* 보안 서브-에이전트: code-reviewer.md는 TypeScript 기반의 서브-에이전트로 5가지 검토 범주를 가집니다.
* 결정론적 감사 엔진: agent_audit.py는 CLI, MCP (Model Context Protocol), 샌드박스 Docker 이미지 세 가지 모드로 실행 가능하며, 동일한 규칙으로 감사합니다.
* 이중 표면 아키텍처:
* Surface A (결정론적 게이트): 정규 표현식 및 구조적 규칙을 사용하여 CI에서 실행되며, 오탐(false positive)을 엄격히 제어합니다.
* Surface B (LLM 평가 스킬): skill-evaluate 등에서 사용되며, 의미론적 판단이 필요한 부분을 LLM이 평가합니다.
* 구체적인 검사 항목:
* 결정론적 게이트: 양방향 텍스트 오버라이드, 숨겨진 문자, 유사 문자 오타, 위험한 인라인 쉘 명령어, 인라인 비밀 정보, 안전하지 않은 스크립트/자산 참조, 실행 도우미 스크립트 문제, MCP 서버 설정 및 훅 명령어 안전성 등을 검사합니다. (17개 규칙 ID)
* LLM 평가 (9가지 품질 차원): 명확성(D1)부터 안전/위험 인식(D9)까지 평가하며, 특히 이식성(D6), 테스트 용이성(D7), 안전/위험 인식(D9)에 중점을 둡니다. D9는 폭발 반경, 프롬프트 주입, 민감 데이터 흐름, 권한 가정, 부분 실패 시 롤백, 멱등성 등을 평가합니다.
* 개발 과정 및 속도:
* 18일 동안 42번의 버전 릴리스를 달성하는 빠른 개발 속도를 보였습니다.
* "먼저 실패, 다음 성공(red first, then green)"이라는 엄격한 테스트 및 CI/CD 파이프라인 원칙을 준수했습니다.
* Claude Code가 코드 작성의 상당 부분을 담당했으며, 개발자는 아키텍처, 범위, "충분히 좋음"의 정의에 집중했습니다.
* 확장성 및 기여 방안:
* 새로운 규칙 추가 시, 정책 데이터 (설정 오버레이) 또는 코드 변경 (새로운 검사 함수 작성)의 두 가지 경로를 제공합니다.
* 새로운 검출기 패턴은 코드 변경 없이 설정 파일에 추가 가능하며, ReDoS 방지 기능이 적용됩니다.
* 새로운 유형의 검출은 코드 변경이 필요하며, 트리거링 및 클린 미스(clean near-miss) 예제를 포함해야 합니다.
* 기존 규칙의 개선은 skill-evaluate의 새로운 D 차원 하위 검사 또는 library-audit의 새로운 단계로 구현됩니다.
* 중단 없는 실행 (Checkpointing):
* 긴 실행 시간을 가진 작업(라이브러리 감사, 스킬 평가 등) 중에 타임아웃, 충돌, 사용자 중단이 발생해도 상태를 저장하여 이전 단계부터 재개할 수 있도록 설계되었습니다.

시사점

본 거버넌스 툴킷은 AI 에이전트 스킬의 신뢰성과 보안을 체계적으로 관리하고, 개발 생산성을 높이며, 개방형 표준의 채택을 촉진하는 데 중요한 역할을 할 것으로 기대됩니다.