grahama1970/skill-creator

Skill Creator

이 스킬은 효과적인 스킬 생성을 위한 지침을 제공합니다.

스킬에 대해

스킬은 특화된 지식, 워크플로우 및 도구를 제공하여 Codex의 기능을 확장하는 모듈식의 자체 포함된 폴더입니다. 스킬을 특정 도메인 또는 작업을 위한 "온보딩 가이드"로 생각하세요. 스킬은 Codex를 범용 에이전트에서 어떤 모델도 완전히 소유할 수 없는 절차적 지식을 갖춘 특화 에이전트로 변환합니다.

스킬이 제공하는 것

1. 특화 워크플로우 - 특정 도메인을 위한 다단계 절차
2. 도구 통합 - 특정 파일 형식 또는 API 작업을 위한 지침
3. 도메인 전문성 - 회사별 지식, 스키마, 비즈니스 로직
4. 번들 리소스 - 복잡하고 반복적인 작업을 위한 스크립트, 참조 자료, 에셋

핵심 원칙

간결성이 핵심

컨텍스트 윈도우는 공공재입니다. 스킬은 Codex가 필요로 하는 다른 모든 것(시스템 프롬프트, 대화 기록, 다른 스킬의 메타데이터, 실제 사용자 요청)과 컨텍스트 윈도우를 공유합니다.

기본 가정: Codex는 이미 매우 똑똑합니다. Codex가 아직 가지고 있지 않은 컨텍스트만 추가하세요. 각 정보 조각에 의문을 제기하세요: "Codex가 이 설명을 정말로 필요로 할까?" 그리고 "이 문단이 토큰 비용을 정당화할까?"

장황한 설명보다 간결한 예제를 선호하세요.

적절한 자유도 설정

작업의 취약성과 가변성에 맞게 특이성 수준을 조정하세요:

• 높은 자유도 (텍스트 기반 지침): 여러 접근 방식이 유효하고, 결정이 컨텍스트에 따라 달라지거나, 발견법(heuristics)이 접근 방식을 안내할 때 사용합니다.
• 중간 자유도 (의사 코드 또는 매개변수가 있는 스크립트): 선호되는 패턴이 존재하고, 일부 변형이 허용되거나, 구성이 동작에 영향을 미칠 때 사용합니다.
• 낮은 자유도 (특정 스크립트, 소수의 매개변수): 작업이 취약하고 오류가 발생하기 쉬우며, 일관성이 중요하거나, 특정 순서를 따라야 할 때 사용합니다.

Codex가 경로를 탐색한다고 생각하세요: 절벽이 있는 좁은 다리에는 특정 가드레일(낮은 자유도)이 필요한 반면, 열린 들판은 다양한 경로(높은 자유도)를 허용합니다.

검증 무결성 보호

반복 중에 하위 에이전트를 사용하여 스킬이 현실적인 작업에서 작동하는지 또는 의심되는 문제가 실제인지 검증할 수 있습니다. 이는 수정 후 스킬의 동작, 출력 또는 실패 모드에 대해 독립적인 검토를 원할 때 가장 유용합니다. 새 하위 에이전트를 시작할 수 있는 경우에만 이 작업을 수행하세요.

검증을 위해 하위 에이전트를 사용하는 경우 이를 평가 표면으로 취급하세요. 목표는 스킬이 일반화되는지 여부를 학습하는 것이지, 다른 에이전트가 유출된 컨텍스트에서 답을 재구성할 수 있는지 여부를 학습하는 것이 아닙니다.

원시 아티팩트(예: 프롬프트 예시, 출력, diff, 로그 또는 추적)를 선호하세요. 검증을 수행하는 데 필요한 최소한의 작업 로컬 컨텍스트를 제공하세요. 검증에 명시적으로 필요한 경우가 아니라면 의도된 답변, 의심되는 버그, 의도된 수정 사항 또는 이전 결론을 전달하지 마세요.

스킬의 구조

모든 스킬은 필수 SKILL.md 파일과 선택적 번들 리소스로 구성됩니다:

skill-name/
├── SKILL.md (필수)
│   ├── YAML 프론트매터 메타데이터 (필수)
│   │   ├── name: (필수)
│   │   └── description: (필수)
│   └── Markdown 지침 (필수)
├── agents/ (권장)
│   └── openai.yaml - 스킬 목록 및 칩용 UI 메타데이터
└── 번들 리소스 (선택 사항)
    ├── scripts/          - 실행 가능한 코드 (Python/Bash 등)
    ├── references/       - 필요에 따라 컨텍스트에 로드하기 위한 문서
    └── assets/           - 출력에 사용되는 파일 (템플릿, 아이콘, 글꼴 등)

SKILL.md (필수)

모든 SKILL.md는 다음으로 구성됩니다:

• 프론트매터 (YAML): name 및 description 필드를 포함합니다. 이 필드들은 Codex가 스킬이 사용되는 시점을 결정하기 위해 읽는 유일한 필드이므로, 스킬이 무엇인지, 언제 사용해야 하는지 명확하고 포괄적으로 설명하는 것이 매우 중요합니다.
• 본문 (Markdown): 스킬 사용에 대한 지침 및 안내입니다. 스킬이 트리거된 후에만 로드됩니다(로드될 수도 있고 그렇지 않을 수도 있음).

에이전트 메타데이터 (권장)

• 스킬 목록 및 칩을 위한 UI 지향 메타데이터입니다.
• 값을 생성하기 전에 references/openai_yaml.md를 읽고 해당 설명과 제약 조건을 따르세요.
• 스킬을 읽어 사람이 인식할 수 있는 display_name, short_description 및 default_prompt를 생성하세요.
• --interface key=value를 scripts/generate_openai_yaml.py 또는 scripts/init_skill.py에 전달하여 결정론적으로 생성하세요.
• 업데이트 시: agents/openai.yaml이 여전히 SKILL.md와 일치하는지 확인하세요. 오래된 경우 다시 생성하세요.
• 명시적으로 제공된 경우에만 다른 선택적 인터페이스 필드(아이콘, 브랜드 색상)를 포함하세요.
• 필드 정의 및 예시는 references/openai_yaml.md를 참조하세요.

번들 리소스 (선택 사항)

스크립트 (scripts/)

결정론적 신뢰성이 필요하거나 반복적으로 재작성되는 작업을 위한 실행 가능한 코드(Python/Bash 등)입니다.

• 포함하는 경우: 동일한 코드가 반복적으로 재작성되거나 결정론적 신뢰성이 필요할 때
• 예시: PDF 회전 작업을 위한 scripts/rotate_pdf.py
• 이점: 토큰 효율적, 결정론적, 컨텍스트에 로드하지 않고 실행 가능
• 참고: 스크립트는 패치 또는 환경별 조정을 위해 Codex가 여전히 읽어야 할 수 있습니다.

참조 자료 (references/)

Codex의 프로세스와 사고를 알리기 위해 필요에 따라 컨텍스트에 로드되는 문서 및 참조 자료입니다.

• 포함하는 경우: Codex가 작업하는 동안 참조해야 하는 문서의 경우
• 예시: 금융 스키마용 references/finance.md, 회사 NDA 템플릿용 references/mnda.md, 회사 정책용 references/policies.md, API 사양용 references/api_docs.md
• 사용 사례: 데이터베이스 스키마, API 문서, 도메인 지식, 회사 정책, 상세 워크플로우 가이드
• 이점: SKILL.md를 간결하게 유지하고, Codex가 필요하다고 판단할 때만 로드됩니다.
• 모범 사례: 파일이 큰 경우(>10k 단어), SKILL.md에 grep 검색 패턴을 포함하세요.
• 중복 방지: 정보는 SKILL.md 또는 참조 파일 중 한 곳에만 있어야 하며, 둘 다 있으면 안 됩니다. 상세 정보는 스킬의 실제 핵심이 아닌 한 참조 파일을 선호하세요. 이렇게 하면 컨텍스트 윈도우를 차지하지 않으면서 정보를 찾을 수 있게 하여 SKILL.md를 간결하게 유지합니다. 필수적인 절차 지침과 워크플로우 안내만 SKILL.md에 유지하고, 상세 참조 자료, 스키마, 예제는 참조 파일로 옮기세요.

에셋 (assets/)

컨텍스트에 로드되지 않고 Codex가 생성하는 출력 내에서 사용되는 파일입니다.

• 포함하는 경우: 스킬이 최종 출력에 사용될 파일을 필요로 할 때
• 예시: 브랜드 에셋용 assets/logo.png, PowerPoint 템플릿용 assets/slides.pptx, HTML/React 보일러플레이트용 assets/frontend-template/, 타이포그래피용 assets/font.ttf
• 사용 사례: 템플릿, 이미지, 아이콘, 보일러플레이트 코드, 글꼴, 복사 또는 수정되는 샘플 문서
• 이점: 출력 리소스를 문서와 분리하고, Codex가 파일을 컨텍스트에 로드하지 않고 사용할 수 있게 합니다.

스킬에 포함하지 말아야 할 것

스킬은 그 기능을 직접적으로 지원하는 필수 파일만 포함해야 합니다. 다음과 같은 불필요한 문서나 보조 파일을 생성하지 마세요:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 등등

스킬은 AI 에이전트가 당면한 작업을 수행하는 데 필요한 정보만 포함해야 합니다. 생성 과정, 설정 및 테스트 절차, 사용자 대상 문서 등에 대한 보조 컨텍스트를 포함해서는 안 됩니다. 추가 문서 파일을 생성하면 혼란만 가중됩니다.

점진적 공개 설계 원칙

스킬은 컨텍스트를 효율적으로 관리하기 위해 세 가지 수준의 로딩 시스템을 사용합니다:

1. 메타데이터 (name + description) - 항상 컨텍스트에 있음 (~100 단어)
2. SKILL.md 본문 - 스킬이 트리거될 때 (<5k 단어)
3. 번들 리소스 - Codex가 필요에 따라 (스크립트를 컨텍스트 윈도우에 읽어들이지 않고 실행할 수 있으므로 무제한)

점진적 공개 패턴

컨텍스트 팽창을 최소화하기 위해 SKILL.md 본문을 필수 사항으로 유지하고 500줄 미만으로 유지하세요. 이 한도에 근접하면 콘텐츠를 별도의 파일로 분할하세요. 콘텐츠를 다른 파일로 분할할 때, SKILL.md에서 해당 파일을 참조하고 언제 읽어야 하는지 명확히 설명하여 스킬의 독자가 해당 파일의 존재와 사용 시기를 알 수 있도록 하는 것이 매우 중요합니다.

핵심 원칙: 스킬이 여러 변형, 프레임워크 또는 옵션을 지원하는 경우, 핵심 워크플로우와 선택 지침만 SKILL.md에 유지하세요. 변형별 세부 정보(패턴, 예제, 구성)는 별도의 참조 파일로 이동하세요.

패턴 1: 참조 자료가 있는 상위 수준 가이드

# PDF 처리

## 빠른 시작

pdfplumber로 텍스트 추출:
[코드 예제]

## 고급 기능

- **양식 채우기**: 전체 가이드는 [FORMS.md](FORMS.md)를 참조하세요.
- **API 참조**: 모든 메소드는 [REFERENCE.md](REFERENCE.md)를 참조하세요.
- **예제**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md)를 참조하세요.

Codex는 필요할 때만 FORMS.md, REFERENCE.md 또는 EXAMPLES.md를 로드합니다.

패턴 2: 도메인별 구성

여러 도메인이 있는 스킬의 경우, 관련 없는 컨텍스트 로드를 피하기 위해 도메인별로 콘텐츠를 구성하세요:

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (수익, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용량, 기능)
    └── marketing.md (캠페인, 기여도)

사용자가 영업 지표에 대해 물으면 Codex는 sales.md만 읽습니다.

마찬가지로, 여러 프레임워크 또는 변형을 지원하는 스킬의 경우 변형별로 구성하세요:

cloud-deploy/
├── SKILL.md (워크플로우 + 공급자 선택)
└── references/
    ├── aws.md (AWS 배포 패턴)
    ├── gcp.md (GCP 배포 패턴)
    └── azure.md (Azure 배포 패턴)

사용자가 AWS를 선택하면 Codex는 aws.md만 읽습니다.

패턴 3: 조건부 세부 정보

기본 콘텐츠를 표시하고 고급 콘텐츠로 연결하세요:

# DOCX 처리

## 문서 생성

새 문서에는 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md)를 참조하세요.

## 문서 편집

간단한 편집의 경우 XML을 직접 수정하세요.

**변경 추적의 경우**: [REDLINING.md](REDLINING.md)를 참조하세요.
**OOXML 세부 정보의 경우**: [OOXML.md](OOXML.md)를 참조하세요.

Codex는 사용자가 해당 기능을 필요로 할 때만 REDLINING.md 또는 OOXML.md를 읽습니다.

중요 지침:

• 깊게 중첩된 참조 피하기 - 참조는 SKILL.md에서 한 수준 깊이로 유지하세요. 모든 참조 파일은 SKILL.md에서 직접 연결되어야 합니다.
• 긴 참조 파일 구조화 - 100줄이 넘는 파일의 경우, Codex가 미리 볼 때 전체 범위를 볼 수 있도록 상단에 목차를 포함하세요.

스킬 생성 프로세스

스킬 생성은 다음 단계를 포함합니다:

1. 구체적인 예제를 통해 스킬 이해
2. 재사용 가능한 스킬 콘텐츠 계획 (스크립트, 참조 자료, 에셋)
3. 스킬 초기화 (init_skill.py 실행)
4. 스킬 편집 (리소스 구현 및 SKILL.md 작성)
5. 스킬 검증 (quick_validate.py 실행)
6. 실제 사용을 기반으로 반복하고 복잡한 스킬은 사전 테스트.

이 단계를 순서대로 따르고, 적용할 수 없는 명확한 이유가 있는 경우에만 건너뛰세요.

스킬 이름 지정

• 소문자, 숫자 및 하이픈만 사용하세요. 사용자가 제공한 제목을 하이픈 케이스로 정규화하세요 (예: "Plan Mode" -> plan-mode).
• 이름을 생성할 때는 64자 미만(문자, 숫자, 하이픈)의 이름을 생성하세요.
• 동작을 설명하는 짧은 동사-주도 구문을 선호하세요.
• 명확성이나 트리거링을 개선하는 경우 도구별로 네임스페이스를 지정하세요 (예: gh-address-comments, linear-address-issue).
• 스킬 폴더 이름을 스킬 이름과 정확히 일치하게 지정하세요.

1단계: 구체적인 예제를 통한 스킬 이해

스킬의 사용 패턴이 이미 명확하게 이해된 경우에만 이 단계를 건너뛰세요. 기존 스킬로 작업할 때도 이 단계는 여전히 가치가 있습니다.

효과적인 스킬을 만들려면 스킬이 사용될 구체적인 예제를 명확히 이해하세요. 이러한 이해는 직접적인 사용자 예제 또는 사용자 피드백으로 검증된 생성된 예제에서 비롯될 수 있습니다.

예를 들어, 이미지 편집기 스킬을 구축할 때 관련 질문은 다음과 같습니다:

• "이미지 편집기 스킬이 어떤 기능을 지원해야 할까요? 편집, 회전, 그 외 다른 것은?"
• "이 스킬이 어떻게 사용될지 몇 가지 예를 들어주시겠습니까?"
• "사용자들이 '이 이미지에서 적목 현상을 제거해줘' 또는 '이 이미지를 회전시켜줘'와 같은 요청을 할 것이라고 상상할 수 있습니다. 이 스킬이 사용될 다른 방식이 있습니까?"
• "사용자가 이 스킬을 트리거하기 위해 무엇을 말해야 할까요?"
• "이 스킬을 어디에 만들어야 할까요? 선호하는 위치가 없다면, Codex가 자동으로 찾을 수 있도록 $CODEX_HOME/skills (또는 CODEX_HOME이 설정되지 않은 경우 ~/.codex/skills)에 배치하겠습니다."

사용자를 압도하지 않도록 한 번에 너무 많은 질문을 하지 마세요. 가장 중요한 질문부터 시작하고 필요에 따라 후속 질문을 하여 효율성을 높이세요.

스킬이 지원해야 할 기능에 대한 명확한 감이 생기면 이 단계를 마무리하세요.

2단계: 재사용 가능한 스킬 콘텐츠 계획

구체적인 예제를 효과적인 스킬로 전환하려면 각 예제를 다음과 같이 분석하세요:

1. 처음부터 예제를 실행하는 방법 고려
2. 이러한 워크플로우를 반복적으로 실행할 때 도움이 될 스크립트, 참조 자료 및 에셋 식별

예시: "이 PDF를 회전시켜줘"와 같은 쿼리를 처리하기 위한 pdf-editor 스킬을 구축할 때 분석 결과는 다음과 같습니다:

1. PDF를 회전하려면 매번 동일한 코드를 다시 작성해야 합니다.
2. 스킬에 저장할 scripts/rotate_pdf.py 스크립트가 도움이 될 것입니다.

예시: "할 일 앱을 만들어줘" 또는 "내 걸음 수를 추적하는 대시보드를 만들어줘"와 같은 쿼리를 위한 frontend-webapp-builder 스킬을 설계할 때 분석 결과는 다음과 같습니다:

1. 프론트엔드 웹앱을 작성하려면 매번 동일한 HTML/React 보일러플레이트가 필요합니다.
2. 보일러플레이트 HTML/React 프로젝트 파일이 포함된 assets/hello-world/ 템플릿을 스킬에 저장하는 것이 도움이 될 것입니다.

예시: "H

본문이 계속됩니다...