Skill Sunset으로 오래된 AI 지침을 안전하게 감사하기

Skill Sunset이란?

Skill Sunset은 축적된 AI 에이전트 지침을 감사하는 명령줄 도구입니다. AGENTS.md, CLAUDE.md, SKILL.md와 같은 파일을 검사하여 오래된 참조, 중복된 Skill, 항상 로드되는 과도하게 큰 콘텐츠, 잘못된 frontmatter 및 기타 유지 관리 문제를 식별합니다.

이 도구는 결정론적 검사와 신중한 검토 가설을 결합합니다. 오래되어 보이는 모든 지침을 사용되지 않는 것으로 간주하지 않으며, 어떤 발견 사항도 삭제를 승인하지 않습니다. 대신 정적으로 확인할 수 있는 문제와 테스트가 필요한 동작 관련 규칙을 구분합니다.

중요: TEST 판정은 “이 가설을 평가하라”는 의미입니다. 최신 AI 모델이 해당 지침을 불필요하게 만들었다는 뜻은 아닙니다.

감사는 로컬에서 읽기 전용으로 실행됩니다. 핵심 기능은 AI API를 호출하거나, 모델 할당량을 사용하거나, 공급자 자격 증명을 읽지 않습니다.

주요 기능

• 정적 지침 검사: 로컬 참조 손상, 오래된 절대 경로, 잘못된 Skill frontmatter, 항상 로드되는 과도하게 큰 파일 및 평문 자격 증명 가능성을 찾습니다.
• 신중한 중복 처리: 이름이 같은 Skill을 감지하고, 복구 가능한 폐기를 권장하기 전에 전체 번들을 확인합니다.
• 동작 가설: 모델 세대별 보정 규칙을 사용되지 않는 것으로 선언하지 않고 TEST로 표시합니다.
• 다양한 보고서 형식: 이중 언어 HTML, Markdown, JSON, Codex 및 Claude 인계 프롬프트, 평가 계획, 실험 템플릿 및 롤백 매니페스트를 생성합니다.
• 보호된 지침 범주: 도메인 지식, 안전 규칙, 권한 부여 게이트 및 프로젝트 불변 조건을 자동 폐기 대상에서 제외합니다.
• CI 지원: --fail-on을 통해 심각도 기반 종료 코드를 반환할 수 있습니다.
• 개인정보를 고려한 보고서: 사용자 홈 디렉터리 아래의 경로는 $HOME/...로 가리고, 그 밖의 절대 대상은 $ABSOLUTE/<name>으로 표시합니다.

요구 사항 및 지원 환경

Skill Sunset은 Node.js 20, 22 및 24를 지원합니다. Ubuntu, macOS 및 Windows의 GitHub Actions를 통해 검증됩니다. 현재 프로젝트의 CI 매트릭스에는 포함되어 있지 않지만, 다른 Linux 배포판도 Node.js 20 이상에서 작동할 것으로 예상됩니다.

Codex의 ~/.codex 및 Claude Code의 ~/.claude에 대한 사전 설정 검사 대상이 제공됩니다. 명시적으로 지정한 제한된 디렉터리도 감사할 수 있습니다.

설치 및 설정

전역 설치는 필요하지 않습니다. npx를 사용하여 최신 공개 패키지를 직접 실행하세요.

npx skill-sunset@latest audit --codex --open

이 명령은 Codex 설정을 감사하고 생성된 HTML 보고서를 엽니다. 대신 Claude Code를 감사하려면 다음을 실행하세요.

npx skill-sunset@latest audit --claude --open

프로젝트 또는 다른 제한된 디렉터리를 검사하려면 해당 경로를 audit에 전달하세요.

npx skill-sunset@latest audit /path/to/setup

기본 기본 보고서 언어는 --lang auto입니다. --lang en 또는 --lang zh-CN을 사용하여 언어를 명시적으로 선택하세요. 각 보고서 번들에는 이식 가능한 영어 및 중국어 간체 HTML 페이지가 여전히 포함됩니다.

첫 감사 실행

현재 디렉터리 감사

지침 파일을 변경하기 전에 복구 가능한 사본을 만드세요. 예를 들어 AGENTS.md를 백업하고 전용 디렉터리에 보고서를 작성합니다.

cp AGENTS.md AGENTS.md.skill-sunset.bak
npx skill-sunset@latest audit . --out .skill-sunset --open

감사는 읽기 전용입니다. 잠재적인 유지 관리 작업을 보고하지만 검사한 파일을 수정하거나 삭제하지 않습니다.

보고서 번들 이해하기

기본적으로 생성된 번들에는 다음 아티팩트가 포함될 수 있습니다.

.skill-sunset/
├── index.html
├── index.en.html
├── index.zh-CN.html
├── audit-report.md
├── audit.json
├── execution-prompt-codex.md
├── execution-prompt-claude.md
├── eval-plan.md
├── experiment-template.json
└── rollback-manifest.json

대화형 사람 검토에는 HTML 파일을, 이식 가능한 텍스트 보고서에는 audit-report.md를, 자동화에는 audit.json을 사용하세요. 실행 프롬프트는 Codex 또는 Claude Code로 인계할 수 있도록 지원하며, 평가 계획과 실험 템플릿은 동작 가설을 검증하는 데 도움이 됩니다.

생성된 rollback-manifest.json은 권한이 부여된 실행 에이전트가 실제 변경 사항과 해시를 기록할 때까지 비어 있습니다.

판정 해석

• MERGE: 정확히 중복되거나 충돌하는 동일 이름의 Skill을 통합 대상으로 검토해야 합니다.
• UPDATE: 경로, 참조, 도구 가정 또는 버전에 종속된 지침을 수정해야 할 수 있습니다.
• DEMOTE: 유용한 세부 정보가 지나치게 광범위하게 로드되고 있으므로 점진적 공개 방식으로 옮길 수 있습니다.
• RETIRE: 하나의 검사 루트 안에 이름이 같고 바이트 단위로 동일하며 완전한 일반 Skill 번들이 존재합니다. 복구 가능한 보관만 권장됩니다.
• TEST: 사용 중단 가능성에 대한 주장은 정리하기 전에 이전 버전과 새 버전의 동작 평가가 필요합니다.

이러한 판정은 검토 범주이며 자동 변경 승인이 아닙니다. 지침을 편집하기 전에 각 문제를 저장소, 현재 도구 및 대표 작업을 기준으로 확인하세요.

예시: 발견 사항에서 롤백까지

AGENTS.md 파일에 무조건적인 도구 요구 사항과 누락된 배포 가이드 링크가 포함되어 있다고 가정해 보겠습니다.

모든 작업에 항상 Context7을 사용하세요.
[배포 런북](docs/deploy.md)

docs/deploy.md가 존재하지 않으면 Skill Sunset에서 세 가지 별도 문제가 보고될 수 있습니다.

• UPDATE / broken-reference: 런북 대상을 확인할 수 없기 때문입니다.
• UPDATE / context7-assumption: 현재 도구 사용 가능 여부를 확인해야 하기 때문입니다.
• TEST / unconditional-tooling: “모든 작업에”라는 표현에는 대표적인 동작 평가가 필요하기 때문입니다.

확인된 변경 사항만 적용

먼저 실제 배포 런북을 찾고 현재 도구 목록을 확인하세요. 확인할 수 있는 오래된 참조만 수정하세요. 무조건적인 도구 사용 규칙은 정적 보고서만으로 삭제하지 말고 별도의 실험 후보로 다루세요.

편집한 후 감사를 다시 실행하고 프로젝트 자체 테스트를 실행하세요.

npx skill-sunset@latest audit . --out .skill-sunset --format json
npm test

TEST 항목 검증

TEST 항목의 경우 생성된 .skill-sunset/experiment-template.json을 완성하세요. 명령을 실행하지 않고 매니페스트를 검증하려면 다음을 실행합니다.

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .

검증만으로는 어떤 명령도 실행되지 않습니다. 실행하려면 별도의 --run 플래그가 필요합니다.

npx skill-sunset@latest test .skill-sunset/experiment-template.json --root . --run

실험이 통과했다는 것은 해당 매니페스트에 인코딩된 승인 기준만 충족한다는 뜻입니다. 해당 지침이 보편적으로 불필요하다는 것을 입증하지는 않습니다.

회귀 롤백

참조, 프로젝트 테스트 또는 작업 동작에 회귀가 발생하면 저장된 파일을 복원하고 다시 감사를 실행하세요.

cp AGENTS.md.skill-sunset.bak AGENTS.md
npx skill-sunset@latest audit . --out .skill-sunset

CI에서 Skill Sunset 사용

자동화를 위해 JSON 출력을 요청하고 심각도 임계값을 설정하세요.

npx skill-sunset@latest audit /path/to/setup --format json --fail-on high

이 형식은 기계 판독 가능한 출력과 높은 심각도 항목에 대한 실패 조건이 필요한 CI 파이프라인에 적합합니다. 종료 상태를 지침 변경 또는 삭제의 승인으로 간주하지 말고 JSON 아티팩트를 검토하세요.

고급 안전 및 워크플로 팁

검색 루트 범위 제한

감사하려는 지침 설정이 포함된 가장 작은 디렉터리를 전달하세요. 중복 분석과 폐기 권고는 하나의 검색 루트 안에서 평가되므로, 명확한 경계를 설정하면 결과를 해석하기 쉬워집니다.

정적 수정과 동작 변경 분리

깨진 링크와 확인된 오래된 경로는 대개 직접 조사할 수 있습니다. 모델 동작 또는 무조건적인 도구 사용에 관한 규칙은 명시적인 승인 기준, 대표 작업 및 롤백 계획을 갖춘 별도의 후보로 유지해야 합니다.

실험 실행을 권한 있는 작업으로 취급

실험 매니페스트는 --run이 지정되지 않은 한 검증 전용입니다. 명령은 셸 없이 실행되며 기본적으로 최소한의 비밀 정보 제외 환경 허용 목록을 전달받습니다.

전체 환경 상속에는 --run과 함께 --inherit-env가 필요합니다. 상속된 변수에는 제공업체 자격 증명이 포함될 수 있으므로 신뢰할 수 있는 명령에만 이 옵션을 사용하세요. 실험 매니페스트에 자격 증명을 절대 입력하지 마세요.

저장되는 실험 데이터 이해

드라이런과 결과 파일에는 실행 파일 이름, 인수 개수, 명령 해시, 출력 크기 및 출력 해시가 보존됩니다. 명령 인수나 출력 본문은 보존되지 않습니다. 노출을 줄이는 데 도움이 되지만 실험 정의와 명령은 여전히 주의 깊게 검토해야 합니다.

비밀 정보 검색을 증거로 간주하지 않기

Skill Sunset은 평문 자격 증명으로 의심되는 항목을 표시할 수 있으며, 이 프로젝트는 게시 보호 장치로 Gitleaks를 사용합니다. 그러나 README에는 이것이 모든 자격 증명 형식을 인식할 수 있다는 증거는 아니라고 명시되어 있습니다.

로컬 개발

저장소 자체를 작업하려면 테스트를 실행하고, 패키지 내용을 검사하고, 포함된 픽스처에서 데모 보고서를 생성하세요.

npm test
npm pack --dry-run
node ./bin/skill-sunset.js audit ./test/fixtures/sample-setup --out ./demo-report --open

프로젝트의 GitHub Actions 워크플로는 지원되는 운영 체제 및 Node.js 매트릭스 전반에서 Gitleaks와 테스트를 실행합니다. 추가 프로젝트 정보는 저장소의 변경 로그, 기여 가이드 및 보안 정책에서 확인할 수 있습니다.

현재 범위

버전 0.2.0은 정적 검사, 보수적인 중복 폐기, 현지화된 보고서, 경로 비식별화, 게이트가 적용된 명령 실험 하네스, CI 심각도 종료 코드 및 적대적 출력 테스트를 제공합니다. 현재 제공업체 기능 스냅샷, 세션 사용량 어댑터 및 작업 품질 어댑터는 기존 기능이 아닌 향후 증거 계층으로 설명되어 있습니다.

결론

Skill Sunset은 오래된 규칙이 자동으로 폐기된다고 가정하지 않고 AI 지침 파일을 유지 관리할 수 있는 신중한 워크플로를 제공합니다. 읽기 전용 감사로 시작하고, 결정론적 문제와 동작 가설을 구분하며, 프로젝트 테스트와 통제된 실험으로 변경 사항을 검증하고, 전체 과정에서 복구 가능한 롤백 경로를 유지하세요.