한줄 요약
저는 좋은 설명문을 곧바로 설치하지 않고, 계약·테스트·근거·독립 검수를 갖춘 프로젝트 안의 후보 패키지로 먼저 키우는 절차를 스킬로 고정했습니다.
바쁘시면 이것만 보세요
스킬 제작과 설치는 다른 결정입니다. 먼저 작업 범위와 금지 행동을 적고, 후보를 운영 환경 밖에 둔 채 RED→GREEN 테스트와 고정된 검수 기준선을 만듭니다. 독립 검수의 지적을 같은 기준선에서 닫은 뒤에도 설치·활성화·게시에는 별도 승인이 필요합니다.
> 기존 완료 검증 사례와 달리, 이 글은 완료 상태기계 자체보다 후보를 운영 프로필 밖에서 만들고 검수·설치·활성화를 서로 다른 결정으로 유지하는 생애주기에만 초점을 둡니다.
이런 분께 추천합니다
반복 업무를 SKILL.md로 만들지만 품질 판단이 작성자 감각에 머무는 분
테스트 통과와 실제 채택을 자주 같은 의미로 보고하는 팀
여러 작업자가 같은 후보를 수정해 검수 기준이 흔들리는 문제를 겪는 분
제작 배경
초기에는 절차를 잘 정리해 두면 재사용 가능한 스킬이 된다고 생각했습니다. 하지만 실제로는 설명이 친절해도 입력 계약이 빠지거나, 출력 경로가 열려 있거나, 테스트용 근거를 실제 근거처럼 읽는 일이 생겼습니다. 더 큰 문제는 후보 파일이 만들어졌다는 사실이 설치 허가처럼 취급되는 것이었습니다. 그래서 저는 “좋은 문서 작성법”보다 후보가 어느 단계에 있고 무엇이 아직 승인되지 않았는지를 보존하는 생애주기가 필요하다고 판단했습니다.
어떤 스킬인가
두 스킬은 계약 → 격리된 후보 → 테스트 → 근거 인계 → 독립 검수 → 보완 → 재검수 → 설치 결정이라는 같은 뼈대를 공유합니다. 하나는 장기 운영에서 발견한 경계 사례와 검수 규칙을 폭넓게 담고, 다른 하나는 후보 패키지의 기본 계약과 품질 게이트를 간결하게 제시합니다. 핵심은 운영 프로필을 직접 고치지 않는 것, 출력 상태와 실패 의미를 먼저 정하는 것, 고정된 파일 기준선에 검수 결과를 묶는 것입니다.
어떻게 만들었나
인계 자료에서 목적, 쓰기 범위, 금지 행동, 완료 조건을 먼저 뽑았습니다. 후보를 별도 폴더에 두고 트리거·입출력·실패·승인 계약을 적은 뒤, 실행 코드는 최소 실패 테스트와 수정으로 만들었습니다. 경로 이탈, 덮어쓰기, 잘못된 타입도 고정 기준선에서 독립 검수하게 했습니다.
어떻게 사용하는가
요청을 받으면 읽기·쓰기 범위를 선언하고 후보를 프로젝트 안에 둡니다. 계약을 한 항목씩 RED→GREEN으로 확인해 파일 목록, 결과, 제한사항을 인계합니다. 지적이 나오면 이전 기록을 보존한 새 기준선으로 재검수하고, 설치와 활성화는 다시 승인받습니다.
검증과 시행착오
작성자 테스트 는 독립 검수를 대신하지 못했고, 검수 중 파일 변경은 판정 대상을 흐렸습니다. 그래서 기준선을 동결하고 변경 시 새 검수를 시작했습니다. 결과 없음, 손상된 입력, 경로 이탈이 예외가 아니라 구조화된 실패로 끝나는지도 확인했습니다.
효과 / Before-After
Before: 스킬 문서가 완성되면 바로 쓸 수 있다고 여겼고, 테스트·검수·설치 상태가 한 문장에 섞였습니다. 문제가 생기면 최신 파일에 바로 덧대어 어떤 결과가 유효한지 흐려졌습니다.
After: 후보의 단계와 승인 경계가 분리됩니다. 검수자는 같은 기준선을 재현할 수 있고, 실패 지적은 회귀 테스트와 새 기록으로 닫힙니다. 다만 이것은 품질 판단을 더 명확하게 만든 것이지 실제 업무 효과나 채택을 자동으로 증명한 것은 아닙니다.
한계와 중단 조건
작은 문구 수정에는 과합니다. 필수 입력이 없거나 다른 작업자가 수정 중이거나 기준선이 고정되지 않으면 중단합니다. 실제 사용자 평가·권리·설치는 로컬 테스트로 대신하지 않으며 독립 검수 없이는 완료라 부르지 않습니다.
다른 업무에 적용하는 법
프롬프트 템플릿, 자동화 스크립트, 평가 규칙, 데이터 변환기처럼 반복 사용되는 내부 도구에도 같은 구조를 적용할 수 있습니다. 산출물 제작과 배포를 분리하고, 변경 가능한 원본과 검수용 동결본을 나누며, 실패 의미를 먼저 정의하면 됩니다.
재사용 체크리스트
[ ] 목적·포함/제외 범위·쓰기 경계를 확인했는가
[ ] 후보가 운영 환경과 분리되어 있는가
[ ] 입력·출력·실패 상태와 승인 조건이 명시됐는가
[ ] 최소 실패 테스트와 수정 후 검증이 남아 있는가
[ ] 독립 검수가 고정된 기준선을 사용했는가
[ ] 설치·활성화·게시 승인을 각각 분리했는가
