Claude 코드 플러그인이 검증을 통과했다고 해서 아무것도 증명되지 않는다.

claude plugin validate를 --strict 없이 실행해도 결함이 있는 스킬에 대해서는 0으로 종료됩니다. 저는 직접 측정했습니다. 녹색의 유효성 검사(validate)가 플러그인이 작동한다는 증거가 아니며, 플러그인이 안전하다는 증거도 절대 아닙니다.

바로 이 문장이 frontmatter-guard v0.2가 존재하는 이유입니다.

v0.1이 이미 수행했던 기능

v0.1은 스킬/플러그인 프론트매터(frontmatter)에 대한 의미론적 린터(semantic linter)였습니다. 공식 검증기는 구조("이 플러그인이 로드될 수 있는가?")만 확인하며, 사용자가 작성한 모든 키가 실제로 무언가를 하는지 여부는 절대 묻지 않습니다. 저는 이 사실을 당황스러운 방식으로 배웠습니다. 저는 명령어 프론트매터에 effort: high를 포함하여 배포했고, claude plugin validate는 이를 조용히 통과시켰지만, effort가 Claude Code가 완전히 무시하는 Codex 개념이라는 것이 밝혀졌습니다. 제 설정은 조용히 세션 기본값으로 되돌아갔고 아무것도 알려주지 않았습니다.

frontmatter-guard v0.1은 이러한 종류의 실수를 잡아냅니다: "혹시 다음을 의미하셨나요…?"와 같은 제안이 나오는 알 수 없는 키, 절대 실행되지 않을 오타가 난 훅 이벤트(hook events), 누락된 필수 필드, 잘못된 버전, 잘못된 유형 등입니다.

두 번째 사각지대: 매니페스트 (manifest)

하지만 프론트매터는 단지 한 가지 차원에 불과합니다. 공식 검증기를 조사한 결과, 더 위험하고 두 번째 간극이 있다는 것을 발견했습니다. 바로 매니페스트의 주장(claims)이 현실과 일치하는지 여부를 절대 확인하지 않는다는 점입니다. 플러그인은 다음을 할 수 있습니다:

• 공식적인 이름(official-superpowers, anthropic-toolkit)을 주장하고,
• 0개의 권한만 선언하며,
• 매니페스트에서 언급되지 않은 훅 스크립트를 포함할 수 있습니다.

...그리고 공식 검증기는 여전히 이를 통과시킵니다. 공식적인 유효성 검사는 작동 보장이 아니며, 보안 보장도 절대 아닙니다.

v0.2: 매니페스트 감사 (manifest audit)

v0.2는 두 번째 계층을 추가하여 .claude-plugin/plugin.json 파일을 실제 디스크에 있는 내용과 대조하는 감사를 수행하고, 발견된 모든 항목에 대해 pass, review, 또는 fail이라는 판결과 수정 제안을 내보냅니다:

pip install frontmatter-guard
frontmatter-guard check ./my-plugin

악성처럼 보이는 테스트 환경(fixture)에서의 실제 출력:

my-plugin/.claude-plugin/plugin.json:1: error [impersonating-name] 플러그인 이름 'official-superpowers'가 권한을 빌려 쓰는 접두사 'official'를 사용합니다.
    수정 방법: 접두사를 제거하고 Anthropic이나 'official' 상태로부터 권위를 빌리지 않는 이름을 선택하세요.
my-plugin/.claude-plugin/plugin.json:1: error [undeclared-hooks] 플러그인 매니페스트(manifest)에 'hooks'가 선언되어 있지 않지만, 디스크에는 훅 스크립트가 존재합니다.
...

fail 판정은 항상 최소한 하나의 오류 수준 발견 사항을 포함하므로, 자체적으로 CI에서 실패합니다. JSON 출력 (--format json)은 자동화를 위한 판정을 담고 있습니다.

상세 정보 (Details)

• 의존성 없음(Zero dependencies), stdlib 전용 Python 3.9 이상, 51개 테스트 모두 성공.
• GitHub: https://github.com/hahahahahahahahah6/frontmatter-guard
• PyPI: https://pypi.org/project/frontmatter-guard/

1차 파티(first-party) 출처가 아닌 곳에서 Claude Code 플러그인을 설치했다면, 신뢰하기 전에 이것을 실행하세요. 공식적인 녹색 체크 표시가 그 역할을 대신해주지는 않습니다.