Claude Code와 Codex CLI의 Skill 재사용 아키텍처

Claude Code와 Codex CLI를 같이 쓰면 같은 스킬을 두 곳에 따로 두기 쉽고, 그러면 한쪽만 고쳐져 내용이 갈라진다. 이 글은 한 대의 Mac에서 두 런타임이 스킬을 실제로 어떻게 나눠 쓰는지 폴더 구조부터 확인하고, 원본을 한 곳에 두는 법, 한 런타임이 다른 런타임을 부르는 법, 런타임마다 따로 둬야 하는 것을 정리한다.

공방 벽의 공구판에서 두 장인이 양쪽에서 같은 공구를 꺼내는 장면

한눈에 보기

아래 숫자와 경로는 2026년 11월 2일 이 Mac의 실제 폴더에서 센 것이다.

위치	읽는 쪽	항목 수	원본 여부
`~/.agents/skills`	직접 읽는 런타임 없음 (설치 도구가 관리)	35개	원본. `.skill-lock.json`에 출처 기록
`~/.claude/skills`	Claude Code	224개 (링크 8개)	대부분 원본, 8개는 `~/.agents`를 가리킴
`~/.codex/skills`	Codex CLI	24개 (링크 4개)	일부 원본, 4개는 `~/.claude`를 가리킴
`~/.codex/AGENTS.md`	Codex CLI	1개	Codex 전용 운영 규칙

Claude Code는 ~/.claude/skills를, Codex CLI는 ~/.codex/skills를 읽고, 두 폴더의 링크가 각각 ~/.agents/skills와 ~/.claude/skills를 가리키며, Claude 스킬의 스크립트가 codex exec로 Codex CLI를 부르는 구조

스킬 하나를 어떻게 설계하는지는 Claude Code Skill 설계부터 자동 실행까지 실전 가이드에, 스킬과 MCP·Hook의 차이는 MCP와 Skill, Hook의 차이 및 적용 기준에 정리했다. 이 글은 이미 만든 스킬을 여러 런타임에서 다시 쓰는 구조만 다룬다.

두 런타임이 공유하는 것: 스킬 폴더 형식

두 런타임의 스킬은 같은 모양이다. 폴더 하나에 SKILL.md가 있고, 맨 위 frontmatter에 name과 description이 있다.

---
name: blog-tech-article
description: 주제를 받아 용데브 블로그(my-blog)의 '기술 아티클' 게시판에 한국어 기술 글을 써서 발행한다. …
---

Codex 쪽 ~/.codex/skills/web-perf/SKILL.md도 같은 두 칸으로 시작한다. 그래서 폴더를 그대로 옮기거나 링크를 걸면 두 런타임 모두 스킬로 읽는다.

같이 쓸 수 있는 것

SKILL.md 본문의 절차와 절대 규칙
scripts/의 셸·Python·Node 스크립트 (런타임이 아니라 OS가 실행하므로)
references/의 참고 문서, CHANGELOG.md

같이 쓰기 어려운 것

본문에 적힌 런타임 전용 도구 이름. 예를 들어 Claude Code의 Read, Agent, Skill 도구를 부르라고 적은 절차는 Codex에서 그대로 따를 수 없다.
권한·Hook 설정. 이건 스킬이 아니라 각 런타임 설정 파일에 있다.

원본은 한 곳, 나머지는 심볼릭 링크

이 Mac에서 스킬 원본이 있는 곳은 세 군데다. 각자 쓰는 방식이 다르다.

~/.agents/skills: 설치 도구가 관리하는 원본

GitHub에서 받아 설치한 스킬이 여기 있다. ~/.agents/.skill-lock.json에 스킬마다 source(예: vercel-labs/skills), sourceUrl, skillPath, skillFolderHash, 설치·갱신 시각이 적혀 있다. 같은 파일의 lastSelectedAgents에는 claude-code, codex, antigravity-cli, cursor 등 14개 런타임이 들어 있다. 설치 도구가 이 목록에 있는 런타임 폴더로 링크를 거는 구조로 보인다(동작 방식은 파일 내용으로 추정한 것이다).

~/.claude/skills/orchestration     -> ../../.agents/skills/orchestration
~/.claude/skills/karpathy-guidelines -> ../../.agents/skills/karpathy-guidelines
~/.claude/skills/ego-browser       -> /Users/yongyeonkim/.local/share/ego/ego-skills

ego-browser처럼 도구 제작사가 자기 설치 폴더에 스킬을 같이 넣어 두고 링크로 연결하는 경우도 있다. 도구를 갱신하면 스킬도 같이 바뀐다.

~/.claude/skills: 직접 만든 스킬의 원본

블로그·영상 파이프라인처럼 직접 만든 스킬은 여기에 원본이 있다. Codex에서도 쓰고 싶은 스킬은 Codex 쪽에서 이 폴더를 가리킨다.

~/.codex/skills/supanova-design-engine -> ../../.claude/skills/supanova-design-engine

링크를 거는 이유

복사하면 갈라진다. 이 Mac에서 zod 스킬은 ~/.codex/skills/zod와 ~/.agents/skills/zod 두 곳에 복사본으로 있다. Codex 쪽에는 SKILL.md 하나만 있고, ~/.agents 쪽에는 references/, rules/, AGENTS.md까지 있으며 SKILL.md 내용도 다르다. 어느 쪽이 최신인지 파일만 보고는 알 수 없다.

한 런타임이 다른 런타임을 부르기

스킬을 공유하는 두 번째 방법은 폴더가 아니라 실행을 공유하는 것이다. Claude Code 스킬의 스크립트가 Codex CLI를 직접 부른다.

codex exec를 부르는 Claude 스킬 스크립트는 4개다.

blog-tech-article/scripts/gen_illustration.sh: 블로그 대표 삽화
youtube-thumbnail/scripts/thumbnail.sh: 유튜브 썸네일
topic-video-youtube/scripts/gen_images.sh, gen_elements.sh: 영상 장면 그림

Claude Code가 글과 절차를 맡고, 그림은 Codex의 내장 image_gen 도구가 그린다. 각 런타임이 잘하는 일만 맡는 셈이다.

codex exec --skip-git-repo-check --sandbox workspace-write \
  "Use the built-in image_gen tool. Generate exactly one wide landscape 16:9 image, then save it as ./hero.png ..." \
  < /dev/null > codex-hero.log 2>&1 || true

위 명령은 thumbnail.sh와 gen_illustration.sh에서 실제로 겪은 일을 한데 모은 형태다.

< /dev/null: thumbnail.sh의 주석대로, 표준 입력을 닫지 않으면 codex exec가 입력을 기다리며 멈춘다.
|| true와 결과 파일 확인: 여러 장을 한 명령에 ;로 이어 돌렸더니 사용량 한도로 실패한 것이 종료 코드에 드러나지 않았다. 그래서 hero.png가 생겼는지로 성공을 판단한다.
로그 파일: 실패 원인(You've hit your usage limit)은 로그에만 남는다.

부르는 쪽이 막혔을 때: 대체 순서

다른 런타임을 부르면 그 런타임의 한도와 장애까지 같이 떠안는다. 2026년 11월 2일 Codex가 사용량 한도에 걸려 삽화 4장을 못 그렸고, 그 뒤 gen_illustration.sh에 대체 순서를 넣었다.

순서	도구	넘어가는 조건	비용
1	Codex CLI `image_gen`	한도 또는 그림 없음	구독 한도 안
2	Antigravity CLI(`agy`)	5분 안에 그림 없음	구독 한도 안
3	Kling (MCP)	없음, 마지막	장당 2크레딧

Kling은 MCP 도구라서 셸 스크립트가 부를 수 없다. 그래서 스크립트는 1·2를 시도한 뒤 종료 코드 3과 KLING_NEEDED를 내고, 3번은 Claude Code가 MCP로 처리한다. 스크립트가 할 수 있는 일과 런타임만 할 수 있는 일을 종료 코드로 나눈 것이다.

agy -p는 그림이 끝나기 전에 답을 돌려주고, 그림은 ~/.gemini/antigravity-cli/brain/<대화>/에 저장된다. 그래서 스크립트가 그 폴더에 새 파일이 생길 때까지 기다렸다가 가져온다. 다른 런타임의 출력 위치와 완료 시점은 직접 실행해 보고 정해야 한다.

권한은 런타임마다 따로

스크립트는 공유해도 권한은 공유되지 않는다.

Claude Code는 다른 에이전트를 띄우는 명령을 자동 모드에서 막았다. agy를 직접 실행하자 Create Unsafe Agents 사유로 두 번 거부됐다.
그래서 agy 전체가 아니라 그림 스크립트 하나만 허용 목록에 넣었다. 프롬프트가 스크립트 안에 고정돼 있어서, 허용 범위가 "그림 한 장 그리기"로 좁아진다. 이 규칙을 넣은 뒤 같은 스크립트로 삽화 네 장을 그렸고, Codex가 사용량 한도로 넘어간 자리를 agy가 막힘 없이 이어받았다. 이 글의 대표 삽화도 그렇게 그린 것이다.

"permissions": {
  "allow": [
    "Bash(~/.claude/skills/blog-tech-article/scripts/gen_illustration.sh:*)"
  ]
}

Codex 쪽 운영 규칙은 ~/.codex/AGENTS.md에 있다. "사용 가능한 Skill이 있음에도 사용하지 않으면 정책 위반"처럼 Codex에게만 적용되는 규칙이라 Claude Code 스킬에 섞지 않는다.

런타임 전용으로 남길 것

무엇	어디에	같이 쓰면 생기는 일
스킬 절차·스크립트	원본 폴더 하나 + 링크	(같이 써야 한다)
런타임 도구 이름이 들어간 절차	그 런타임 스킬 본문	다른 런타임이 없는 도구를 찾다 멈춤
권한 허용 목록	`~/.claude/settings.json` 등	한쪽 허용이 다른 쪽 위험이 됨
운영 규칙	`~/.codex/AGENTS.md`, `CLAUDE.md`	서로 다른 강제 규칙이 충돌
설치 출처 기록	`~/.agents/.skill-lock.json`	갱신할 때 어디서 받았는지 모름

여러 에이전트가 같은 산출물을 나눠 만들 때의 검수 구조는 Maker–Checker Loop로 AI Agent 결과물 검증하기에, 스킬을 묶어 프로젝트를 찍어 내는 구조는 한 줄 프롬프트로 프로젝트를 생성하는 Project Factory 설계에 있다.

자주 하는 실수

스킬 폴더를 복사해서 나눠 준다. 한쪽만 고쳐져 zod처럼 두 벌이 갈라진다. 링크를 건다.
다른 런타임의 종료 코드를 믿는다. 한도에 걸려도 성공처럼 끝날 수 있다. 결과 파일이 생겼는지로 판단한다.
표준 입력을 열어 둔다. codex exec가 입력을 기다리며 멈춘다. < /dev/null을 붙인다.
에이전트 CLI 전체를 허용 목록에 넣는다. 아무 프롬프트나 보낼 수 있게 된다. 프롬프트가 고정된 스크립트만 허용한다.
런타임 전용 규칙을 공유 스킬에 적는다. 다른 런타임이 따를 수 없는 절차가 섞인다. 운영 규칙 파일로 뺀다.

점검표

스킬마다 원본 위치가 한 곳이고, 나머지는 심볼릭 링크다
같은 이름의 스킬이 두 곳에 복사본으로 있지 않다
설치형 스킬은 .skill-lock.json에 출처와 해시가 있다
공유 스킬 본문에 특정 런타임의 도구 이름이 없다
다른 런타임을 부르는 스크립트는 표준 입력을 닫는다
성공 여부를 종료 코드가 아니라 결과 파일로 판단한다
실패 원인이 로그 파일에 남는다
한도에 걸렸을 때 넘어갈 다음 도구가 정해져 있다
허용 목록에는 에이전트 CLI가 아니라 스크립트 경로만 있다
런타임 전용 운영 규칙은 그 런타임 설정 파일에만 있다

스킬 재사용의 핵심은 원본을 한 곳에 두고 링크로 나눠 쓰되, 실행·권한·운영 규칙처럼 런타임마다 다른 것은 끝까지 따로 두는 것이다.