ComposioHQ/skill-creator

Skill Creator

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

스킬에 대하여

스킬은 Codex의 기능을 특화된 지식, 워크플로우 및 도구로 확장하는 모듈식의 독립적인 패키지입니다. 이를 특정 도메인이나 작업에 대한 '온보딩 가이드'로 생각하면 됩니다. 스킬은 Codex를 범용 에이전트에서 어떤 모델도 완전히 가질 수 없는 절차적 지식을 갖춘 특수 에이전트로 변환합니다.

스킬이 제공하는 것

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

핵심 원칙

간결성이 핵심

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

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

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

적절한 자유도 설정

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

높은 자유도 (텍스트 기반 지침): 여러 접근 방식이 유효하고, 결정이 컨텍스트에 따라 달라지거나, 발견법이 접근 방식을 안내할 때 사용합니다.

중간 자유도 (의사코드 또는 매개변수가 있는 스크립트): 선호되는 패턴이 존재하고, 약간의 변형이 허용되거나, 구성이 동작에 영향을 미칠 때 사용합니다.

낮은 자유도 (특정 스크립트, 적은 매개변수): 작업이 취약하고 오류가 발생하기 쉬우며, 일관성이 중요하거나, 특정 순서를 따라야 할 때 사용합니다.

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

스킬의 해부학

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

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

SKILL.md (필수)

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

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

번들 리소스 (선택 사항)

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

점진적 공개 설계 원칙

스킬은 컨텍스트를 효율적으로 관리하기 위해 3단계 로딩 시스템을 사용합니다:

1. 메타데이터 (이름 + 설명) - 항상 컨텍스트에 있음 (~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. 스킬 패키징하기 (package_skill.py 실행)
6. 실제 사용을 기반으로 반복하기

이 단계들을 순서대로 따르되, 적용되지 않는 명확한 이유가 있는 경우에만 건너뛰세요.

스킬 이름 짓기

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

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

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

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

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

• "이미지 편집기 스킬이 지원해야 할 기능은 무엇인가요? 편집, 회전, 그 외 다른 것은요?"
• "이 스킬이 어떻게 사용될지 몇 가지 예를 들어 주시겠어요?"
• "사용자가 '이 이미지에서 적목 현상을 제거해 줘' 또는 '이 이미지를 회전해 줘'와 같은 요청을 할 것으로 예상됩니다. 이 스킬이 사용될 다른 방식이 있으신가요?"
• "사용자가 이 스킬을 트리거하기 위해 무엇을 말해야 할까요?"

사용자에게 부담을 주지 않으려면 한 메시지에 너무 많은 질문을 하는 것을 피하세요. 가장 중요한 질문부터 시작하고 필요에 따라 후속 질문을 하여 효율성을 높이세요.

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

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/ 템플릿을 스킬에 저장하는 것이 도움이 될 것임

예시: "오늘 로그인한 사용자는 몇 명인가요?"와 같은 쿼리를 처리하기 위한 big-query 스킬을 구축할 때 분석 결과는 다음과 같습니다:

1. BigQuery를 쿼리하려면 매번 테이블 스키마와 관계를 다시 검색해야 함
2. 테이블 스키마를 문서화한 references/schema.md 파일을 스킬에 저장하는 것이 도움이 될 것임

스킬의 콘텐츠를 확립하려면 각 구체적인 예제를 분석하여 포함할 재사용 가능한 리소스(스크립트, 참조, 에셋) 목록을 만드세요.

3단계: 스킬 초기화하기

이제 실제로 스킬을 생성할 때입니다.

개발 중인 스킬이 이미 존재하고 반복이나 패키징이 필요한 경우에만 이 단계를 건너뛰세요. 이 경우 다음 단계로 계속 진행하세요.

처음부터 새 스킬을 생성할 때는 항상 init_skill.py 스크립트를 실행하세요. 이 스크립트는 스킬에 필요한 모든 것을 자동으로 포함하는 새 템플릿 스킬 디렉토리를 편리하게 생성하여 스킬 생성 프로세스를 훨씬 더 효율적이고 안정적으로 만듭니다.

사용법:

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

예시:

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

스크립트는:

• 지정된 경로에 스킬 디렉토리를 생성합니다.
• 적절한 프론트매터와 TODO 플레이스홀더가 있는 SKILL.md 템플릿을 생성합니다.
• 선택적으로 --resources 를 기반으로 리소스 디렉토리를 생성합니다.
• --examples 가 설정된 경우 선택적으로 예제 파일을 추가합니다.

초기화 후, 필요에 따라 SKILL.md를 사용자 지정하고 리소스를 추가하세요. --examples 를 사용한 경우 플레이스홀더 파일을 교체하거나 삭제하세요.

4단계: 스킬 편집하기

(새로 생성되었거나 기존) 스킬을 편집할 때, 스킬이 다른 Codex 인스턴스(Codex가 중앙 저장소에서 스킬을 가져오는 경우) 또는 Codex의 미래 자체를 위해 생성되고 있음을 기억하세요. 즉, 항상 스킬이 당신(편집자)이 아니라 독자(Codex)에 의해 사용되고 있다고 가정하세요. 이 관점은 명확하고 완전하며 모호하지 않은 지침을 만드는 데 중요합니다.

Codex의 관점에서 SKILL.md 읽기 - SKILL.md의 모든 내용을 Codex의 관점에서 검토하세요:

• "Codex가 이 작업을 수행하는 방법을 이미 알고 있나요?" - 설명을 추가하기 전에 Codex의 기본 지식을 신뢰하세요. 예를 들어, Codex는 Python, Docker, pytest의 목적을 이미 알고 있으므로 이를 설명할 필요가 없습니다.
• "이 정보는 필수인가요?" - 관련 없는 세부 사항이나 과도한 맥락을 제거하세요. Codex가 relation-manager의 역사나 데이터베이스 마이그레이션의 개념을 알 필요는 없습니다.
• "이것이 너무 모호한가요?" - 지침은 구체적이고 실행 가능해야 합니다. "프로세스 사용"이 아니라 "get_orders() 호출"이라고 명시하세요.
• "예제가 필요한가요?" - 추상적인 규칙보다 구체적인 예제가 더 좋은 경우가 많습니다. 한 줄의 의사코드가 한 단락의 설명보다 더 명확할 수 있습니다.

파일 시스템에 접근하세요 - 스킬에서 파일 경로를 참조할 때는 항상 하드코딩된 절대 경로 대신 동적 파일 시스템 접근을 사용하세요. /Users/username/projects/skill-name/scripts/... 와 같은 경로를 작성하지 마세요. 대신 일반적인 scripts/rotate_pdf.py 또는 references/api_docs.md 를 사용하세요. 이렇게 하면 스킬이 모든 환경에서 이식 가능하게 유지됩니다.

참조 파일에서 SKILL.md로 정보를 승격하지 마세요 - 참조 파일의 정보로 SKILL.md를 채우고 싶은 유혹을 피하세요. 참조 파일은 SKILL.md를 간결하게 유지하기 위해 존재합니다. 이 원칙을 위반하면 컨텍스트 윈도우가 부풀려집니다. 핵심 절차적 지침만 SKILL.md에 유지하고, 자세한 스키마, 예제 및 구성은 참조 파일에 보관하세요.

사용자 정의 로직

다음과 같이 SKILL.md 상단에 사용자 정의 로직이 필요한 조건을 명시하세요:

> 이 스킬은 `assets/` 번들 리소스가 필요합니다.
> 이 스킬은 `scripts/` 번들 리소스가 필요합니다.

이러한 조건은 Codex가 스킬을 사용할 때 스킬 리소스를 로드하도록 안내하는 데 도움이 됩니다.

SKILL.md 작성

SKILL.md는 대신 Codex가 작업을 수행하는 방법에 대한 모든 지침을 포함합니다. 다음을 포함해야 합니다:

• 상세 지침 - 각 단계를 자세히 설명하세요. "PDF 추출"이 아니라 "import pdfplumber를 사용하여 모든 페이지를 반복하고 extract_text()를 호출"이라고 명시하세요.
• 워크플로우 - "컨텍스트를 확인하는 것으로 시작"하거나 "구성을 읽는 것으로 시작"과 같은 시작 지점을 포함한 다단계 절차입니다.
• 코드 예제 - 최대한 많이 사용하세요. 예제를 선호하세요. 일반적으로 한 줄의 예제가 한 단락의 설명보다 낫습니다.
• 규칙 및 제약 조건 - Codex가 따라야 할 중요한 규칙을 포함하세요.

SKILL.md를 작성할 때는 이 템플릿을 사용하세요:

---
name: <name>
description: <description>
---

# <name>

## 요구 사항

- (선택 사항) 특정 리소스 파일에 대한 요구 사항을 설명합니다

## 개요

- 작업의 맥락과 목적을 간략히 설명합니다

## 워크플로우

1. 단계 1...
2. 단계 2...
3. 단계 3...

## 지침

### 지침 카테고리 1

[지침...]

### 코드 예제

[예제...]

5단계: 스킬 패키징하기

스킬이 완료되면 패키징 스크립트를 실행하여 간결한 JSON 설명을 생성하세요.

사용법:

scripts/package_skill.py <skill-dir> --output-dir <output-dir> [--validate] [--no-install]

기본 사용법

scripts/package_skill.py skills/public/my-skill --output-dir skills/packaged

검증

scripts/package_skill.py skills/public/my-skill --output-dir skills/packaged --validate

--validate는 패키징된 JSON에 대해 LSP 검사를 실행하고 구문 문제를 보고합니다. 발견된 문제를 수정한 후 다시 실행하세요.

puppeteer 설치 방지(권장)

scripts/package_skill.py skills/public/my-skill --output-dir skills/packaged --no-install

--no-install은 의존성 설치 단계를 건너뛰어 더 빠르게 실행됩니다. --validate가 필요하지 않은 경우 포함하세요.

6단계: 실제 사용을 기반으로 반복하기

스킬을 사용할 때 생성하는 컨텍스트를 검토하세요. 예를 들어, Codex가 사용자가 제공한 코드 예제로 작업하는 것을 본다면, 해당 예제를 참조 파일로 이동하는 것을 고려하세요.

반복을 위한 신호:

참조 파일로 이동해야 할 신호:

• SKILL.md 본문이 500줄 또는 5k 단어를 초과함
• Codex가 동일한 정보나 예제를 반복적으로 다시 작성함
• Codex가 사용자로부터 동일한 질문을 반복함
• Codex가 부정확한 패턴을 생성함
• Codex가 잘못된 API를 호출함
• 스킬이 환경 변수 또는 인증서와 같이 변경되는 것들에 의존함

조정해야 할 신호:

• Codex가 혼란스러워 하거나 스킬을 일관되게 잘못 사용함
• Codex가 SKILL.md를 읽은 후에도 동일한 질문을 함
• Codex가 잘못된 리소스(스크립트, 참조, 에셋)를 선택함

제거해야 할 신호:

• Codex가 불필요한 정보를 반복하거나 컨텍스트를 낭비함
• Codex가 관련 없는 도구나 라이브러리를 언급함
• Codex가 관련 없는 단계를 실행함

최종 참고 사항

효과적인 스킬을 만드는 것은 지속적인 개선 프로세스입니다. 실제 사용을 관찰하고, 정보가 어떻게 소비되는지 이해하며, 가장 큰 영향을 미치는 부분을 지속적으로 개선하세요.