매번 “변경 파일을 읽고 테스트와 변경 차이를 확인해 줘”라고 다시 쓰고 있다면 긴 프롬프트를 보관하는 것보다 작업 절차를 Skill로 만드는 편이 낫습니다. 첫 Skill에는 도구나 스크립트를 많이 넣을 필요가 없습니다.
핵심 Skill은 이름과 용도 설명을 가진 지침 파일에서 시작합니다. 처음에는 지침만으로 한 가지 반복 작업을 완성하고, 직접 호출과 용도 설명 기반 자동 선택이 모두 예상대로 작동하는지 검증한 뒤에만 스크립트와 자원을 더합니다.
프롬프트가 아니라 반복 가능한 절차를 고릅니다
좋은 첫 주제는 입력과 결과가 분명하고 여러 번 반복되는 일입니다. 여기서는 변경 사항을 읽기 전용으로 점검해 테스트 누락과 위험을 보고하는 `change-check`를 만듭니다.
한 번만 쓸 요청, 사람마다 답이 달라야 하는 판단, 운영 상태를 직접 바꾸는 일은 첫 Skill로 고르지 않습니다. 먼저 사람이 절차를 안정적으로 수행할 수 있어야 합니다.
저장소 범위 Skill 디렉터리를 만듭니다
팀과 함께 쓸 Skill은 저장소의 `.agents/skills`에 둡니다. 아래 파일 하나만 추가합니다.
.agents/skills/change-check/SKILL.md
---
name: change-check
description: Review current repository changes for scope, missing tests, and risky side effects. Use for a read-only pre-commit review. Do not edit, commit, push, or deploy.
---
1. Read the repository instructions.
2. Inspect git status and the current diff.
3. Identify changed behavior and relevant tests.
4. Report scope drift, missing verification, and risky side effects.
5. Do not modify files or external state.설명은 언제 쓰고 언제 쓰지 않을지 적습니다
Codex는 처음부터 모든 Skill 본문을 읽지 않습니다. 이름과 용도 설명을 보고 작업과 맞는 Skill을 고른 뒤 선택된 지침 파일 전체를 읽습니다. 따라서 “유용한 도구”처럼 막연한 설명은 부족합니다.
핵심 작업, 대표 트리거와 금지 범위를 앞부분에 둡니다. Skill이 많으면 초기 목록의 용도 설명이 축약되거나 일부 Skill이 생략될 수 있으므로 가장 중요한 구분을 뒤에 숨기지 않습니다.
명시 호출로 본문부터 검증합니다
작은 문서 변경이 있는 연습 브랜치에서 `$change-check 현재 변경을 점검해 줘`라고 요청합니다. CLI나 IDE에서는 `$`로 Skill을 언급하거나 `/skills`에서 찾을 수 있습니다.
결과가 파일을 고치지 않고 변경 범위, 테스트와 위험을 구분해 보고하는지 확인합니다. Skill이 보이지 않으면 경로와 파일 머리말을 확인하고, 자동 감지가 되지 않은 경우 Codex를 다시 시작합니다.
$change-check 현재 변경을 점검해 줘.
파일을 수정하지 말고, 확인한 명령과 남은 검증을 구분해 보고해 줘.자동 선택과 비트리거를 함께 시험합니다
다음에는 이름을 쓰지 않고 “커밋 전에 현재 변경 차이에서 범위 이탈과 테스트 누락만 읽기 전용으로 검토해 줘”라고 요청합니다. Skill이 선택되는지 확인합니다.
반대로 “README 문장을 더 자연스럽게 고쳐 줘”처럼 편집을 요구하는 요청에는 이 Skill이 자동으로 선택되지 않아야 합니다. 잘못 선택되면 용도 설명의 사용 조건과 금지 범위를 더 구체적으로 고칩니다.
재사용이 확인된 뒤에만 확장합니다
지침만으로 반복해서 같은 결과를 내면 첫 버전은 충분합니다. 결정적인 검사 명령이 필요할 때만 `scripts/`, 긴 기준 문서는 `references/`, 결과 양식은 `assets/`에 둡니다.
외부 도구가 필요해졌다면 바로 명령을 넣지 말고 설치 여부, 입력 데이터, 실패 방식과 부작용을 설계합니다. 여러 Skill이나 외부 연결 도구와 함께 배포하려는 단계가 되면 독립 Skill과 Plugin의 차이를 다시 검토합니다.
읽고 나서 확인하기
답을 떠올린 뒤 본문의 판단 기준과 비교해 보세요.
- 첫 Skill은 지침 파일의 이름, 용도 설명과 실행 지침만으로 시작할 수 있습니다.
- 명시 호출 성공만 보지 않고 이름 없는 자동 선택과 선택되면 안 되는 요청도 시험합니다.
- 스크립트와 외부 도구는 반복성과 필요성이 확인된 뒤 추가합니다.
공식 출처
목록 검증 기준
확인일:
선정 기준: 입력과 결과가 분명하고 반복되는 읽기 전용 절차를 첫 Skill 대상으로 선택합니다.
추천 중단 기준: 자동 선택 범위가 불명확하거나 외부 상태 변경·비밀 접근이 필요한 단계가 되면 기능을 추가하지 않고 설계를 다시 검토합니다.