에이전트 스킬 하나를 Codex CLI와 Claude Code CLI에서 함께 쓸 수 있을까?

가능합니다. 기본 SKILL.md 형식과 참고 파일은 두 CLI에서 함께 쓸 수 있습니다. 다만 Codex는 .agents/skills, Claude Code는 .claude/skills에서 프로젝트 스킬을 찾습니다. 원본 하나를 함께 쓰려면 각자 찾는 경로를 같은 폴더로 연결해야 합니다.

이번 글에서는 Windows의 junction을 이용해 두 경로를 연결하고 직접 확인했습니다. 확인 범위는 name, description, 본문과 참고 파일로 구성한 기본 스킬까지입니다.

스킬 형식은 같아도 탐색 경로는 다릅니다

공식 문서에 따르면 두 CLI 모두 Agent Skills 공개 표준을 따릅니다. 기본 형식은 같지만 프로젝트 스킬을 찾는 위치는 서로 다릅니다.

이를 확인하려고 독립된 Git 프로젝트 폴더 세 개에 같은 테스트 스킬 cross-cli-probe-7f3a를 배치했습니다. 각 스킬의 참고 파일에는 사용자 요청에 없는 확인용 문자열을 넣었습니다. CLI가 이 문자열을 답하면 스킬과 참고 파일을 읽은 것으로 판단했습니다.

한쪽 경로에만 스킬을 두면 다른 CLI에서는 보이지 않습니다. 같은 파일을 양쪽에 복사할 수도 있지만, 스킬을 고칠 때마다 두 복사본을 함께 관리해야 합니다.

Windows에서 스킬 원본 하나로 관리하기

이번 테스트에서는 .agents/skills/<스킬이름>을 실제 스킬 폴더로 두고, .claude/skills/<스킬이름>에 원본으로 이어지는 junction을 만들었습니다. junction은 두 CLI의 동기화 기능이 아니라 Windows 파일 시스템이 제공하는 폴더 연결 기능입니다.

실제로 만들 때는 <스킬이름> 대신 article-review처럼 스킬을 나타내는 고유한 이름을 넣습니다.

프로젝트 폴더/
├─ .agents/skills/<스킬이름>/     ← 실제 스킬 원본
│  ├─ SKILL.md
│  └─ references/
│
└─ .claude/skills/<스킬이름>/     ← 원본으로 이어지는 junction

Codex와 Claude Code는 서로 다른 경로로 들어가지만, 마지막에는 같은 SKILL.md와 참고 파일을 읽습니다.

공통 스킬 생성을 요청하기

폴더와 파일을 직접 만들지 않고 Codex나 Claude Code에 다음과 같이 요청할 수 있습니다. <스킬이름>과 작업 목적은 실제 내용에 맞게 바꿉니다.

이 프로젝트에서 Codex CLI와 Claude Code CLI가 함께 사용할 스킬을 만들어줘.

스킬 이름: <스킬이름>
스킬이 할 일: <여기에 작업 목적 입력>

다음 조건을 지켜줘.

1. `.agents/skills/<스킬이름>`을 실제 스킬 폴더로 사용한다.
2. `SKILL.md`에는 두 CLI가 공통으로 이해할 수 있는 `name`, `description`과 작업 지침만 작성한다. Codex나 Claude Code 전용 frontmatter, hooks, 권한 설정, 실행 스크립트는 넣지 않는다.
3. 참고 파일은 실제 스킬 폴더 안에 두고 상대 경로로 연결한다.
4. `.claude/skills/<스킬이름>`에는 복사본 대신 실제 스킬 폴더로 이어지는 Windows junction을 만든다.
5. 기존 폴더나 파일은 덮어쓰거나 삭제하지 말고 현재 상태를 먼저 보고한다.
6. 작업이 끝나면 두 경로가 같은 `SKILL.md`를 가리키는지 확인하고, 각 CLI에서 스킬을 호출하는 방법을 알려준다.

파일 쓰기와 junction 생성이 허용된 세션에서 사용해야 합니다. 읽기 전용 모드에서는 구조를 설명할 수 있지만 실제 파일과 junction은 만들 수 없습니다.

호출 방법은 다릅니다

경로를 연결해도 스킬을 직접 부르는 문법은 서로 다릅니다.

스킬 이름이 article-review라면 Codex에서는 $article-review, Claude Code에서는 /article-review로 부릅니다.

두 CLI 모두 description을 보고 필요한 스킬을 자동으로 선택할 수 있습니다. 이번 테스트에서는 이름을 직접 쓰지 않은 요청도 양쪽에서 한 차례씩 성공했습니다. 다만 모델의 판단에 따라 결과가 달라질 수 있으므로, 확실하게 사용하려면 스킬 이름을 직접 지정하는 편이 낫습니다.

확인 범위와 테스트 환경

이번에 확인한 것은 name, description, 본문과 참고 파일로 구성한 기본 스킬입니다. 도구별 frontmatter와 metadata, hooks, 권한 설정, 실행 스크립트는 시험하지 않았습니다. 이런 도구별 기능이 필요한 스킬은 원본 하나를 공유하더라도 두 CLI에서 같은 방식으로 동작하지 않을 수 있습니다. 이 경우 각 CLI에 맞는 별도 구성이 필요할 수 있으므로, 실제 사용 전에 호환 여부를 따로 검증해야 합니다.

직접 확인한 연결 방식도 Windows junction뿐입니다. 두 CLI의 공식 문서는 symlink로 연결한 스킬 폴더를 지원한다고 설명하지만, macOS와 Linux에서는 직접 실행하지 않았습니다.

참고 문서

• Codex Skills 공식 문서
• Claude Code Skills 공식 문서