Skills 해부 — SKILL.md·progressive disclosure·컨텍스트 2% 규칙
학습목표 / 사전지식: 이 레슨을 끝내면 Skills가 무엇을 묶는지, 왜 SKILL.md가 중심인지, progressive disclosure와 2%/8,000자 규칙이 Skill 설계에 어떤 영향을 주는지 설명할 수 있다. [OF-05, OF-06, OF-07]
1. 왜 필요한가 — 개념·배경을 초보자 눈높이로 [근거]
Skills는 반복해서 쓸 업무 방식과 자료와 도구를 한 묶음으로 보관하는 구조다. [OF-05]
공식 표현은 “packaging instructions, resources, and optional scripts”이며, instructions는 작업 지시문, resources는 참고 자료, optional scripts는 필요할 때 실행할 수 있는 보조 스크립트로 이해하면 된다. [OF-05]
비유하면 Skill은 여행 가방이다. [OF-05]
가방 안에는 일정표 같은 지시문, 지도 같은 참고 자료, 필요할 때 꺼내는 계산기 같은 선택 도구가 따로 들어간다. [OF-05]
이 가방의 이름표 역할을 하는 파일이 SKILL.md다. [OF-07]
SKILL.md는 필수이며, 근거에는 “SKILL.md (required)”라고 적혀 있다. [OF-07]
progressive disclosure는 처음부터 가방을 전부 뒤집어 놓지 않고, 필요한 물건만 차례로 꺼내는 방식이다. [OF-05]
Skills는 명시 호출과 암묵 호출을 다룰 수 있다. [OF-05]
암묵 호출을 막고 싶을 때는 agents/openai.yaml에서 allow_implicit_invocation: false를 사용한다. [OF-07]
컨텍스트 창은 지금 작업대 위에 펼쳐 놓을 수 있는 글자 공간으로 생각하면 쉽다. [OF-06]
초기 Skill 목록은 컨텍스트 창의 “maximum 2% of context window or 8,000 characters”까지만 소비한다. [OF-06]
그래서 Skill의 첫 설명은 간판처럼 짧고 분명해야 하고, 긴 설명은 필요할 때 펼쳐 볼 자료로 따로 빼 두는 편이 좋다. [OF-05, OF-06]
2. 준비 — 코덱스 어디로 들어가 무엇을 누르나
이 시연 화면은 왼쪽에 Skill 번들 구조, 오른쪽에 SKILL.md 내용을 보여주는 방식으로 구성한다. [OF-05, OF-07]
화면에는 SKILL.md, resources, scripts, agents/openai.yaml 네 가지 이름이 보이게 둔다. [OF-05, OF-07]
처음에는 필수 파일인 SKILL.md를 열고, 다음에는 resources와 scripts가 Skill 번들에 들어갈 수 있음을 보여준다. [OF-05, OF-07]
마지막에는 agents/openai.yaml의 allow_implicit_invocation: false 설정을 보여준다. [OF-07]
3. 따라하기 — 단계별로 아주 세세하게
1단계는 SKILL.md를 여는 장면이다. [OF-07]
화면에는 이 Skill을 언제 써야 하는지 짧게 적힌 영역을 보여준다. [OF-05, OF-07]
입력할 말은 “이 Skill의 목적과 호출 조건을 먼저 확인해 줘”처럼 짧게 둔다. [OF-05]
2단계는 resources를 보여주는 장면이다. [OF-05]
화면에는 긴 참고 자료를 바로 본문에 붙이지 않고 resources 쪽에 둔 예를 보여준다. [OF-05, OF-06]
입력할 말은 “필요한 참고 자료가 있으면 그때 열어 줘”라고 둔다. [OF-05]
3단계는 scripts를 보여주는 장면이다. [OF-05]
입력할 말은 “반복 처리에 도움이 될 때만 스크립트를 사용해 줘”라고 둔다. [OF-05]
결과는 스크립트가 필수가 아니라 optional scripts라는 점을 확인하는 방식으로 설명한다. [OF-05]
4단계는 agents/openai.yaml을 여는 장면이다. [OF-07]
화면에는 allow_implicit_invocation: false 한 줄을 크게 보여준다. [OF-07]
입력할 말은 “이 Skill은 내가 이름을 부를 때만 쓰게 해 줘”라고 둔다. [OF-05, OF-07]
5단계는 2%/8,000자 한계를 확인하는 장면이다. [OF-06]
화면에는 짧은 Skill 설명과 긴 resources 문서를 나란히 보여준다. [OF-05, OF-06]
결과는 초기 Skill 목록이 컨텍스트 창의 최대 2% 또는 8,000자까지만 소비한다는 규칙으로 해석한다. [OF-06]
4. 복붙 템플릿 — 그대로 쓰는 프롬프트/Skill + 각 부분 해설
아래 프롬프트는 명시 호출을 연습하기 위한 문장이다. [OF-05]
이 작업에는 [스킬명] Skill을 사용해 주세요.
먼저 SKILL.md만 확인해 주세요.
필요한 경우에만 resources나 scripts를 열어 주세요.
마지막에 어떤 파일을 왜 열었는지 짧게 알려 주세요.
첫 줄은 사용자가 Skill을 직접 부르는 명시 호출을 만든다. [OF-05]
둘째 줄은 필수 파일인 SKILL.md를 먼저 보게 만드는 장치다. [OF-07]
셋째 줄은 instructions, resources, optional scripts가 한 번에 모두 펼쳐지지 않도록 하는 progressive disclosure 연습이다. [OF-05]
아래는 SKILL.md를 작성할 때 쓸 수 있는 짧은 골격이다. [OF-07]
# Skill name
## Use when
- 이 Skill을 써야 하는 상황을 짧게 쓴다.
## Do not use when
- 이 Skill을 쓰지 말아야 하는 상황을 짧게 쓴다.
## Process
1. Read SKILL.md.
2. Open only needed resources.
3. Use optional scripts only when useful.
## Output format
- 결과 형식을 짧게 쓴다.
이 골격은 필수 파일인 SKILL.md에 호출 기준과 진행 순서를 짧게 담기 위한 틀이다. [OF-05, OF-07]
암묵 호출을 끄는 설정 예시는 아래처럼 둔다. [OF-07]
allow_implicit_invocation: false
5. 응용·함정 — 변형, 자주 막히는 곳과 해결
첫 번째 함정은 SKILL.md에 설명을 전부 욱여넣는 것이다. [OF-05, OF-06]
초기 Skill 목록은 최대 2% 또는 8,000자 규칙의 영향을 받으니, 첫 설명은 짧게 두고 긴 자료는 resources로 빼는 편이 맞다. [OF-05, OF-06]
다음 함정은 scripts를 필수로 여기는 것이다. [OF-05]
근거 표현이 optional scripts인 만큼, 스크립트는 필요할 때만 꺼내 쓰는 선택 도구로 다룬다. [OF-05]
마지막 함정은 암묵 호출을 켜 둔 채 Skill이 언제 실행되는지 몰라 헤매는 것이다. [OF-05, OF-07]
이럴 때는 agents/openai.yaml의 allow_implicit_invocation: false를 보여 준다. [OF-07]
6. 정리·체크리스트
Skills는 instructions, resources, optional scripts를 함께 포장하는 번들이다. [OF-05]
SKILL.md는 필수 파일이다. [OF-07]
progressive disclosure는 필요한 자료를 단계적으로 여는 구조다. [OF-05]
초기 Skill 목록은 컨텍스트 창의 최대 2% 또는 8,000자까지만 소비한다. [OF-06]
암묵 호출은 agents/openai.yaml의 allow_implicit_invocation: false로 제어하는 예를 보여 줄 수 있다. [OF-07]
체크리스트는 SKILL.md가 짧고 분명한지, 긴 자료가 resources로 빠졌는지, 암묵 호출을 허용할지 막을지 확인하는 것이다. [OF-05, OF-06, OF-07]
출처
본문의 [...] 표기는 아래 근거에서 확인할 수 있습니다.
- OF-05 — Skills = 지시문·리소스·스크립트 번들, 명시/암묵 호출, progressive disclosure · https://developers.openai.com/codex/skills
- OF-06 — 스킬 초기 목록은 컨텍스트의 최대 2% 또는 8,000자까지 소비 · https://developers.openai.com/codex/skills
- OF-07 — SKILL.md 필수, agents/openai.yaml로 allow_implicit_invocation 제어 · https://developers.openai.com/codex/skills