나만의 SKILL.md 작성 — description 필드가 암묵 호출을 가른다
학습목표 / 사전지식: 이 레슨의 목표는 SKILL.md를 만들고, description 필드에 한글과 영어 키워드를 조정한 뒤, 스킬 이름을 직접 부르지 않는 암묵 호출 테스트까지 해 보는 것이다. [KO-06]
선수지식은 파일을 만들고 문장을 복사해 붙여 넣을 수 있으면 충분하도록 구성한다. [OF-07]
1. 왜 필요한가 — 개념·배경을 초보자 눈높이로 (이 기능이 뭔지, 비유, 용어풀이) [근거]
Skills에서 SKILL.md는 스킬을 설명하는 필수 파일이다. [OF-07]
description은 코덱스가 어떤 스킬을 떠올릴지 판단할 때 특히 중요한 설명 칸이다. [KO-06]
암묵 호출은 사용자가 스킬 이름을 대지 않아도 요청 내용만으로 스킬이 맞아 들어가는 상황을 말한다. [KO-06]
description은 서랍 앞에 붙이는 라벨에 가깝다. [KO-06]
라벨에 “문서”라고만 적으면 찾는 사람이 망설이지만, “제안서, 영업 문서, proposal, sales deck”처럼 실제로 찾을 말을 적어 두면 꺼낼 서랍이 또렷해진다. [KO-06]
공식 근거의 핵심 문장은 “암묵적 매칭의 정확도는 SKILL.md의 description 필드에 달려 있습니다”이다. [KO-06]
allow_implicit_invocation은 암묵 호출을 허용할지 제어하는 설정으로, agents/openai.yaml에서 allow_implicit_invocation: false처럼 다룰 수 있다. [OF-07]
2. 준비 — 코덱스 어디로 들어가 무엇을 누르나 (화면 요소 설명)
촬영 화면은 왼쪽에 파일 목록, 가운데에 SKILL.md 편집창, 오른쪽이나 아래쪽에 코덱스 입력창이 보이도록 배치한다. [OF-07, KO-06]
먼저 실습용 스킬 폴더를 만들고, 그 안에 SKILL.md 파일을 만든다. [OF-07]
파일 이름은 반드시 SKILL.md로 보이게 한다. [OF-07]
그다음 편집창에서 description 줄을 찾거나 새로 적는다. [KO-06]
마지막으로 코덱스 입력창에는 스킬 이름을 적지 않고, 평소 요청처럼 “아래 제안서 도입부를 더 설득력 있게 다듬어줘”라고 입력한다. [KO-06]
3. 따라하기 — 단계별로 아주 세세하게
1단계. 스킬 폴더와 SKILL.md 만들기
파일 목록에서 새 폴더를 만들고 이름을 proposal-polish로 둔다. [OF-07]
그 안에 SKILL.md 파일을 만든다. [OF-07]
화면에는 빈 파일이 열리고, 파일 목록에는 proposal-polish/SKILL.md가 보여야 한다. [OF-07]
2단계. 처음 description을 짧게 써 보기
처음에는 description: 제안서 문장 다듬기처럼 짧은 설명을 넣는다. [KO-06]
이 단계의 목적은 “짧은 설명도 동작할 수 있지만, 암묵 매칭 정확도는 description에 좌우된다”는 점을 눈으로 확인하는 것이다. [KO-06]
---
description: 제안서 문장 다듬기
---
한국어 제안서 초안을 더 분명하고 설득력 있는 업무 문장으로 다듬는다.
3단계. 스킬 이름 없이 테스트하기
코덱스 입력창에는 proposal-polish라는 이름을 쓰지 않는다. [KO-06]
대신 사용자가 실제로 말할 법한 요청만 넣는다. [KO-06]
아래 제안서 도입부를 더 설득력 있게 다듬어줘.
이번 프로젝트는 고객사의 업무 효율을 높이기 위해 다양한 개선 방안을 제공합니다.
결과가 기대와 다르면 지시문 전체를 고치기 전에 description을 먼저 점검한다. [KO-06]
4단계. 한글·영어 키워드 튜닝하기
description에는 멋진 소개문보다 사용자가 실제로 입력할 말을 넣는다. [KO-06]
한글 요청에는 “제안서, 영업 문서, 도입부, 설득력” 같은 말을 넣고, 영어 요청에는 “proposal, sales deck, business writing” 같은 말을 넣는다. [KO-06]
---
description: 제안서, 영업 문서, 도입부, 설득력, proposal, sales deck, business writing 초안 다듬기
---
한국어 제안서 초안을 더 분명하고 설득력 있는 업무 문장으로 다듬는다.
이제 같은 요청을 다시 넣고, 스킬 이름을 직접 부르지 않아도 의도한 스킬이 떠오르는지 확인한다. [KO-06]
5단계. 암묵 호출을 끄는 설정 확인하기
암묵 호출을 원하지 않는 스킬은 agents/openai.yaml에서 allow_implicit_invocation: false로 제어할 수 있다. [OF-07]
allow_implicit_invocation: false
스킬을 만들 때마다 자동 호출이 정말 필요한지 한 번 따져 보게 하는 안전장치인 셈이다. [OF-07]
4. 복붙 템플릿 — 그대로 쓰는 프롬프트/Skill + 각 부분이 왜 그런지 해설
아래 SKILL.md 템플릿의 핵심은 description에 실제 요청어를 넣는 것이다. [KO-06]
---
description: 제안서, 영업 문서, 도입부, 설득력, proposal, sales deck, business writing 초안 다듬기
---
한국어 제안서 초안을 더 분명하고 설득력 있는 업무 문장으로 다듬는다.
불필요하게 추상적인 표현을 줄이고, 다음 행동이 보이는 문장으로 바꾼다.
description 앞부분의 한글 키워드는 한국어로 요청하는 사용자를 위한 라벨이다. [KO-06]
description 중간의 영어 키워드는 영어 단어가 섞인 요청을 위한 라벨이다. [KO-06]
아래 테스트 프롬프트는 스킬 이름을 직접 부르지 않고 암묵 매칭을 확인하기 위한 문장이다. [KO-06]
아래 영업 제안서 도입부를 더 설득력 있게 다듬어줘.
이번 프로젝트는 고객사의 업무 효율을 높이기 위해 다양한 개선 방안을 제공합니다.
아래 설정 줄은 암묵 호출을 끄는 예시로 사용한다. [OF-07]
allow_implicit_invocation: false
5. 응용·함정 — 변형, 자주 막히는 곳과 해결
첫 번째 함정은 description을 “좋은 문장을 작성합니다”처럼 넓게 쓰는 것이다. [KO-06]
넓은 설명은 사람 눈에는 친절해 보여도 암묵 매칭의 단서로는 약하다. [KO-06]
두 번째 함정은 한글 키워드만 넣고 영어 키워드를 빼는 것이다. [KO-06]
근거는 한글과 영어 키워드가 description의 암묵 매칭 정확도에 영향을 준다고 말한다. [KO-06]
세 번째 함정은 모든 스킬을 자동으로 불러오게 두는 것이다. [OF-07]
자동 호출이 필요 없는 스킬은 allow_implicit_invocation: false로 제어하는 장면을 함께 보여 준다. [OF-07]
막히면 세 가지만 확인한다. [OF-07, KO-06]
첫째, 파일 이름이 SKILL.md인지 확인한다. [OF-07]
둘째, description에 사용자가 실제로 입력할 한글·영어 키워드가 들어 있는지 확인한다. [KO-06]
셋째, agents/openai.yaml에서 allow_implicit_invocation: false가 들어가 암묵 호출을 막고 있지 않은지 확인한다. [OF-07]
6. 정리·체크리스트
SKILL.md는 스킬을 구성할 때 필요한 파일이다. [OF-07]
암묵 매칭 정확도는 SKILL.md의 description 필드에 달려 있다. [KO-06]
description에는 예쁜 소개문보다 실제 요청에 들어갈 한글·영어 키워드를 넣는다. [KO-06]
스킬 이름을 직접 부르지 않는 테스트로 암묵 호출을 확인한다. [KO-06]
암묵 호출을 막아야 할 때는 agents/openai.yaml의 allow_implicit_invocation: false를 확인한다. [OF-07]
마지막으로 기억할 문장은 하나다. “description은 스킬의 이름표이고, 좋은 이름표가 암묵 호출을 가른다.” [KO-06]
출처
본문의 [...] 표기는 아래 근거에서 확인할 수 있습니다.
- KO-06 — 스킬 암묵적 매칭 정확도는 SKILL.md description 필드(한/영 키워드)에 좌우 · https://www.gpters.org/dev/post/complete-guide-using-codex-nutBXkvgxKmQuPK
- OF-07 — SKILL.md 필수, agents/openai.yaml로 allow_implicit_invocation 제어 · https://developers.openai.com/codex/skills