aiskillstore/marketplace

Skill Creator

Codex에 유용하고 비자명한 지침을 제공하되, 관련 없는 작업을 제한하지 않는 스킬을 생성합니다.

핵심 원칙

Codex가 이미 충분히 능숙하다고 가정합니다. 결정을 바꾸거나 작업을 개선하는 정보만 포함하세요. 일반적인 조언, 반복되는 지침, 추측성 예외 사례, 작업을 명확히 설명하는 데 실질적으로 도움이 되지 않는 예제는 제거하세요.

사용자 의도와 범위를 존중하세요. 스킬은 요청된 작업을 지원해야 하며, 사용자가 선택한 제품을 대체하거나, 할당된 작업을 확장하거나, 관련 없는 구성을 수정하거나, 추가적인 외부 작업에 대한 권한을 암시해서는 안 됩니다. 특정 예시, 과거 실패 사례, 개인적 선호도를 보편적 요구사항으로 바꾸지 마세요.

작업 완료 승인이 작업 범위나 실행 권한을 확장하지는 않습니다. 재시도나 외부 변경 워크플로의 경우 위험에 비례하는 중단 조건을 정의하세요.

세부 수준을 위험도에 맞추세요. 여러 접근 방식이 합리적일 때는 모델이 적절한 접근 방식을 선택할 여지를 주세요. 정확성, 안전성, 권한, 또는 진정으로 깨지기 쉬운 워크플로가 필요한 경우에만 상세한 단계, 결정론적 스크립트, 또는 절대적인 언어를 사용하세요.

열린 작업의 경우 결과물과 관련 의사 결정 기준을 설명하세요. 선호되는 형태의 워크플로가 있다면 유용한 예제나 설정 가능한 스크립트를 제공하세요. 고정된 시퀀스와 좁은 매개변수는 이탈이 구체적인 문제를 일으키는 작업에만 사용하세요. 비자명한 운영상 불변 조건을 보존하고, 실제 요구사항과 선택적 권장 사항 또는 로컬 관례를 구분하며, 다른 곳에서 이미 시행되고 있는 정책을 반복해서 언급하지 마세요.

발견을 저렴하고 정확하게 유지하세요. 스킬 이름과 설명은 스킬이 로드되기 전에 확인할 수 있습니다. 실제 기능과 적용 시점을 설명하고, 잘못된 라우팅을 방지하는 데 필요한 경우에만 제외 사항을 추가하세요. 관련 없는 요청을 유인하는 포괄적 기능 목록이나 catchall을 피하세요.

스킬은 자체 포함되도록 유지하세요. 요청된 워크플로가 진정으로 필요하고 대상 환경에서 사용 가능한 경우에만 다른 스킬이나 도구를 참조하세요. 특화된 검토, 강화, 또는 감사 워크플로는 요청되거나 진정으로 필요한 경우에만 적용해야 하며, 일반 작업이 동일한 주제를 다룬다고 해서 자동으로 적용해서는 안 됩니다.

세부 사항을 점진적으로 공개하세요. 공유 목적, 필수 제약 조건, 유용한 라우팅 정보는 SKILL.md에 유지하세요. 상당한 모드별 지침, 스키마, 예제, 절차는 지원 참조 자료에 넣고 현재 작업과 관련된 참조 자료만 읽으세요. 간단한 자체 포함 스킬에는 라우터나 추가 파일이 필요하지 않습니다.

스킬의 구조

모든 스킬은 필수 SKILL.md 파일과 실제 워크플로에 필요한 선택적 리소스를 포함하는 폴더입니다:

skill-name/
|-- SKILL.md                 필수 스킬 지침
|   |-- YAML frontmatter     필수 이름 및 설명
|   `-- Markdown body        스킬 사용 시 로드되는 지침
|-- agents/                  선택적 UI 메타데이터 및 호출 정책
|   `-- openai.yaml
|-- scripts/                 선택적 실행 가능 도우미
|-- references/              선택적 필요 시 로드되는 문서
`-- assets/                  선택적 생성된 출력에 사용되는 파일

실제 작업에 맞는 구조를 선택하세요. 일부 스킬은 짧고 자체 포함되어 있으며, 다른 스킬은 운영 모드 간을 라우팅하거나 복잡한 메커니즘을 스크립트에 위임합니다. 명확한 용도 없이 디렉토리, 플레이스홀더, 예제, 또는 보조 문서를 생성하지 마세요.

SKILL.md

YAML frontmatter는 스킬을 식별하고 언제 고려해야 하는지 결정합니다. 필수 name과 description을 포함하고, 기존 metadata와 같은 지원되는 선택적 필드는 적절한 경우 보존하세요.

Markdown 본문은 스킬이 사용될 때만 로드됩니다. 목적, 필수 워크플로, 실제 제약 조건, 유용한 링크를 여기에 넣으세요. 세부 절차와 예제는 특정 모드에만 관련된 경우 지원 참조 자료에 보관하세요.

스킬 정보는 세 단계로 공개됩니다:

1. 이름 및 설명: 스킬 선택 중에 사용 가능하므로 간결하고 차별화되게 유지하세요.
2. SKILL.md 본문: 스킬이 적용될 때 로드되므로 지침이 해당 작업과 관련되도록 유지하세요.
3. 지원 리소스: 현재 작업에 실제로 필요한 경우에만 읽거나 실행하세요.

진입점은 중요한 제약 조건을 유지하면서 작업이 허용하는 한 최대한 짧아야 합니다. 큰 상한선이 목표가 아닙니다: 조건부 세부 정보를 참조 자료로 이동하는 것이 명확성이나 컨텍스트 사용을 개선할 때, 파일이 다루기 어려워질 때까지 기다리지 말고 이동하세요.

Scripts

동일한 로직이 반복적으로 다시 작성되거나 결정론적 실행이 안정성을 실질적으로 개선하는 경우 scripts/를 실행 가능한 코드에 사용하세요.

• 예시: 동일한 코드를 다시 만들어야 하는 PDF 작업의 경우 scripts/rotate_pdf.py.
• 유용한 경우: 반복되는 변환, 신뢰할 수 있는 API 작업, 데이터 처리 및 기타 구체적인 자동화.
• 검증: 새롭거나 변경된 스크립트를 실행하여 동작을 확인하세요. 스크립트는 일반적으로 전체 구현을 컨텍스트에 로드하지 않고 실행할 수 있지만, 에이전트가 스크립트를 패치하거나 적용할 때 검사해야 할 수 있습니다.

References

특정 컨텍스트에서만 필요한 문서에는 references/를 사용하세요.

• 예시: 데이터베이스 테이블의 경우 references/schema.md, 도메인 규칙의 경우 references/policies.md, API의 경우 references/api_docs.md, 또는 다른 결과물에 대한 별도의 작성 가이드.
• 유용한 경우: 스키마, API 문서, 회사 정책, 형식별 절차, 상세 워크플로, 실질적인 예제.
• 라우팅: SKILL.md 또는 다른 관련 리소스에서 각 참조 자료에 링크하고 언제 읽어야 하는지 설명하세요. 정보를 진입점과 참조 자료에 중복하지 않고 한 곳에 유지하세요.

참조 자료는 유지 관리되는, 작업별 정보에 초점을 맞추고 에이전트의 결정을 변경하는 것으로 유지하세요. 복사된 매뉴얼, 포괄적인 카탈로그, 권위 있는 출처에서 이미 사용 가능한 일반 튜토리얼은 피하세요. 기존 리소스를 제거하기 전에 호출자와 목적을 검사하세요.

큰 참조 자료의 경우 필요한 자료를 더 쉽게 찾을 수 있게 해주는 유용한 검색어나 짧은 내용 섹션을 포함하세요.

Assets

생성된 출력에 속하고 모델의 지침에는 속하지 않는 파일에는 assets/를 사용하세요.

• 예시: assets/logo.png, assets/slides.pptx, assets/font.ttf, 또는 assets/frontend-template/.
• 유용한 경우: 템플릿, 이미지, 글꼴, 아이콘, 보일러플레이트 프로젝트 및 결과에 복사되거나 적용되는 기타 파일.
• 컨텍스트: 작업에서 검사가 필요한 경우가 아니라면 자산을 지침으로 로드하지 마세요.

UI 메타데이터 및 호출 정책

agents/openai.yaml은 display_name, short_description, default_prompt와 같은 UI용 메타데이터와 호출 정책을 제공할 수 있습니다. 이러한 설정을 생성하거나 업데이트할 때는 references/openai_yaml.md를 읽고 값을 스킬과 일관되게 유지하세요.

자동 스킬 선택은 기본적으로 허용됩니다. 사용자가 명시적 전용 스킬을 요청하는 경우에만 기본값을 변경하세요:

policy:
  allow_implicit_invocation: false

이렇게 하면 스킬이 자동으로 모델 컨텍스트에 추가되지 않고 $skill-name으로 명시적으로 호출될 때 사용 가능하게 유지됩니다. agents/openai.yaml을 업데이트할 때 기존의 관련 없는 UI, 정책, 종속성 필드를 보존하세요.

초기화 도구는 이 파일을 자동으로 생성합니다. 새 스킬 또는 인터페이스 전용 메타데이터의 경우 다음을 사용하여 생성하세요:

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

생성기는 전체 파일을 대체합니다. 기존 파일에 policy 또는 dependencies가 포함된 경우 다시 생성하는 대신 해당 필드만 직접 업데이트하세요.

선택적 인터페이스 필드는 사용자가 제공하거나 요청하는 경우에만 포함하세요.

포함하지 말아야 할 것

스킬의 작업을 직접 지원하는 파일만 포함하세요. 특정 작업이나 패키징 요구사항이 요구하지 않는 한 README.md, 설치 가이드, 변경 로그, 중복된 빠른 참조 또는 기타 보조 문서를 추가하지 마세요.

실제 점진적 공개

여러 주요 모드가 있는 스킬의 경우 공유 지침과 모드 선택 기준을 SKILL.md에 유지하세요. 각 지원 참조 자료가 관련성이 있을 때 링크하세요. 기본적으로 모든 참조 자료를 로드하거나, 진입점에 참조 콘텐츠를 중복하거나, 라우팅할 의미 있는 내용이 없는데 라우팅 레이어를 추가하지 마세요.

예를 들어, 배포 스킬은 공급자 선택을 SKILL.md에 유지하고 공급자별 세부 정보를 분리할 수 있습니다:

cloud-deploy/
|-- SKILL.md
`-- references/
    |-- aws.md
    |-- gcp.md
    `-- azure.md

사용자가 AWS를 선택하면 references/aws.md를 읽으세요. GCP 및 Azure 가이드는 로드하지 마세요. 동일한 패턴으로 비즈니스 도메인, 결과물 유형 또는 기타 실질적으로 구별되는 운영 모드를 분리할 수 있습니다.

짧은 스킬은 고급 작업에 필요할 때만 세부 정보로 라우팅할 수 있습니다:

## 문서

일반 편집은 직접 처리합니다.

- 변경 내용 추적의 경우 [references/redlining.md](references/redlining.md)를 읽으세요.
- 문서 내부 구조의 경우 [references/ooxml.md](references/ooxml.md)를 읽으세요.

이러한 예시는 필수 구조가 아닌 옵션을 보여줍니다. 관련 없는 자료를 로드하지 않고 스킬을 더 쉽게 사용할 수 있는 구성을 선택하세요.

스킬 생성 또는 업데이트

작업을 요청에 맞게 조정하세요. 복잡한 새 스킬을 생성하는 것은 실제 사용 사례 이해, 지원 리소스 선택, 파일 초기화, 지침 작성, 결과 검증을 포함할 수 있습니다. 기존 스킬의 좁은 업데이트는 집중된 편집과 검증만 필요할 수 있습니다.

누락된 정보가 중요하고 합리적으로 추론할 수 없는 경우에만 명확한 질문을 하세요. 사용자가 지정한 위치를 존중하세요. 그렇지 않으면 $CODEX_HOME/skills 또는 CODEX_HOME이 설정되지 않은 경우 ~/.codex/skills에 검색 가능한 스킬을 생성하세요.

사용자가 명시적 전용 스킬을 명시적으로 요청하지 않는 한 자동 스킬 선택을 활성화된 상태로 유지하세요. 의도된 호출 모드가 진정으로 불분명하고 요청된 워크플로에 중요한 경우, 사용자에게 일반 자동 검색을 원하는지 명시적 전용 호출을 원하는지 물어보세요. 그렇지 않으면 기본값을 유지하세요. 민감한 작업이나 필수 승인에서 명시적 전용 호출을 추론하지 마세요: 스킬을 검색 가능하게 유지하고 실제 변형 직전에 권한 부여를 요구하세요. 사용자가 변경을 요청하지 않는 한 기존 스킬의 호출 정책을 유지하세요.

새 스킬이나 대대적으로 수정된 스킬의 경우, 처리해야 할 실제 요청과 해당 작업을 개선할 재사용 가능한 리소스를 고려하세요:

• 반복되는 PDF 변환은 scripts/rotate_pdf.py 도우미를 정당화할 수 있습니다.
• 애플리케이션 구축 워크플로는 assets/frontend-template/ 스타터의 이점을 얻을 수 있습니다.
• 데이터 분석 스킬은 테이블 관계를 재발견하지 않도록 references/schema.md 가이드가 필요할 수 있습니다.

해당 리소스의 구체적인 이점이 정당화되는 경우에만 생성하세요. 사용자가 이미 작업을 명확하게 설명했다면 추가 예제를 요청하지 말고 진행하세요.

명명 규칙

• 소문자, 숫자, 하이픈을 사용하세요.
• 이름을 64자 미만으로 유지하고 짧고 행동 지향적인 이름을 선호하세요.
• 발견을 개선하는 경우 도구 또는 도메인별로 네임스페이스를 지정하세요.
• 스킬 폴더 이름을 스킬 이름과 동일하게 지정하세요.

새 스킬 초기화

새 스킬의 경우 번들 초기화 도구가 필요한 파일을 일관되게 생성하는 데 도움이 될 때 사용하세요:

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

예를 들어:

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references

스킬에 필요한 리소스 디렉토리만 요청하세요. --examples는 구체적인 플레이스홀더가 도움이 될 때만 사용하고 완료하기 전에 교체하거나 제거하세요. 기존 스킬을 다시 초기화하지 마세요.

초기화 도구는 스킬 디렉토리, 간결한 SKILL.md 시작 파일, agents/openai.yaml을 생성합니다. 리소스 디렉토리와 예제 파일은 요청된 경우에만 생성합니다. 필요할 때 생성된 UI 값을 --interface key=value로 전달하세요.

지침 작성

Frontmatter description은 스킬의 기능과 적용 시점을 간략히 설명해야 합니다. 유사한 요청이 스킬을 활성화해서는 안 되는 의미 있는 경계를 포함하세요.

예를 들어:

description: 서식 지정, 변경 내용 추적, 또는 주석에 문서별 처리가 필요한 경우 Word 문서를 생성하거나 편집합니다.

상세 워크플로, 도구 선택, 예제, 운영 모드는 설명에 모두 나열하기보다 본문이나 관련 참조 자료에 넣으세요. 적절한 경우 기존 metadata와 같은 지원되는 선택적 frontmatter를 보존하세요.

다른 Codex 인스턴스가 작업을 잘 수행하는 데 필요한 지침만 작성하세요. 원하는 결과, 비자명한 컨텍스트, 실제 제약 조건, 관련 참조 자료 또는 도구를 명시하세요. 사용자의 명시적 선택과 기존 권한 경계를 보존하세요. 작업이 필요로 하지 않는 한 고정된 구조, 프로세스, 또는 단계 수를 규정하지 마세요.

검증 및 반복

완료된 스킬을 다음으로 검증하세요:

scripts/quick_validate.py <path/to/skill-folder>

검증기는 frontmatter, 명명 규칙, 완료되지 않은 스캐폴드 플레이스홀더를 확인합니다. 스킬이 좋은 결정을 내린다는 것을 증명하지는 않습니다. 또한 설명이 여전히 차별화되는지, 지침이 사용자 의도를 보존하는지, 참조 자료를 찾을 수 있는지, 추가된 스크립트가 실제로 작동하는지 확인하세요.

테스트가 정당한 경우 관찰 가능한 동작이나 의미 있는 불변 조건을 검증하세요. 단순히 생성된 문구, 제목, 또는 정규식 패턴과 일치하는 테스트는 피하세요.

실제 사용 또는 입증된 실패를 기반으로 스킬을 개선하세요. 모든 잠재적 실패에 대해 보편적인 규칙을 축적하기보다 좁은 수정을 선호하세요.