awesome-codex-skills 딥다이브
— 스킬 880개, 그중 832개는 이름만 다른 같은 파일이다

1한눈에 — 이 레포의 정체

awesome-codex-skills는 Composio라는 회사가 운영하는, OpenAI Codex(CLI·API)용 SKILL.md 폴더 모음집이다. "스킬"이란 에이전트에게 "이런 요청이 오면 이렇게 처리해라"는 매뉴얼을 폴더 하나로 묶어 주는 표준 포맷인데, 이 레포는 그 포맷으로 쓰인 스킬을 두 가지 완전히 다른 방식으로 채워 넣었다. 하나는 사람이 손으로 설계한 48개의 워크플로 스킬(회의록 정리, PR 리뷰, GitHub 이슈 트리아지 등 — 레포 최상위에 폴더별로 존재), 다른 하나는 Composio 자신의 통합 카탈로그를 그대로 훑어 거의 동일한 템플릿에 서비스 이름만 바꿔 넣은 832개의 "자동화" 스킬(composio-skills/<서비스명>-automation/)이다.

동작 흐름을 압축하면 이렇다:

2왜 생겼나 — "Codex 스킬"이라는 개념의 등장

이 레포가 존재하는 이유를 이해하려면 두 가지 흐름이 겹쳐야 한다. 첫째는 코딩 에이전트 진영 전체의 "스킬" 표준화다. Claude Code가 먼저 SKILL.md 폴더 규격(프런트매터 + 본문 + 동봉 리소스)을 정착시켰고, Codex도 같은 폴더 규격을 그대로 받아들였다 — 이 레포에 동봉된 설치 도구(skill-installer/scripts/list-curated-skills.py)가 기본값으로 openai/skills 레포의 skills/.curated 경로를 조회하도록 설정된 것에서 보이듯, OpenAI 자신도 공식 큐레이션 스킬 저장소를 운영하고 있다. awesome-codex-skills는 그 공식 목록의 third-party 확장판인 셈이다.

둘째는 "도구가 너무 많아졌다"는 문제다. 에이전트가 MCP로 수백~수천 개의 외부 도구에 연결되면, 그 스키마를 전부 컨텍스트에 욱여넣는 건 비효율적이다. 스킬 포맷의 핵심 아이디어인 프로그레시브 디스클로저(progressive disclosure) — 평소엔 짧은 description만 들고 있다가 필요할 때만 본문을 펼치는 방식 — 이 문제를 정확히 겨냥한다. 흥미로운 건 Composio의 Rube MCP도 같은 아이디어를 도구 레이어에서 한 번 더 적용한다는 점이다: 1,000여 개 서비스의 API를 낱개 도구로 노출하는 대신, RUBE_SEARCH_TOOLS·RUBE_MANAGE_CONNECTIONS·RUBE_MULTI_EXECUTE_TOOL 같은 범용 동사 몇 개로 압축하고, 실제 스키마는 그때그때 검색해서 가져온다.

이 두 흐름이 만나는 지점에서 awesome-codex-skills의 구조가 설명된다. 사람이 쓴 48개는 "에이전트가 반복 작업을 잘 해내려면 어떤 절차·스크립트·참고자료가 필요한가"라는 스킬 포맷 본연의 질문에 답한 결과물이고, 기계가 찍어낸 832개는 "우리 회사의 통합 카탈로그를 스킬 발견 메커니즘에 노출시키자"는 완전히 다른 동기의 산물이다. 이름은 같은 "스킬"이지만 태어난 이유가 다르다.

3스킬이 뭔지 기초부터

가장 쉬운 비교는 "매번 프롬프트에 다 설명해주기" vs "미리 적어둔 매뉴얼을 필요할 때 꺼내 읽기"다. 스킬이 없으면, 사용자가 "회의록을 액션 아이템으로 정리해줘"라고 할 때마다 "이런 형식으로, 이런 순서로 해줘"를 매번 새로 설명해야 한다. 스킬이 있으면, 그 절차가 폴더 하나에 저장되어 있고 에이전트는 관련 요청이 왔을 때 그 폴더를 스스로 찾아 펼친다.

awesome-codex-skills를 읽다 보면 스킬이 실제로는 두 가지 다른 방식으로 "일을 시킨다"는 게 보인다:

세 번째 유형이 중요한 이유는, 이 유형의 스킬은 발동되는 순간 사용자의 실제 계정으로 실제 행동(이메일 발송, Slack 게시, GitHub 이슈 생성 등)을 일으킨다는 점이다. 이 특성은 뒤에서(9장) 보안 리스크로 다시 다룬다.

4SKILL.md 해부 — 실제 파일 기준

레포에서 가장 단순한 SKILL.md는 template-skill/에 들어있는 "빈 틀"이다. 이게 스킬의 최소 골격이다:

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

frontmatter는 ---로 감싼 YAML이고, 그 아래는 마크다운 자유 형식이다. 실전 예시로 meeting-notes-and-actions/SKILL.md를 보면 필드가 하나 더 붙는다:

---
name: meeting-notes-and-actions
description: Turn meeting transcripts or rough notes into crisp summaries
  with decisions, risks, and owner-tagged action items; use for Zoom/Meet/Teams
  transcripts, call notes, or long meeting chats to generate share-ready outputs.
metadata:
  short-description: Meeting transcript to notes and actions
---

레포에 동봉된 검증 스크립트 skill-creator/scripts/quick_validate.py를 직접 읽으면 공식적으로 허용된 프런트매터 키가 정확히 무엇인지가 코드로 박혀 있다:

allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}

디렉토리 레이아웃 — README가 규정한 것과 실제로 관찰되는 것

README의 "Creating Skills" 절이 명시하는 공식 레이아웃은 세 가지 선택적 리소스뿐이다:

그런데 실제 48개 최상위 스킬을 뒤져보면 이 규정에 없는 폴더 이름이 여럿 관찰된다: mcp-builder·notion-* 4종은 references가 아니라 단수형 reference/를 쓰고, notion-* 4종은 여기에 더해 examples/와 evaluations/까지 추가로 만들어 쓴다. agent-deep-links는 Codex 전용 메타데이터 파일 agents/openai.yaml을 동봉한다(전면 UI에서 스킬을 어떻게 표시할지 정의 — display_name·short_description·default_prompt). 즉 SKILL.md 자체의 스키마는 코드로 강제되지만, 동봉 폴더 이름은 강제되지 않는 관례일 뿐이다 — 이 레포 안에서도 통일돼 있지 않다.

5레포 구조와 카테고리 지도 (실제 숫자)

GitHub이 이 레포의 주 언어를 Python으로 표시하지만, 파일 개수·바이트 수 어느 쪽으로 봐도 실체는 마크다운 프롬프트 저장소에 가깝다 — .py는 35개(272KB)뿐이고 .md는 952개(3.3MB)로 10배 이상이다. Python이 상위로 잡히는 건 아마도 스크립트를 가진 12개 스킬의 코드 밀도 때문일 텐데, 어느 쪽이든 "이 레포를 열면 파이썬 코드가 잔뜩 나온다"는 인상은 정확하지 않다.

README가 선언한 5개 카테고리 (로컬 폴더 48 + 외부 링크 12)

이 표에 composio-skills/의 832개는 아예 등장하지 않는다. README의 "Skills" 섹션 어디에도 composio-skills/ 폴더에 대한 언급이 없다 — 카테고리 매니페스트도, 개수 안내도 없이 그냥 레포 안에 통째로 들어있다. 성격상 굳이 분류하면 "Meta & Utilities"(도구 연결)에 가장 가깝지만, 공식 목록은 이 존재를 사실상 언급하지 않은 채 방치하고 있다.

6대표 스킬 5개 뜯어보기

7내 Codex에 설치하고 쓰는 법

방법 1 — 설치 스크립트 (권장, README 원문)

# README에 실제로 이렇게 적혀 있다 (조직명 표기에 주의 — 아래 danger 박스 참고)
git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills
python skill-installer/scripts/install-skill-from-github.py \
  --repo ComposioHQ/awesome-codex-skills --path meeting-notes-and-actions
# → $CODEX_HOME/skills/meeting-notes-and-actions (기본값 ~/.codex/skills/)

방법 2 — 수동 복사

# 원하는 스킬 폴더를 그대로 복사하면 끝
cp -r ./spreadsheet-formula-helper $CODEX_HOME/skills/
# (CODEX_HOME 미설정 시 ~/.codex/skills/)
# 이후 Codex를 재시작해야 새 메타데이터를 인식한다

설치 확인

ls ~/.codex/skills
head ~/.codex/skills/meeting-notes-and-actions/SKILL.md

설치만으로 끝나는 스킬(지침형)도 있지만, 도구 위임형 스킬(6장의 ③④)은 별도 준비가 필요하다:

Codex는 세션 중 자연어 요청이 어떤 스킬의 description과 맞아떨어지는지 판단해 자동으로 트리거한다. 스킬 이름을 직접 언급해도 되지만(README 문구: "you can also mention a skill by name if you want it considered"), 강제 로드 문법은 별도로 문서화돼 있지 않다.

8Claude Code 스킬과의 차이·호환성

이 레포를 실제로 열어보면 "Codex 스킬과 Claude Code 스킬이 얼마나 호환되는가"라는 질문에 레포 스스로가 답을 하고 있다 — mcp-builder·canvas-design·webapp-testing·theme-factory·internal-comms·slack-gif-creator는 설명 문구와 LICENSE.txt(Apache-2.0) 내용까지 Anthropic이 공개한 동명의 Claude 공식 스킬과 사실상 동일하다. brand-guidelines만 "OpenAI's brand colors... Codex/OpenAI 룩앤필"로 본문이 각색돼 있을 뿐, 나머지는 이름조차 안 바뀐 채로 Codex 저장소에 들어와 있다. 즉 SKILL.md라는 파일 포맷 자체는 두 진영이 완전히 공유한다는 뜻이다 — 폴더를 복사해서 이름만 인식시키면 그대로 작동할 만큼.

실전 질문으로 정리하면: "이 레포의 스킬 폴더를 Claude Code의 ~/.claude/skills/에 그대로 복사하면 작동하는가?" — name·description(+license·metadata)만 쓰는 48개 중 상당수는 포맷이 동일하므로 그대로 작동할 가능성이 높다(실제로 그 반대 방향, 즉 Claude 스킬이 이 레포에 그대로 들어와 있는 사례가 이미 존재한다). 반면 requires 필드를 가진 832개는 스키마 밖의 키를 포함하고 있어, 엄격한 검증기를 통과한다는 보장이 없다 — 기반 포맷은 이식 가능해도, 각 진영이 얹은 확장 필드까지 자동으로 호환되는 것은 아니다.

9품질·보안 리스크 — 남의 스킬이 내 셸에서 실행된다

레포 자신의 규칙을, 레포 자신이 어긴다

skill-creator/SKILL.md는 스킬 작성자에게 이렇게 명시한다: "Do not include any other fields in YAML frontmatter"(프런트매터에 다른 필드를 넣지 말 것) — name과 description 외엔 적지 말라는 뜻이다. 같은 폴더의 quick_validate.py는 이보다 조금 관대하게 {name, description, license, allowed-tools, metadata} 5개까지 허용한다. 그런데 이 검증 스크립트를 composio-skills/의 자동화 스킬에 실제로 돌려보면:

$ python3 skill-creator/scripts/quick_validate.py composio-skills/ably-automation
Unexpected key(s) in SKILL.md frontmatter: requires.
Allowed properties are: allowed-tools, description, license, metadata, name

$ # 832개 전체에 동일한 검증을 반복 실행한 결과
총 832 개 중 검증 실패 832 개

편집 감수성의 흔적 — 자매 레포에서 넘어온 문구들

connect-apps/SKILL.md는 Codex 레포 최상위(사람이 골랐다고 봐야 할 48개) 안에 있으면서도 본문 전체가 "Connect Claude to external apps", "Ask Claude to... / Claude runs" 식으로 쓰여 있다 — 바로 옆 connect/SKILL.md가 "Connect Codex..."로 정확히 각색된 것과 대비된다. 이 문서 전체에서 "Claude"라는 단어가 남아있는 파일은 11개(canvas-design·file-organizer·template-skill·content-research-writer·internal-comms·langsmith-fetch·invoice-organizer·connect-apps·skill-share 등)로, 대부분은 "다음 Claude가 판단할 여지를 남겨라" 같은 일반적 조언 문맥이라 큰 문제는 아니지만, connect-apps만큼은 스킬 전체의 정체성(어느 에이전트를 부르는가)이 통째로 안 바뀐 사례다.

진짜 위험 — "설치"가 곧 "권한 위임"이라는 점

이 레포 스킬의 상당수는 사용자의 실제 계정으로 실제 부작용(side effect)을 일으키도록 설계돼 있다 — connect/SKILL.md의 표어 그대로 "초안을 보여주는 대신 실제로 이메일을 보내고, 이슈를 만들고, 메시지를 올린다." 이 실행 경로는 두 갈래다: ① composio execute SLUG(로컬 Composio CLI, connect·connect-apps) ② Rube MCP의 RUBE_MULTI_EXECUTE_TOOL(832개 automation 스킬). 두 경로 모두 사용자가 이미 OAuth로 연결해 둔 진짜 Gmail·Slack·GitHub·Notion 계정을 사용한다.

여기서 신뢰 경계가 어떻게 뚫릴 수 있는지 정리하면:

• 설치 시점 검증 없음 — skill-installer는 "SKILL.md 파일이 존재하는가"만 확인한다. 내용이 안전한지, 스키마를 지키는지는 전혀 보지 않는다. --repo에 아무 GitHub 저장소나 넣으면 그대로 $CODEX_HOME/skills/에 복사된다.
• 기여 시점 게이트 없음 — CI·자동 스키마 검증·CONTRIBUTING 체크리스트가 전무하다(5장). README의 "PRs welcome"이 유일한 절차이고, 사실상 사람 리뷰어의 육안 확인이 전부다.
• 실행 시점엔 확인 절차가 없다 — SKILL.md 어디에도 "실행 전 사용자에게 다시 확인하라"는 지시가 없다. 오히려 설계 철학 자체가 "그냥 실행하라"는 쪽이다.
• 권한의 범위가 스킬 단위가 아니라 계정 단위 — Rube MCP·Composio CLI 연결은 "이 스킬에만" 허용되는 게 아니라 연결된 순간부터 그 세션의 모든 스킬이 같은 권한을 공유한다. 즉 무해한 스킬 하나를 설치해 Gmail을 연결해 두면, 이후 설치한 다른(검증되지 않은) 스킬도 같은 Gmail 권한을 함께 쓸 수 있는 구조다.

10이 레포로 공부하는 법 + 내 스킬 만들기

추천 정독 순서

1. template-skill/SKILL.md — 4줄짜리 최소 골격부터 감을 잡는다.
2. meeting-notes-and-actions/SKILL.md — 스크립트 없이 순수 절차 서술만으로 스킬이 성립하는 예.
3. connect-apps/SKILL.md — CLI 위임형 패턴을 보되, "Claude" 잔존 문구를 스스로 찾아보며 왜 문제인지 체감한다(9장 답 확인 전에 먼저 찾아볼 것).
4. mcp-builder/SKILL.md + reference/ 4종 — scripts·reference를 모두 갖춘 "정석" 구조.
5. composio-skills/ 아무 폴더나 하나 — 실행 코드 0줄짜리 최소 위임형이 어떻게 성립하는지 확인.
6. notion-research-documentation/evaluations/ — 스킬을 "합격 기준이 있는 사양"으로 만드는 실험적 패턴.

내 스킬 만들기 — skill-creator가 규정한 6단계

이 레포에 동봉된 skill-creator 스킬은 스킬을 만드는 절차 자체를 스킬로 만들어 놓았다. 핵심 단계만 요약하면:

# 직접 해보는 최소 실습
python3 skill-creator/scripts/init_skill.py my-first-skill \
  --path ./skills-sandbox --resources scripts

# SKILL.md의 [TODO] 부분을 채운 뒤 검증
python3 skill-creator/scripts/quick_validate.py ./skills-sandbox/my-first-skill

# 검증을 통과하면 배포용으로 패키징 (내부에서 검증을 한 번 더 돈다)
python3 skill-creator/scripts/package_skill.py ./skills-sandbox/my-first-skill

실습 아이디어: 본인이 반복적으로 하는 작업(예: "PR 올리기 전에 체크리스트 확인하기", "주간 회고 정리하기")을 하나 골라 위 3단계를 그대로 따라 해본다. 그다음 composio-skills/의 automation 스킬 하나를 골라 스스로 quick_validate.py에 돌리기 전에 어떤 이유로 실패할지 먼저 예측해보면, SKILL.md 스키마가 왜 그렇게 설계됐는지가 체감된다.

11한 줄 정리 + 링크

awesome-codex-skills는 "Codex 스킬 큐레이션 리스트"라는 간판 아래, 사람이 직접 설계한 48개의 실전 워크플로 스킬과 회사 통합 카탈로그를 스킬 포맷으로 찍어낸 832개의 자동생성 커넥터가 공존하는 저장소다 — 그리고 후자는 레포 자신의 검증 도구 기준으로도 100% 비표준이다. SKILL.md라는 파일 포맷 자체는 Claude Code와 사실상 그대로 호환되지만("이식된 흔적"이 레포 안에 직접 남아있다), 설치 경로·배포 방식·확장 필드는 각기 다르며, 그 확장 필드가 정확히 이 레포의 품질 격차가 드러나는 지점이었다.

• GitHub 저장소: github.com/composio-community/awesome-codex-skills (README 내 설치 명령은 구 조직명 ComposioHQ 표기 — 7장 참고)
• 1차 소스: README.md(카테고리·설치법) · skill-creator/SKILL.md+scripts/quick_validate.py(공식 스키마 원본) · skill-installer/scripts/*.py(설치 메커니즘) · composio-skills/*/SKILL.md(자동화 스킬 실물)
• Composio 제품: Composio MCP Gateway · Rube MCP · Composio CLI 문서
• OpenAI 공식 큐레이션: openai/skills 레포의 skills/.curated — list-curated-skills.py가 기본으로 조회하는 대상
• 비교 대상: Claude Code Skills 공식 문서 — 이 레포의 여러 스킬이 실제로 이식해 온 원본 포맷
• 참고 개념: progressive disclosure, YAML frontmatter, Model Context Protocol(MCP), OAuth 위임 인증, awesome list 큐레이션 관행