AI 코딩 에이전트가 늘어나면서, 동일한 스킬을 여러 곳에 중복해서 두고 계시지는 않나요? 업데이트할 때마다 전부 수정하는 것은 번거로운 일이며, 그러다 보면 결국 어딘가는 옛날 버전 그대로 방치되게 됩니다.

5명 정도의 개발 팀에서 이 문제에 직면했습니다. 멤버마다 사용하는 에이전트가 달라서, Claude Code 파가 있는가 하면 Codex CLI 파도 있습니다. 동일한 스킬을 두 곳에 두는 운영 방식은 어느 한쪽이 낡아지는 것이 눈에 보였습니다.

해결책은 간단합니다. 심볼릭 링크 (symlink)를 하나 거는 것만으로 충분합니다.

• 스킬의 실체는 .agents/skills/에 둔다 (Codex CLI는 이곳을 공식적으로 직접 읽습니다)
• 직접 읽지 않는 에이전트 (Claude Code 등)의 위치에서는 symlink로 참조하게 한다
• 팀 배포는 프로젝트 리포지토리에 실체와 symlink를 커밋하기만 하면 된다

이렇게 하면 어떤 에이전트를 사용하는 멤버라도 동일한 스킬을 읽을 수 있습니다.

에이전트마다 스킬을 읽어오는 위치가 다릅니다.

단순한 해결책은 동일한 내용을 양쪽 모두에 두는 것입니다. 하지만 이 운영 방식은 스킬을 수정할 때마다 모든 위치를 빠짐없이 계속 업데이트해야 한다는 전제가 필요합니다. 집 안의 모든 시계를 하나씩 손으로 맞춰 돌리는 것과 같아서, 맞추는 것을 잊어버리는 문제를 구조적으로 방지할 수 없습니다.

혼자 사용한다면 어긋나더라도 알아차렸을 때 고칠 수 있습니다. 하지만 팀 단위로 운영하며 다른 멤버들에게도 배포하면, 누구의 컴퓨터 어디에 어떤 것이 옛날 버전인지 추적할 수 있는 수단이 없습니다.

제 환경에서는 실체를 ~/.agents/skills/ 한 곳에만 두고 있습니다. Codex CLI는 공식적으로 이 위치를 직접 읽기 때문에 Codex를 위해 할 일은 없습니다. Claude Code가 읽는 곳은 ~/.claude/skills/뿐이므로, 거기서 링크를 겁니다.

ln -s ~/.agents/skills/review-helper ~/.claude/skills/review-helper

링크가 잘 걸렸는지는 ls -la ~/.claude/skills/를 실행하여 확인할 수 있습니다. 링크가 되어 있다면 실체에 대한 참조가 화살표로 표시됩니다.

review-helper -> /Users/me/.agents/skills/review-helper

이후에는 ~/.agents/skills/review-helper/를 수정하면, Claude Code에서 보이는 내용도 Codex에서 보이는 내용도 동시에 바뀝니다. 수정하는 곳은 단 한 곳뿐입니다. "한쪽만 옛날 버전이 되는 상황"이 원리적으로 발생하지 않게 됩니다.

스킬뿐만 아니라 규칙(rule) 파일에도 같은 구조가 있습니다. Codex CLI는 AGENTS.md를 읽지만, Claude Code가 읽는 것은 CLAUDE.md뿐입니다. 동일한 규칙을 두 파일에 복사해서 가지고 있으면 역시 어느 한쪽이 낡게 됩니다.

# AGENTS.md를 실체로 만들고, CLAUDE.md는 링크로 만든다
ln -s AGENTS.md CLAUDE.md

이것은 제가 임의로 만들어낸 비책이 아니라, Claude Code의 공식 문서에서 AGENTS.md와의 공존 방법으로 안내하고 있는 수법입니다. Claude 전용 추가 내용도 작성하고 싶다면, CLAUDE.md의 상단에 @AGENTS.md라고 적어 가져오는 방법도 같은 페이지에서 안내되고 있습니다.

에이전트 측에 "symlink인지 판정하여 따라가라"와 같은 코드는 작성되어 있지 않습니다. OS가 알아서 해줍니다.

에이전트가 "~/.claude/skills/review-helper/SKILL.md를 열어주세요"라고 OS에 요청하면, 내부에서는 다음과 같이 처리됩니다.

~/.claude/skills/review-helper를 본다

• "이것은 symlink다. ~/.agents/skills/review-helper를 가리키고 있다"
• 그쪽을 보러 간다
• 내부의 SKILL.md를 반환한다

에이전트는 그것이 symlink였다는 사실조차 눈치채지 못합니다. 평범하게 파일을 열려고 했을 뿐인데 내용이 반환되었을 뿐입니다.

따라서 에이전트 측의 구현 방식이 어떻게 되어 있든 상관없습니다. OS 레벨의 메커니즘이므로, Claude Code, Codex CLI, Cline, 혹은 아직 알지 못하는 미래의 에이전트가 등장하더라도 위치 경로(path)만 알 수 있다면 동일한 방식으로 정리할 수 있습니다.

팀과 공유하고 싶은 스킬은 프로젝트 리포지토리(repository)에 실체와 심볼릭 링크 (symlink)를 넣어 커밋합니다. 구조는 다음과 같습니다.

프로젝트 루트/
├── .agents/
│ └── skills/ # 실체는 여기에 위치. Codex CLI는 이를 직접 읽음
...

Windows 사용자가 팀에 있는 경우에만 주의해 주세요. Windows에서 git이 심볼릭 링크 (symlink)를 복원하려면 개발자 모드(Developer Mode) 등의 설정이 필요합니다.

지금까지 설명한 방법의 적용 범위를 정리하면 다음과 같습니다.

• 사용자 레벨의 ~/.agents/skills/에 둔 스킬은 자신의 머신에 있는 모든 리포지토리에서 사용할 수 있습니다.
• 리포지토리에 커밋한 스킬은 해당 리포지토리를 클론 (clone) 하는 모든 멤버에게 전달됩니다.

전달되지 않는 경우는 "팀의 여러 리포지토리에서 동일한 스킬을 사용하고 싶을" 때이며, 이 부분이 심볼릭 링크 (symlink)의 관리 범위를 벗어나는 지점입니다. 제 팀에서는 공유 전용 리포지토리를 하나 만들어 Claude Code의 플러그인 마켓플레이스 (plugin marketplace)를 통해 배포하고 있습니다. 동일한 리포지토리는 Codex의 플러그인 마켓플레이스 (plugin marketplace)로도 등록할 수 있는 형식입니다. 즉, 심볼릭 링크 (symlink)는 "자신의 머신 내 위치를 하나로 묶는" 도구이고, 팀으로의 배포는 "배포 기제 (distribution mechanism)"의 역할이라는 식으로 역할 분담이 이루어집니다.

심볼릭 링크 (symlink)를 하나 연결해 두면 스킬의 실체는 한 곳에 존재하게 됩니다. "어느 쪽이 최신이지?"라고 확인하는 작업이나, 수정을 잊어 오래된 상태로 남은 복사본 문제도 여기서 해결됩니다.

팀이 "Claude Code 파"와 "Codex 파"로 나뉘어 있더라도, 실체를 한 곳에서 수정하면 모두에게 반영됩니다. 새로운 에이전트가 등장하더라도 .agents/skills/를 읽는다면 그대로 작동할 것이고, 읽지 않는다면 링크를 하나 추가하기만 하면 됩니다.