구조적 무결성, 깨진 참조(references), 하드코딩된 비밀 정보를 스캔하고 각 스킬을 명확한 언어로 분류하는 에이전트 비종속형 (Hermes 우선) CLI 도구. 테스트 커버리지 95%, CI 성공.

문제점

AI 에이전트의 스킬 컬렉션은 검토 없이 성장합니다: Hermes, Claude Code, OpenCode 또는 Codex에서 100~200개 이상의 항목. 사실상 에이전트의 프롬프트 표면(surface)은 명령을 로드하고 (보안 스킬의 경우) 자격 증명에 대한 지침을 처리하는 실행 가능한 코드입니다. 아무도 이를 감사하지 않습니다.

Hermes의 200개 스킬로 구성된 실제 컬렉션에서, 파일 시스템에 대한 직접적인 감사는 다음 사항들을 발견했습니다:

• 런타임에서 활성 이름 충돌을 일으키고 이중 탈출(double escaping) 버그를 유발하는 중첩된 중복 폴더 (software-development/software-development/software-development/);
• 악센트 오타로 인한 깨진 참조 (anti-evasión 대 anti-evasion);
• 저장소에 목적지 없이 존재하는 누락된 참조;
• 스크립트/references를 인용하지만 실제로 전달되지 않은 여러 스킬.

비밀 정보의 위생(hygiene)은 깨끗했습니다 (단순히 문서화 플레이스홀더만 존재). 하지만

• 중첩된 폴더 innermost만 제거하고(가장 바깥쪽의 캐노니컬한 폴더는 보존),
• 같은 스킬 내에 올바른 파일이 존재할 경우, 악센트나 오타로 인해 깨진 참조를 수정하며,
• 실제 내용은 리포지토리의 다른 스킬에 존재하는 누락된 참조를 위해 최소한의 인덱스 stub을 생성합니다(기술적인 내용 없이 크로스링크 리디렉션).

절대로 비밀 값은 편집하지 않고, 스킬의 산문(prose)을 다시 작성하지 않으며, 스킬의 유일한 사본을 삭제하지 않습니다. 파일에 대한 SECRET 발견이 있다면, 어떤 수정 작업도 이를 건드리지 않습니다.

작동 방식 (설계)

1. Discovery — SKILL.md를 재귀적으로 탐색하며, 결정론적이고 순서가 있습니다.
2. Frontmatter — pyyaml이 없을 경우 보수적인 regex 폴백을 사용한 pyyaml.safe_load. 여러 줄 블록은 실제 텍스트로 보존됩니다(순진한 regex 파서는 이를 1자 설명으로 읽었습니다—이는 이전 ad-hoc 스크립트의 정확한 거짓 양성 클래스였으며, 회귀 테스트 대상입니다).
3. 중복 파일 — name 충돌 및 run-length가 ≥ 3인 자동 중첩 X/X/.../X를 감지합니다(제거 가능한 사본은 가장 안쪽의 것만 해당).
4. 참조 — 언급을 추출하고 스킬 내에 파일 존재 여부를 확인합니다; 런타임, 컨테이너 및 플레이스홀더 경로는 무시합니다.
5. 비밀 정보 — 스킬의 모든 파일을 대상으로 regex를 수행합니다; 플레이스홀더 allowlist가 문서화 샘플을 필터링합니다.
6. 분류 — 카테고리, 목적(첫 문장, ≤120자), 발견된 내용을 기반으로 상태를 결정합니다.
7. 보고서 — 터미널 / md / json 형식입니다.
8. 수정 (Fix) — 오직 안전한 경우에만, diff-first 방식이며 비밀 정보에 안전합니다.

검증

이 프로젝트는 Pass/Fail의 인수 조건(acceptance criteria)을 가진 SDD(Spec-Driven Development) 방식으로 구축되었습니다.

• 테스트 28개 통과, 커버리지 측정값은 로컬에서 95%, CI에서는 94.51% (게이트 --cov-fail-under=85).
• ruff clean (모든 검사 통과!).
• 9개의 스킬 피처(fixture)에 대한 라이브 CLI: FRONTMATTER_ERROR, REF_ROTA, 실제 비밀 정보 (플레이스홀더 무시), NAME_DUPLICADO, NESTED_DUPLICATE를 감지합니다. --fix는 내부 폴더만 제거하고 외부 폴더는 손상되지 않은 상태로 남겨둡니다. 재감사(re-audit) 시 9개에서 8개의 스킬로 줄어들며 중첩 오류가 발생하지 않습니다.
• GitHub Actions 파이프라인: push/PR → 체크아웃 → setup-python 3.11 → 설치 → ruff → cov≥85를 만족하는 pytest → CLI 스모크 테스트 실행. 실제 실행 결과: 성공.

모든 메트릭은 요약이 아닌 pytest --cov 및 CI 로그의 원시 출력입니다.

사용해보기 (Pruébalo)

pip install -e .
# 읽기 전용 감사 모드
skill-auditor ~/.hermes/skills
...

스택 (Stack)

Python 3.11+, pyyaml (유일한 런타임 종속성), argparse, pytest, ruff. 라이선스 AGPL-3.0-or-later.

링크 (Links)

• Repo: https://github.com/amurlaniakea/skill-auditor

라이선스: AGPL-3.0-or-later © 2026 Pedro Sordo Martínez — amurlaniakea@gmail.com