좋은 Codex Skill 설계: 트리거·입력·부작용·검증

트리거는 이름이 아니라 사용자 의도로 씁니다

“문서 Skill”처럼 명사만 적으면 교정, 번역, 발행 중 어느 요청에 선택돼야 하는지 알 수 없습니다. “공개 전 Markdown 문서의 끊어진 내부 링크를 읽기 전용으로 점검한다”처럼 작업, 대상과 모드를 씁니다.

용도 설명 앞부분에는 가장 중요한 용례와 경계를 둡니다. 명시 호출을 막을 필요가 있거나 자동 선택을 금지해야 한다면 `agents/openai.yaml`의 호출 정책도 검토합니다.

입력 계약은 추측 가능한 값도 명시합니다

Skill 본문에 필수 입력, 선택 입력, 기본값과 누락 시 행동을 적습니다. 값이 없어도 그럴듯하게 진행하는 것이 가장 위험합니다.

필수 입력
- 검사할 문서 루트
- 내부 링크의 기준 경로

선택 입력
- 제외 경로: 기본값 vendor/, build/
- 외부 링크 검사: 기본값 false

누락 시
- 문서 루트를 추측하지 말고 한 번 질문한다.
- 여러 후보가 있으면 후보와 차이를 보고하고 멈춘다.

부작용은 읽기·초안·실행으로 나눕니다

같은 “발행” 작업에도 원고 확인, 발행 초안 생성, 외부 CMS 저장과 공개 발행이 섞여 있습니다. Skill은 현재 단계에서 허용된 변경을 분명히 적고 다음 단계로 자동으로 넘어가지 않아야 합니다.

파일 수정, 이슈 생성, 메시지 전송, 커밋·푸시·배포, 데이터 변경은 각각 별도 부작용입니다. 외부 쓰기 전에 대상, 개수, 되돌리는 방법과 사람이 검토할 미리보기를 제시합니다.

검증은 성공 문구가 아니라 관찰 가능한 증거입니다

스크립트가 종료 코드 0을 냈다는 사실만으로 콘텐츠가 맞거나 부작용이 없다고 판단하지 않습니다. 링크 점검이라면 검사한 파일 수, 끊어진 링크 목록, 제외 경로와 오류를 보고해야 합니다. 수정 Skill이라면 변경 파일과 변경 차이, 관련 테스트를 확인합니다.

검증 명령 자체가 상태를 바꾸지 않는지도 봅니다. 운영 API 호출로 확인해야 한다면 읽기 전용 주소나 별도 샌드박스를 사용합니다.

최소 테스트 행렬을 만듭니다

다섯 사례를 같은 버전의 Skill에 실행하고 기대 행동과 실제 행동을 기록합니다. 자연스러운 문장 변형도 넣어 용도 설명이 특정 문구에만 맞지 않는지 확인합니다.

1. 정상 트리거 + 완전한 입력 → 실행 후 증거 보고
2. 이름 없는 유사 요청 → 자동 선택
3. 비트리거 요청 → 선택하지 않음
4. 필수 입력 누락 → 질문 또는 중단
5. 도구 실패·부분 결과 → 성공이라 하지 않고 실패 범위 보고

스크립트와 참조는 본문을 짧게 만들 때만 추가합니다

결정적으로 반복해야 하는 계산과 검사는 `scripts/`, 필요할 때만 읽을 긴 정책은 `references/`, 고정 출력 양식은 `assets/`에 둡니다. 지침 파일에는 언제 어느 자원을 읽거나 실행할지 남깁니다.

스크립트 입력을 문자열로 이어 붙여 셸에서 실행하거나, 원문 로그와 비밀을 결과에 그대로 싣지 않습니다. 실행 파일은 직접 검토하고 실패 종료 코드와 임시 파일 정리 방식을 시험합니다.

버전 변경은 기존 계약으로 회귀 검사합니다

용도 설명, 스크립트나 도구 의존성을 바꿀 때마다 테스트 행렬을 다시 실행합니다. UI 정보와 MCP 의존성을 `agents/openai.yaml`에 선언했다면 의존 도구가 없을 때의 안내도 확인합니다.

비트리거가 계속 선택되거나 입력 누락 상태에서 외부 쓰기를 시도하거나 검증 결과를 재현할 수 없으면 배포하지 않습니다. Skill을 더 길게 만드는 대신 범위를 둘로 나누는 편이 안전할 수 있습니다.