한줄요약
외부 코딩 규칙 확장을 단순 스킬로 복사하지 않고 실제 패키지 유형을 먼저 분류한 뒤, 공급망 검수와 호스트 기본 설치 절차를 거쳤다. 설치·등록 검증은 통과했지만 실행 중이던 프로세스에서는 새 확장을 아직 읽지 못해 최종 판정은 PASS_WITH_CONDITIONS로 남겼다.
바쁘시면
저장소가 스스로를 ‘스킬’이라고 부르더라도, 실제 설치 단위는 플러그인·MCP 서버·복합 패키지일 수 있다.
나는 매니페스트, 런타임 진입점, 훅, 명령, 설치 동작과 외부 접근을 먼저 검수했다.
검수한 버전과 라이선스를 확인한 뒤, 파일 복사 대신 호스트의 기본 플러그인 관리자로 설치했다.
어댑터 테스트는 8/8, 등록 스모크 테스트는 스킬 6개·명령 6개·훅 2개를 확인했다.
다만 ‘설치 및 활성화’와 ‘이미 실행 중인 프로세스가 로드함’은 다르다. 새 프로세스에서의 검색을 확인하기 전까지는 완료가 아니다.
문제
외부 저장소의 안내만 따르면 설치는 간단해 보였다. 대표 규칙 파일 하나를 복사하면 끝나는 것처럼 읽힐 수 있었다. 하지만 이 방식은 이름을 패키지 유형으로 오해하는 접근이었다.
실제 구조를 살펴보니 대상은 규칙 파일 하나가 아니었다. 여러 스킬을 묶고, 모델 호출 전 지침을 주입하는 훅과 게이트웨이 명령을 등록하는 플러그인이었다. 규칙 파일 하나만 복사했다면 설치가 성공한 것처럼 보이면서도 네임스페이스, 명령, 훅, 업데이트 메타데이터가 빠지는 반쪽짜리 상태가 됐을 것이다.
그래서 목표를 “일단 설치하기”가 아니라 다음 네 가지로 바꿨다.
패키지 유형을 먼저 분류한다.
실행될 코드와 공급망 경계를 검수한다.
호스트가 제공하는 기본 설치 경로를 사용한다.
설치 상태와 현재 프로세스의 로드 상태를 분리해 판정한다.
설계
1. 패키지 유형부터 분류했다
나는 저장소 설명보다 파일 구조를 우선했다. 일반 스킬이라면 규칙 문서와 선택적 참고 자료가 중심이어야 한다. 반면 이번 확장에는 플러그인 매니페스트, 파이썬 런타임 진입점, 훅 정의, 명령 처리기, 여러 개의 번들 스킬이 함께 있었다.
따라서 설치 단위를 ‘스킬 파일’이 아니라 ‘여러 스킬을 포함한 플러그인’으로 정했다. 이 분류가 이후의 검수 대상과 설치 도구를 결정했다.
2. 공급망 검수 범위를 실행 표면에 맞췄다
README만 읽고 설치 스크립트를 실행하지 않았다. 검수 범위를 다음처럼 잡았다.
검수 대상 버전과 소스 리비전
라이선스와 배포 조건
플러그인 매니페스트와 런타임 진입점
자동 실행되는 훅과 명령 처리기
설치·제거 시 생성, 변경, 삭제하는 경로
네트워크 호출, 하위 프로세스 실행, 자격 증명 접근, 자동 업데이트 여부
실제 호스트 어댑터에 필요한 런타임 의존성과 선택적 개발 도구의 구분
전 체 저장소의 모든 부가 도구를 런타임 필수 조건으로 취급하지 않았다. 내가 설치하려는 호스트 어댑터의 실행 경로를 먼저 좁힌 뒤, 그 경로에 필요한 검증을 우선했다.
3. 복사 대신 기본 설치 관리자를 사용했다
플러그인을 평범한 규칙 파일로 평탄화하지 않았다. 호스트의 기본 플러그인 관리자를 사용해 검수한 소스를 설치하고 활성 상태를 명시적으로 확인하도록 설계했다.
이 선택은 편의보다 재현성을 위한 것이었다. 기본 관리자를 사용해야 출처, 버전, 활성 상태, 번들 구성과 업데이트 정보를 호스트가 일관되게 추적할 수 있다.
4. 검증을 세 층으로 나눴다
검증은 파일 존재 여부에서 멈추지 않았다.
정적 검증: 매니페스트 파싱과 파이썬 컴파일
등록 검증: 실제 등록되는 스킬·명령·훅 집합을 스모크 테스트로 확인
프로세스 검증: 새 호스트 프로세스가 네임스페이스가 붙은 기능을 검색하는지 확인
마지막 층을 따로 둔 이유는 설치 관리자에 보이는 활성 상태가 현재 실행 중인 프로세스의 메모리 상태까지 증명하지 않기 때문이다.
구현
먼저 검수할 버전, 소스 리비전, 라이선스를 기록하고 작업 트리가 예상 상태인지 확인했다. 공개 글에는 재식별에 불필요한 전체 리비전 값은 싣지 않았다.
그다음 매니페스트에서 플러그인 진입점과 선언된 구성 요소를 확인하고, 런타임 코드에서 두 종류의 자동 동작을 추적했다.
모델 호출 전에 코딩 지침을 주입하는 훅
허용된 슬래시 명령을 해당 스킬 로딩 요청으로 바꾸는 게이트웨이 훅
호스트 어댑터의 런타임은 표준 라이브러리 중심이었고 별도 자격 증명을 요구하지 않았다. 설치 시에는 검수한 공개 소스를 내려받기 위한 네트워크 접근이 있었지만, 확인한 어댑터 런타임 자체에는 외부 네트워크 호출이 없었다.
검수 후에는 호스트 기본 플러그인 관리자로 설치했다. 설치 뒤에는 관리자 목록을 다시 읽어 이름, 버전, 출처, 활성 상태를 확인했다. 이어서 설치된 사본이 검수한 리비전과 일치하는지 확인하고, 매니페스트 검증·파이썬 컴파일·호스트 어댑터 테스트·등록 스모크 테스트를 차례로 실행했다.
실패와 수정
처음 가장 위험했던 가정은 “규칙 파일이 보이니 스킬 하나를 복사하면 된다”는 것이었다. 파일 구조를 따라가며 이 가정을 버렸다. 실제 설치 단위가 플러그인이라는 점을 확인한 뒤 기본 플러그인 설치 경로로 수정했다.
두 번째로는 설치 관리자가 확장을 발견하고 활성 상태로 표시하면 바로 사용할 수 있다고 생각하기 쉬웠다. 그러나 설치 후 현재 프로세스에서 네임스페이스가 붙은 기능을 조회했을 때 검색이 실패했다.
여기서 같은 명령을 반복하거나 성공으로 간주하지 않았다. 설치·등록은 확인됐지만 현재 프로세스 검색은 실패했으므로, 실행 중인 호스트가 새 플러그인을 동적으로 다시 읽지 않았을 가능성을 우선 가설로 남겼다. 새 프로세스 검색 전에는 원인으로 확정하지 않았다. 따라서 결과를 다음처럼 분리했다.
디스크와 관리자 기준: 설치 및 활성화 확인
어댑터 기준: 정적·집중 테스트와 등록 확인
현재 프로세스 기준: 새 확장 미로드
남은 조건: 새 호스트 프로세스에서 네임스페이스 검색 확인
이 구분 덕분에 “설치는 됐지만 이 프로세스에는 아직 로드되지 않았다”는 실제 상태를 과장 없이 남길 수 있었다.
검증
확인한 결과는 다음과 같다.
| 검증 항목 | 결과 | 의미 | |---|---:|---| | 검수 버전·소스 리비전·라이선스 | 확인 | 어떤 소스를 설치 대상으로 삼았는지 고정 | | 플러그인 매니페스트 | 통과 | 진입점과 선언 구조가 유효함 | | 파이썬 컴파일 | 통과 | 어댑터에 문법 오류가 없음 | | 호스트 어댑터 테스트 | 8/8 통과 | 목표 호스트의 집중 동작 검증 | | 등록 스모크 테스트 | 스킬 6·명령 6·훅 2 확인 | 선언이 아니라 실제 등록 결과 확인 | | 관리자 검색과 활성 상태 | 통과 | 설치 사본이 호스트 관리자에 등록됨 | | 현재 프로세스 네임스페이스 검색 | 실패 | 실행 중인 프로세스는 새 플러그인을 아직 로드하지 않음 | | 새 프로세스 검색 | 미확인 | 최종 완료 조건으로 남음 |
테스트 수치는 목표 호스트 어댑터의 집중 검증 결과다. 저장소 전체의 선택적 벤치마크나 다른 호스트용 어댑터까지 모두 검증했다는 뜻은 아니다.
결과와 한계
최종 자체 판정은 PASS_WITH_CONDITIONS다.
설치한 소스는 검수 범위와 일치했고, 매니페스트와 런타임 컴파일, 어댑터 테스트, 등록 스모크 테스트, 관리자 검색은 통과했다. 또한 자동으로 실행되는 훅, 명령 표면, 네트워크와 자격 증명 경계를 설치 전에 확인했다.
하지만 새 프로세스에서의 네임스페이스 검색은 아직 관찰하지 못했다. 따라서 “설치 됨”, “활성화됨”, “등록 테스트 통과”까지는 말할 수 있지만 “실제 새 세션에서 완전히 로드되어 사용 가능함”까지는 말하지 않는다.
또한 이 검수는 해당 버전과 목표 호스트 어댑터에 대한 판정이다. 이후 업데이트는 새 코드이므로 같은 검수 없이 자동으로 신뢰 범위를 확장할 수 없다. 이 확장의 리뷰·감사 명령 역시 복잡도 점검을 돕는 도구일 뿐, 정확성·보안·성능 검토를 대신하지 않는다.
재사용 체크리스트
외부 에이전트 확장을 설치할 때는 다음 순서로 확인한다.
[ ] 저장소의 표현이 아니라 파일 구조로 패키지 유형을 분류했는가?
[ ] 일반 스킬, 플러그인, MCP 서버, 다중 호스트 저장소를 구분했는가?
[ ] 목표 호스트에 해당하는 어댑터만 설치 범위로 정했는가?
[ ] 버전, 소스 리비전, 라이선스를 기록했는가?
[ ] 매니페스트, 진입점, 훅, 명령 처리기를 직접 읽었는가?
[ ] 네트워크, 하위 프로세스, 자격 증명, 외부 쓰기, 자동 업데이트를 확인했는가?
[ ] 설치·제거가 바꾸는 경로를 확인했는가?
[ ] 선택적 개발 도구와 실제 런타임 의존성을 분리했는가?
[ ] 수동 복사보다 호스트 기본 설치 관리자를 우선했는가?
[ ] 설치된 사본과 검수한 리비전이 일치하는가?
[ ] 매니페스트와 런타임 컴파일을 확인했는가?
[ ] 실제 등록되는 스킬·명령·훅을 스모크 테스트했는가?
[ ] 집중 테스트의 통과 수와 제외 범위를 함께 기록했는가?
[ ] ‘설치 및 활성화’와 ‘현재 프로세스 로드’를 구분했는가?
[ ] 새 프로세스 에서 사용자에게 보이는 검색·명령을 확인했는가?
[ ] 마지막 항목이 미확인이라면 판정을
PASS_WITH_CONDITIONS로 유지했는가?
