Codex와 Claude Code에서의 skill 정의
두 도구 모두 동일한 개방형 표준을 기반으로 구축되었습니다. OpenAI의 문서에는 "Skills는 개방형 agent skills 표준을 기반으로 합니다"라고 명시되어 있으며, Anthropic은 "Claude Code skills는 여러 AI 도구에서 작동하는 Agent Skills 개방형 표준을 따릅니다"라고 설명합니다.
Codex에서 OpenAI가 설명하는 구조는 다음과 같습니다: "skill은 SKILL.md 파일과 선택적인 스크립트 및 참조가 포함된 디렉토리입니다. SKILL.md 파일에는 반드시 name과 description이 포함되어야 합니다." skill 폴더에는 scripts/, references/, assets/ 및 agents/openai.yaml 파일도 포함될 수 있습니다.
Claude Code에서도 skill은 SKILL.md 파일이 포함된 폴더입니다. --- 표시 사이의 frontmatter는 Claude에게 언제 이 skill을 사용할지 알려주며, 그 아래의 markdown은 지침을 담고 있습니다.
따라서 skill의 핵심인 폴더, SKILL.md 파일, name, description 및 지침은 두 도구 모두에서 동일한 형식입니다. 이는 마이그레이션에 있어 좋은 소식입니다. 대부분의 작업은 위치 설정과 각 도구가 표준 위에 추가하는 몇 가지 요소에 관한 것입니다.
각 도구가 skills를 찾는 위치
이 섹션은 서두의 예시를 설명해 줍니다.
Codex는 저장소, 사용자, 관리자 및 시스템 위치에서 skills를 읽습니다:
- 저장소(Repository): 현재 작업 디렉토리 및 저장소 루트까지의 모든 폴더에 있는
.agents/skills. - 사용자(User): 모든 저장소에 적용되는 skills를 위한
$HOME/.agents/skills. - 관리자(Admin): 머신에서 공유되는
/etc/codex/skills. - 시스템(System):
skill-creator및skill-installer와 같이 Codex에 내장된 skills.
Claude Code는 다음 위치에서 skills를 읽습니다:
- 프로젝트(Project): 저장소 내의
.claude/skills/<skill-name>/SKILL.md. - 개인(Personal): 해당 머신의 모든 프로젝트를 위한
~/.claude/skills/<skill-name>/SKILL.md. - 엔터프라이즈(Enterprise): 조직에서 배포하는 관리형 설정 디렉토리.
- 플러그인(Plugins): 활성화한 플러그인에 포함된 skills.
두 도구의 문서 모두 상대방의 폴더를 나열하지 않습니다. 따라서 .agents/skills에 있는 skill은 .claude/skills/로 옮기기 전까지는 Claude Code에 나타나지 않으며, 그 반대의 경우도 마찬가지입니다.
모노레포(monorepos)의 경우 한 가지 차이점이 더 있습니다. Anthropic의 문서에 따르면 Claude Code는 "실행한 디렉토리와 저장소 루트까지의 모든 상위 디렉토리에 있는 .claude/skills/에서 프로젝트 skills를 로드합니다." 또한 "실행 위치보다 하위에 있는 .claude/skills/ 디렉토리의 skills는 시작 시 로드되지 않습니다"라고 덧붙였습니다. 이러한 기술들은 Claude가 해당 하위 디렉토리의 파일을 처음 읽거나 편집할 때 로드됩니다.
변경 없이 그대로 유지되는 항목
두 도구 모두 동일한 표준을 따르므로, 가장 많이 작성하는 부분은 그대로 유지됩니다:
- 폴더 이름 및
SKILL.md. 구조가 동일합니다. name및description. 두 도구 모두 설명을 사용하여 skill 적용 시점을 결정합니다.- 지침(Instructions). markdown 본문은 두 도구 모두 따를 수 있는 일반 텍스트입니다.
- 지원 파일. skill 폴더 내부의 스크립트, 참조 및 템플릿도 함께 이동합니다.
이동 후에는 설명을 다시 한번 살펴볼 필요가 있습니다. Codex에 대한 OpenAI의 조언은 "명확한 범위와 경계를 가진 간결한 설명을 작성하라"는 것입니다. Anthropic의 문서는 Claude Code에 대해 제한 사항을 추가합니다: "컨텍스트 사용량을 줄이기 위해 skill 목록에서 description과 when_to_use 텍스트의 합계가 1,536자에서 잘립니다." Codex에서는 괜찮았던 긴 설명이 Claude Code의 목록에서는 잘릴 수 있습니다.
일대일로 매칭되지 않는 항목
Codex skill의 몇몇 부분은 OpenAI 제품에 특화되어 있습니다.
agents/openai.yaml. OpenAI는 이 파일의 목적을 다음과 같이 설명합니다: "ChatGPT 데스크톱 앱에서 UI 메타데이터를 구성하고, 호출 정책을 설정하며, skill 사용 시 더 원활한 경험을 위해 도구 종속성을 선언하려면 agents/openai.yaml을 추가하세요." 여기에는 표시 이름, 아이콘, 암시적 호출 정책, MCP 서버와 같은 종속성이 포함됩니다. Claude Code의 skill 문서에는 이 파일을 읽는다는 설명이 없습니다.
호출 정책(Invocation policy). Codex에서는 해당 파일의 policy 섹션에 allow_implicit_invocation과 같은 설정이 포함됩니다. Claude Code는 동일한 개념을 위해 자체 frontmatter 필드인 disable-model-invocation을 사용합니다. 문서에 따르면: "Claude가 이 skill을 자동으로 로드하지 못하게 하려면 true로 설정하세요." Codex에서 skill의 암시적 호출을 꺼두었다면, 이동 후 SKILL.md에서 이 필드를 설정하세요.
도구 종속성(Tool dependencies). Codex skill이 openai.yaml에서 MCP 서버를 선언하는 경우, Claude Code에서는 해당 서버를 별도로 구성해야 합니다. 서버 없이도 skill의 지침이 작동하는지 확인하거나, Claude Code에 서버를 추가하세요.
skill 호출 방법. Codex CLI 또는 IDE 확장 프로그램에서 OpenAI는 "/skills를 실행하거나 $를 입력하여 skill을 언급하라"고 안내합니다. Claude Code에서는 /skill-name을 사용하여 직접 skill을 호출합니다.
중복된 이름. OpenAI는 다음과 같이 언급합니다: "두 skill이 동일한 name을 공유하는 경우, Codex는 이를 병합하지 않으며 둘 다 skill 선택기에 나타날 수 있습니다." Claude Code 역시 동일한 이름을 가진 중첩된 skills를 모두 사용할 수 있게 유지합니다. skill 세트를 결합하는 경우, 사용하기 전에 충돌하는 이름이 있다면 변경하세요.
방법 1: /import 사용
Claude Code에는 이를 위한 명령어가 있습니다. 명령어 참조에 따르면 /import는 머신에 있는 OpenAI Codex 및 기타 코딩 에이전트의 구성을 Claude Code로 가져오는 방법으로, "지침 파일, MCP 서버, 명령어, subagents 및 skills를 포함"합니다.
더 안전하게 실행하기 위한 두 가지 옵션이 있습니다:
- 먼저 미리보기. 참조 문서에 따르면: "아무것도 기록하지 않고 미리 보려면
--dry-run을 추가하고, 대화형 선택기를 건너뛰려면--yes를 추가하세요." - 터미널에서 실행.
claude import는 동일한 옵션으로/import를 실행하는 대화형 세션을 시작합니다.
새 프로젝트를 설정할 때, /init 실행 중 Codex 구성이 발견되면 /import를 통해 이를 가져올지 묻는 메시지가 표시됩니다.
실행 전 Anthropic의 memory 문서에서 읽어볼 만한 세부 사항이 하나 있습니다. /import는 "AGENTS.md와 같은 지침 파일의 일회성 복사본을 일치하는 CLAUDE.md에 추가하고 MCP 서버, 명령어, subagents 및 skills를 가져옵니다."
핵심 단어는 일회성 복사본입니다. 가져오기 후에는 AGENTS.md와 CLAUDE.md가 별개의 파일이 됩니다. 다음 달에 AGENTS.md에서 규칙을 변경하더라도, CLAUDE.md를 직접 업데이트하거나 가져오기를 다시 실행하지 않는 한 Claude Code는 이를 인식하지 못합니다. skills에도 동일한 논리가 적용됩니다. skill이 복사되면 Codex 버전을 편집해도 Claude Code 버전은 변경되지 않습니다.
문서에는 /import가 agents/openai.yaml 또는 기타 OpenAI 전용 메타데이터를 어떻게 처리하는지 설명되어 있지 않습니다. 가져오기 후에는 Claude Code에서 각 skill을 열어 frontmatter와 지원 파일을 확인하세요.
방법 2: 심볼릭 링크(symlink)로 단일 복사본 유지
두 도구를 모두 계속 사용할 계획이라면, 모든 skill의 복사본 두 개를 관리하는 것은 동기화 문제를 야기할 수 있습니다. 두 도구 모두 심볼릭 링크된 skill 폴더를 지원하므로 하나의 소스를 유지할 수 있습니다.
OpenAI의 문서에 따르면: "Codex는 심볼릭 링크된 skill 폴더를 지원하며 해당 위치를 스캔할 때 심볼릭 링크 대상을 따릅니다."
Anthropic은 엔터프라이즈, 개인 또는 프로젝트 위치의 skill 항목이 디스크의 다른 위치에 있는 디렉토리에 대한 심볼릭 링크일 수 있다고 설명합니다. "Claude Code는 대상에서 SKILL.md를 읽으며, 여러 위치가 동일한 대상을 가리키더라도 skill을 한 번만 로드합니다."
간단한 레이아웃은 각 skill을 하나의 실제 폴더에 보관하고 다른 도구의 위치가 그곳을 가리키도록 하는 것입니다:
- Codex가 찾을 수 있도록
.agents/skills/release-notes/에 skill을 보관합니다. - 해당 폴더를 가리키는 심볼릭 링크로
.claude/skills/release-notes를 추가합니다.
이렇게 하면 하나의 SKILL.md를 편집해도 두 도구 모두에 반영됩니다. Codex는 "skill 변경 사항을 자동으로 감지"하며, 업데이트가 나타나지 않으면 Codex를 재시작하라고 문서에 명시되어 있습니다. Claude Code에서 편집 내용이 보이지 않으면 새 세션을 시작하세요.
두 가지 주의 사항이 있습니다. 심볼릭 링크된 skill은 하나의 설명을 공유하므로 두 도구의 목록에서 모두 잘 작동하도록 작성해야 합니다. 또한 disable-model-invocation과 같은 Claude Code 전용 frontmatter가 Codex도 읽는 파일에 포함되게 되므로, 이를 추가한 후에도 Codex가 skill을 여전히 잘 로드하는지 테스트해야 합니다.
개인용 skills
저장소가 아닌 개인적으로 보관하는 skills에도 동일한 선택지가 적용됩니다. Codex는 $HOME/.agents/skills에서 개인 skills를 읽습니다. Claude Code는 ~/.claude/skills/에서 읽습니다. 이를 복사하거나, /import를 실행하거나, 개별 skill 폴더를 심볼릭 링크할 수 있습니다.
Anthropic의 문서는 개인 위치에서 하나의 폴더 이름을 예약해 두었습니다. Claude Code는 claude.ai 계정에서 다운로드한 skills를 위해 ~/.claude/skills/synced/를 사용하므로, 본인의 skill 이름을 synced로 짓지 마세요.
반대 방향으로 이동해 본 적이 있다면, 플러그인에 대해서도 동일한 위치 및 패키징 문제가 발생했을 것입니다. 저희는 Claude Code 플러그인을 Codex로 마이그레이션하기 가이드에서 해당 방향을 다룬 바 있습니다.
시작 전 확인 사항
- 실제로 사용하는 skills. 마이그레이션은 아무도 호출하지 않는 skills를 정리하기 좋은 시기입니다.
- OpenAI 전용 메타데이터에 의존하는 skills. 호출 정책이나 MCP 종속성이 있는
agents/openai.yaml파일을 확인하세요. - Codex를 계속 사용할지 여부. 그렇다면 심볼릭 링크를 계획하세요. 아니라면 복사나
/import로 충분합니다. - 이름 충돌. 두 도구 간의 skill 이름을 비교하세요.
AGENTS.md파일. Claude Code가 복사본을 읽게 할지, 아니면 두 파일을 모두 유지 관리할지 결정하세요.
사람들이 흔히 하는 실수
.agents/skills를 저장소에 복사하고 Claude Code가 찾기를 기대하는 것. Claude Code는 .claude/skills/를 읽습니다.
/import가 파일을 계속 동기화한다고 가정하는 것. 이는 지침 파일의 일회성 복사본을 추가할 뿐입니다.
openai.yaml 설정이 그대로 전달될 것이라 믿는 것. skill이 자동으로 실행되지 않아야 한다면 Claude Code에서 disable-model-invocation을 설정하세요.
긴 설명을 그대로 두는 것. Claude Code는 목록에서 결합된 설명 텍스트를 자릅니다.
동일한 skill의 복사본 두 개를 유지하는 것. 시간이 지나면 내용이 달라집니다. 두 도구를 모두 사용한다면 심볼릭 링크를 사용하세요.
수동 마이그레이션 단계
1단계: Codex skills 목록 작성
저장소, $HOME/.agents/skills 및 사용 중인 관리자 위치에 있는 skills를 수집합니다.
2단계: 가져오기 미리보기
Claude Code에서 /import를 --dry-run 옵션과 함께 실행하여 무엇이 이동될지 확인합니다.
3단계: 가져오기 또는 링크 연결
가져오기를 실행하거나, 한 곳에 보관할 skill 폴더를 .claude/skills/에서 심볼릭 링크로 연결합니다.
4단계: Frontmatter 조정
Codex skill에서 암시적 호출이 꺼져 있던 곳에 disable-model-invocation을 추가하고, 긴 설명을 짧게 수정합니다.
5단계: 종속성 재연결
openai.yaml을 통해 skill이 의존했던 모든 MCP 서버를 구성합니다.
6단계: 이름으로 각 skill 테스트
/skill-name으로 각 skill을 호출한 다음, 자동으로 트리거되어야 하는 요청을 시도해 봅니다.
더 나은 방법: skill 뒤에 숨겨진 이유를 한 곳에 보관하기
skill은 작업을 수행하는 방법을 캡처합니다. 릴리스 체크리스트에 수동 단계가 있는 이유, 어떤 마이그레이션 패턴이 이전 패턴을 대체했는지, 또는 테스트 분류 skill이 절대 건드리지 말아야 할 것과 같은 그 뒤에 숨겨진 이유는 프로젝트 컨텍스트입니다. 도구 간에 skills를 이동할 때 지침은 따라오지만, 왜 그렇게 작성되었는지에 대한 역사는 누군가의 기억 속에만 남을 수 있습니다.
MemoryLake는 결정, 관습, 워크플로우 뒤에 숨겨진 이유와 같은 프로젝트 컨텍스트를 위한 memory 레이어입니다. 이를 한 곳에서 유지 관리하고 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트에서 사용할 수 있습니다.
사용자는 자신의 언어로 직접 항목을 작성합니다. skill 폴더, SKILL.md 파일, AGENTS.md 또는 CLAUDE.md 파일, Codex 또는 Claude Code 설정, 또는 어떤 벤더의 저장소에서도 데이터를 읽거나 쓰거나 삭제하지 않습니다. Skills와 /import는 OpenAI와 Anthropic이 설명하는 방식 그대로 작동합니다.
1단계: API 키 생성
로그인하고 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하세요.

2단계: 첫 번째 memories 업로드
수동 마이그레이션의 1단계에서 나열한 skills부터 시작하세요. 각 skill에 대해 그것이 왜 존재하는지, 무엇을 변경해서는 안 되는지 적으세요. 항목당 하나의 skill을 할당합니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결하세요. 어떤 도구가 skill을 실행하든 동일한 근거를 활용할 수 있습니다.

실제 작업에서의 변화
첫 번째 차이점은 더 깔끔한 마이그레이션입니다. 역사는 다른 곳에 보관되므로 skills는 지침 위주로 간소화될 수 있습니다.
두 번째는 도구 간의 일관성입니다. Claude Code와 Codex 모두에서 동일한 추론을 사용할 수 있습니다.
세 번째는 더 쉬운 업데이트입니다. 관습이 바뀌면 하나의 항목만 업데이트하면 되고, 이를 따르는 skill도 함께 업데이트됩니다.
Codex skills를 Claude Code로 옮기기 위한 모범 사례
Claude Code가 찾는 위치에 skills를 두세요. .claude/skills/ 또는 ~/.claude/skills/를 사용하세요.
가져오기 전에 미리 확인하세요. --dry-run을 사용하세요.
일회성 복사본임을 기억하세요. 지침 파일은 /import 후에 동기화 상태를 유지하지 않습니다.
두 도구를 모두 사용한다면 심볼릭 링크를 사용하세요. 폴더 하나로 관리해야 내용이 어긋나지 않습니다.
호출 정책을 변환하세요. Claude Code에서는 disable-model-invocation을 사용하세요.
설명을 짧게 유지하세요. 두 도구 모두 설명을 기반으로 매칭하며, Claude Code는 긴 설명을 자릅니다.
이름과 요청으로 테스트하세요. 수동 및 자동 호출을 모두 확인하세요.
결론
Codex와 Claude Code는 개방형 agent skills 표준을 기반으로 구축된 동일한 skill 형식을 사용하므로, skill 폴더, SKILL.md, 이름, 설명 및 지침은 변경 없이 그대로 유지됩니다. 차이점은 각 도구가 검색하는 위치입니다. Codex는 .agents/skills를, Claude Code는 .claude/skills/를 확인합니다. agents/openai.yaml에 있는 Codex 전용 메타데이터는 disable-model-invocation과 같은 Claude Code의 대응 설정이 필요합니다.
/import를 사용하여 skills를 가져올 수 있으며, 이는 AGENTS.md와 같은 지침 파일의 일회성 복사본도 함께 추가합니다. 또는 두 도구가 모두 따르는 심볼릭 링크를 사용하여 단일 복사본을 유지할 수도 있습니다. 어떤 방식을 선택하든 이동 후 각 skill을 점검하고, 두 도구 모두에서 사용할 수 있는 곳에 skill 뒤에 숨겨진 이유를 보관하세요.