왜 Codex Skills와 Claude Code Skills에서 동일한 Skill.md 포맷을 사용하는가
요약
OpenAI Codex와 Claude Code에서 사용하는 SKILL.md 포맷의 공통점과 차이점을 분석합니다. 두 도구 간의 호환성을 유지하면서 효율적으로 스킬을 관리하고 이식하는 전략을 제시합니다.
핵심 포인트
- name과 description 필드는 Codex와 Claude Code 간 완전 호환됨
- allowed-tools 필드를 생략하면 두 도구 모두에서 작동하는 공통 스킬로 활용 가능
- 복잡한 워크플로우나 권한 제어가 필요한 경우 Claude Code 전용 확장 스킬로 관리 권장
- 효율적인 스킬 실행을 위해 description에 사용 조건과 인자 명시가 중요함
이 기사는 playpark Blog에서 전재되었습니다.
- Skill.md 포맷의 사양과 각 필드의 역할
- Codex와 Claude Code에서 동일한 포맷을 채택하고 있는 설계 이유
- 양쪽 모두에 대응할 수 있는 스킬 작성 판단 기준
AI 코딩 툴에서 스킬(재사용 가능한 절차 정의)을 사용하기 시작하면, 툴이 늘어남에 따라 "이 스킬, 다른 툴에서도 작동하지 않을까?"라는 의문이 생긴다.
OpenAI Codex와 Claude Code는 둘 다 SKILL.md를 중심으로 한 스킬 기능을 가지고 있지만, 필드 구성이나 기능의 차이가 있어 "어디까지 공통화할 수 있는가"를 판단하기 어렵다.
특히 곤란한 경우는 Codex용으로 작성한 스킬을 Claude Code에서 유용하려고 할 때, 또는 그 반대 방향으로 이식하려고 할 때다.
스킬을 어떻게 관리할지에 대한 선택지를 정리한다.
| 접근 방식 | 장점 | 단점 |
|---|---|---|
| 툴마다 별도 포맷으로 작성 | 각 툴의 기능을 최대한 활용할 수 있음 | 유지보수 비용이 2배가 됨 |
| ... |
결론적으로 "공통 포맷으로 작성하고, 확장은 별도로 관리"하는 것이 가장 현실적이다. 그 전제로 포맷 사양을 이해할 필요가 있다.
Codex와 Claude Code는 SKILL.md의 필수 필드가 공통적이다.
---
name: my-awesome-skill
description: |
...
name과 description 두 필드만이 필수이며, 이 부분은 두 툴에서 완전히 호환성이 있다.
Claude Code 고유 기능으로서 allowed-tools가 있지만, 이는 생략 가능하다. 생략하면 Codex에서도 그대로 작동한다.
| 필드 | Codex | Claude Code | 호환성 |
|---|---|---|---|
name | 필수 | 필수 | ✅ 완전 호환 |
description | 필수 | 필수 | ✅ 완전 호환 |
allowed-tools | 미지원 | 옵션 | ⚠️ 생략 시 호환 |
| 스킬 연쇄 | 제한적 | Skill: other-skill | ⚠️ Claude Code 고유 |
이 구조로부터 "allowed-tools를 생략한 공통 스킬을 기반으로 한다"는 판단이 자연스럽게 도출된다.
---
name: lint-and-format
description: |
...
# Lint & Format
## Step 1: Run linter
```bash
npm run lint
Step 2: Auto-fix
npm run lint -- --fix
Step 3: Report
Report the results:
- Files checked
...
`allowed-tools`를 생략하고 있기 때문에, Codex에서도 Claude Code에서도 작동한다.
`allowed-tools`(권한의 최소화)나 스킬 연쇄가 필요한 상황에서는 확장 스킬을 별도 디렉토리에서 관리한다.
skills/
├── lint-and-format/ ← 공통 스킬 (양쪽 툴에서 작동)
│ └── SKILL.md
...
스킬을 작성할 때의 판단 기준은 다음과 같다.
**공통 포맷(`allowed-tools` 생략)으로 작성하는 케이스:**
- Codex / Claude Code 양쪽 모두에서 사용하고 싶은 스킬
- 팀에서 공유·배포하고 싶은 스킬 (Codex 공식 카탈로그 등록도 염두에 두는 경우)
**Claude Code 고유 구문을 사용하는 케이스:**
- 프로덕션 배포 등, 권한을 최소화하고 싶은 스킬 (`allowed-tools`를 명시)
- 여러 스킬을 연쇄시키는 복잡한 워크플로우 (`Skill: other-skill` 형식)
`description` 작성 방식이 스킬 실행에 가장 직결되므로, `Use when:`과 `Accepts args:`를 명시하는 것이 첫 번째 우선순위다.
이 기사에서는 Codex / Claude Code 공통의 Skill.md 포맷 사양과 설계 판단을 해설했습니다.
**Skill.md 작성 가이드 — Codex Skills와 Claude Code Skills의 차이와 설계 패턴**에서는 더욱:
- 도구 횡단 스킬 설계의 3가지 패턴(호환성 중시·플랫폼별 확장·참조 파일 공유)의 상세 비교
- 커밋 메시지 생성 스킬의 완전 구현 예시 (Conventional Commits 대응)
- Codex 공식 스킬 카탈로그 `openai/skills` 의 클론 및 활용 방법
을 다룹니다.
**playpark LLC** - 업무 자동화·AI 활용·Web 개발
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기