AI 에이전트 스킬, 복사하지 말고 Symlink로 - 한 번 만들어 모든 에이전트에서 쓰기

AI 노트 

▶ AI 에이전트 · 스킬 관리

AI 에이전트 스킬, 복사하지 말고 Symlink로 - 한 번 만들어 모든 에이전트에서 쓰기

Claude Code · Codex · Cursor · Gemini CLI… 에이전트는 늘어가는데 같은 스킬을 매번 복사해서 쓰고 있다면, 관리는 곧 무너진다. 원본 하나만 두고 나머지를 심볼릭 링크로 연결하는, 가장 깔끔한 스킬 관리 전략 정리.

주제 AI 에이전트 운영 난이도 ★★☆☆☆ 초중급 키워드 Skill · Symlink · Claude Code · Codex

▶ LEARNING GOALS

이 글을 다 읽으면 다음을 할 수 있습니다

• "스킬은 Claude 전용"이라는 흔한 오해를 정리하고, 표준화된 자원으로 이해할 수 있다
• 전역(Global) 스킬과 지역(Local) 스킬의 차이, 그리고 왜 지역 스킬이 더 효율적인지 설명할 수 있다
• 각 에이전트의 고유 폴더(​.claude/skills, ​.codex/skills 등)가 만드는 함정을 안다
• 심볼릭 링크(symlink)로 스킬 원본 1개를 모든 에이전트가 공유하게 만들 수 있다
• Codex로 만든 스킬을 Claude Code에서 symlink로 끌어다 쓰는 실제 흐름을 따라할 수 있다

요즘 자동화 도구로 Claude를 쓰다 보면, 어느새 손에 잡힌 도구가 한둘이 아니다. Claude Code · Codex · Cursor · Gemini CLI · Antigravity… 각각이 강한 부분이 달라서 작업마다 다른 친구를 부르게 된다.

그러다 만나는 흔한 풍경 - 같은 스킬을 매번 복사해서 각 에이전트 폴더에 넣어 두고 있는 자기 자신. 한 번 잘 만들어 둔 스킬을 수정할 때마다 여러 폴더를 일일이 손대야 한다면, 그건 관리가 아니라 노동이다.

결론은 단순하다. 스킬은 한 곳에만 두고, 다른 에이전트는 심볼릭 링크로 그곳을 가리키게 한다. 이 글은 그 전략의 이유와 실제 적용 방법을 정리한 노트다.

[ 목 차 ]

• 1.왜 스킬 관리가 문제가 되는가
• 2.스킬에 대한 흔한 오해 — Claude 전용이 아니다
• 3.전역 vs 지역 — 스킬을 어디 둘 것인가
• 4.에이전트 고유 폴더의 함정
• 5.Symlink — 핵심 해결책 한 가지
• 6.[실습] Codex에서 만든 스킬을 Claude Code에서 쓰기
• 7.핵심 정리 · 체크리스트

[1] 왜 스킬 관리가 문제가 되는가

"스킬"이라는 말은 들어 봤지만, 정작 효율적으로 관리하는 법은 모르고 쓰는 사람이 많다. 그러다 보니 다음과 같은 비효율이 일상이 된다.

😶 공유 가능성을 모름

스킬이 에이전트 간에 공유될 수 있다는 사실을 인지하지 못한다.

📋 무분별한 복사

같은 스킬을 여러 폴더에 복사해 두고 따로따로 관리한다.

🔧 수정의 지옥

스킬 한 줄 수정에도 모든 복사본을 일일이 고쳐야 한다.

🔍 탐색 성능 저하

전역에 스킬이 쌓일수록 에이전트가 스킬 목록을 읽는 시간이 길어진다.

스킬을 효율적으로 활용하고 중복을 막으려면 "한 번 만들어 어디서나 쓴다"는 원칙을 시스템으로 강제할 필요가 있다. 이 글의 결론은 이 한 줄로 요약된다.

[2] 스킬에 대한 흔한 오해 - Claude 전용이 아니다

스킬을 처음 접한 사람들이 가장 자주 하는 오해는 "스킬은 Claude(또는 Claude Code) 전용 기능"이라는 것이다. 그렇지 않다.

오해	사실
스킬은 Claude만의 고유 기능이다	Anthropic이 처음 제시했지만, 이후 에이전트 간 공유 가능한 표준으로 자리잡았다
다른 에이전트에선 못 쓴다	Cursor, Codex CLI, Gemini CLI, Antigravity 등 대부분의 AI 에이전트가 스킬을 사용한다
각 에이전트별로 따로 만들어야 한다	한 번 잘 만든 스킬은 어떤 에이전트에서도 그대로 동작한다

USB 메모리 같은 거다. Anthropic이라는 회사가 만든 USB라고 해서, 다른 컴퓨터 회사의 PC에 안 꽂히는 게 아니다. 규격이 표준화되어 있으면 어디든 꽂힌다. 스킬도 그렇다.

[3] 전역 vs 지역 — 스킬을 어디 둘 것인가

스킬은 PC의 "어디"에 저장되느냐에 따라 두 가지로 나뉜다. 이 차이를 제대로 이해해야 다음 단계가 보인다.

전역(Global) 스킬

• PC 전체 범위에 설치 - 모든 에이전트가 접근 가능
• 설치된 스킬이 늘수록 PC가 복잡해짐
• 탐색 시간이 길어져 성능 저하 우려
• 관리 습관 측면에서 비효율적

지역(Local) 스킬

• 특정 프로젝트 폴더 내에 저장
• 해당 프로젝트에서만 우선 참조 - 깔끔
• 프로젝트 단위로 묶이므로 다른 에이전트도 같은 폴더에서 접근 가능
• 이상적인 관리 방식

권장 방향은 단순하다 — 전역 스킬은 최소화하고, 대부분은 지역 스킬로 관리한다. Google Workspace CLI처럼 진짜 범용으로 어디서나 쓸 스킬만 전역에 두고, 나머지는 프로젝트 폴더 안에 넣는다.  ex)  "협회 자료 변환" 같은 협회 전용 스킬은 협회 작업 프로젝트 폴더에, "PDF 추출" 같은 진짜 범용은 전역에. 이렇게 나누면 PC가 깔끔해지고 어떤 에이전트로 갈아타도 헷갈리지 않는다.

[4] 에이전트 고유 폴더의 함정

여기서 진짜 문제가 시작된다. 각 에이전트는 자기 이름이 붙은 고유 폴더에 스킬을 저장하려고 한다. 같은 프로젝트 폴더 안에서도 —

📁 my_project/
├─ ​.claude/
│   └─ skills/      # Claude가 만든 스킬은 여기로
│       └─ skill_a/
├─ ​.codex/
│   └─ skills/      # Codex가 만든 스킬은 여기로
│       └─ skill_b/
└─ ​.cursor/
    └─ skills/      # Cursor가 만든 스킬은 여기로

문제는 각 에이전트가 자기 폴더만 쳐다본다는 점이다. Claude로 만든 skill_a가 ​.claude/skills에 있다면, Codex는 ​.codex/skills에 같은 스킬이 없으면 인식하지 못한다.

그래서 흔히 일어나는 일

"그럼 복사하면 되지" 하고 한 스킬을 세 폴더에 복사한다. 처음엔 동작한다. 그런데 일주일 뒤 그 스킬을 한 줄 수정해야 할 때 —

스킬을 한 군데만 수정하고 다른 두 곳은 잊어버린다. 어제까지 잘 되던 작업이 갑자기 안 되고, 한참을 헤맨 끝에 "아, 그 스킬 다른 폴더 버전은 옛날 버전이었구나" 하고 깨닫는다. 이 함정이 한두 번 반복되면 스킬 관리 자체에 회의가 든다.

[5] Symlink - 핵심 해결책 한 가지

해법은 의외로 단순하다. 스킬 원본은 한 곳에만 두고, 다른 에이전트의 고유 폴더에는 "그곳으로 가라"는 메모만 남긴다. 이 메모가 바로 심볼릭 링크(symlink)다.

사무실에 비유하면 — 회의록 원본은 사무국장 책상 서랍에 한 부만 둔다. 다른 직원들 책상 서랍에는 회의록을 똑같이 복사해서 넣어두는 게 아니라, "회의록은 사무국장 책상 서랍에 있음" 이라고 적힌 쪽지만 둔다. 누가 회의록을 보러 와도 결국 같은 원본 한 부를 보게 된다. 수정도 한 번이면 끝.

REAL · 원본

​.codex/skills/
hyper_slide_image/

실제 스킬 파일들

←

LINK · 심볼릭 링크

​.claude/skills/
hyper_slide_image

"원본은 ​.codex 쪽에 있어요"

Symlink가 가져오는 4가지 이점

① 원본 1개	스킬 파일은 디스크에 단 한 부만 존재한다. 중복 자체가 사라진다.
② 한 번에 수정	원본을 고치면 모든 에이전트가 같은 버전을 본다.
③ 에이전트 갈아타기 자유	주력 에이전트가 바뀌어도 같은 스킬을 그대로 쓸 수 있다.
④ 깔끔한 폴더 구조	"이 폴더는 진짜 파일, 저 폴더는 링크" — 역할이 명확해진다.

[6] [실습] Codex에서 만든 스킬을 Claude Code에서 쓰기

개념만으론 안 와닿는다. 직접 따라가 보자. 시나리오는 — Codex에서 슬라이드 이미지 생성 스킬을 만들고, 그걸 Claude Code에서도 똑같이 쓰는 것이다.

[Step 1] 작업 환경 만들기

1

테스트 폴더 생성

$ mkdir skill_manage_study
$ cd skill_manage_study

2

두 에이전트를 같은 폴더에서 실행

# Claude Code (권한 자동 승인 모드)
$ claude --skip-permissions

# Codex (bypass 모드)
$ codex bypass

두 에이전트 모두 같은 프로젝트 폴더를 작업 공간으로 인식한다.

[Step 2] Codex로 스킬 만들기

Codex는 skill-creator 스킬을 통해 새로운 스킬을 만들 수 있다. 다음과 같이 지시한다.

CODEX 프롬프트

HTML과 CSS를 활용해서 4:3 비율의 전통적인 발표 슬라이드 이미지를
생성하는 스킬을 만들어줘.

- 디자인 레퍼런스: styles​.repper​.dev 의 'Hyper Aviation'
- 슬라이드 구성: 큰 제목 + 서브 제목 + 불릿 3개 (텍스트 위주)
- 균형감 있는 레이아웃, 한 장만

⚠ 중요: 전역 스킬이 아니라 현재 프로젝트 폴더 안의 지역 스킬로 만들어줘.

"지역 스킬로 만들어줘"라는 지시를 명시적으로 넣지 않으면 에이전트가 전역(글로벌) 폴더에 생성해 버릴 수 있다. 지역 스킬을 원한다면 반드시 못 박는다.

Codex는 자기 고유 폴더 안에 스킬을 만든다.

📁 skill_manage_study/
└─ ​.codex/
    └─ skills/
        └─ hyper_slide_image/   # 실제 스킬 파일들
            ├─ SKILL​.md
            └─ ​.​.​.

[Step 3] Claude Code로 가서 인식 안 되는 것 확인

같은 폴더에서 Claude Code로 들어가 list skills 같은 명령을 던져도, 방금 만든 hyper_slide_image는 목록에 없다. Claude Code는 ​.claude/skills만 보기 때문이다.

이 시점에 두 가지 길이 있다 — (A) 스킬을 ​.claude/skills에 그대로 복사 (나쁜 길), (B) symlink로 연결 (좋은 길). 우린 후자다.

[Step 4] Claude Code에 symlink 만들도록 지시

CLAUDE CODE 프롬프트

현재 프로젝트의 ​.codex/skills 안에 hyper_slide_image 라는 스킬이 있어.
이걸 ​.claude/skills 폴더에서 심볼릭 링크로 연결해서 내가 사용할 수 있게
설정해 줘. (스킬 파일을 복사하지 말고, 반드시 symlink로 연결할 것)

Claude Code는 다음과 같이 폴더를 만들고 symlink를 건다.

📁 skill_manage_study/
├─ ​.codex/skills/
│   └─ hyper_slide_image/      # 원본 (실제 파일)
└─ ​.claude/skills/
    └─ hyper_slide_image → ​.​.​/​.​.​/​.codex/skills/hyper_slide_image
                                       # 심볼릭 링크 (메모일 뿐)

검증 — 실체가 어디 있는지 묻기

You: "방금 연결한 hyper_slide_image 스킬은 실제 파일이 어디에 있어?"
Claude: "​.codex/skills/hyper_slide_image 에 있습니다.
       ​.claude/skills 쪽은 그곳을 가리키는 심볼릭 링크일 뿐입니다."

[Step 5] Claude Code 재시작 후 스킬 사용

Claude Code를 한 번 재시작하면 hyper_slide_image가 스킬 목록에 등장한다. 이제 사용해 본다.

CLAUDE CODE 프롬프트

Codex 라는 도구를 설명하는 슬라이드 한 장만 만들어 봐.
hyper_slide_image 스킬을 써.

결과 — Codex에서 만들었던 그 디자인 그대로 슬라이드가 나온다. 스킬은 한 곳(​.codex/skills)에만 존재하고, Claude Code는 symlink를 통해 그것을 그대로 사용하는 것이다. 복사본은 0개다.

Windows에선 symlink가 잘 만들어지나? PowerShell에서도 되나?

Windows 10/11에서는 PowerShell의 New-Item -ItemType SymbolicLink 명령 또는 명령 프롬프트의 mklink /D로 가능하다. 단, 관리자 권한 또는 "개발자 모드" 활성화가 필요할 수 있다. 에이전트에 명령하면 자동으로 처리해 준다.

전역 스킬도 symlink로 묶을 수 있나?

가능하다. 예를 들어 홈 폴더의 ~/​.claude/skills/my_skill을 만들고, 다른 에이전트의 전역 스킬 폴더에서 거기를 가리키는 symlink를 두면 된다. 다만 글에서 강조했듯 — 전역 스킬은 최소화하는 편이 PC 관리에 유리하다.

[7] 핵심 정리 · 체크리스트

★ KEY TAKEAWAYS

1. 스킬은 표준화된 자원이다. Claude만의 것이 아니라 Codex · Cursor · Gemini CLI 등 대부분의 에이전트에서 동작한다.
2. 스킬은 전역과 지역으로 나뉜다. 대부분은 프로젝트 폴더 안의 지역 스킬로 관리하는 것이 효율적이다.
3. 각 에이전트는 자기 고유 폴더(​.claude/skills, ​.codex/skills)만 쳐다본다 — 이게 함정이다.
4. 해법은 심볼릭 링크. 원본은 한 폴더에 두고, 나머지는 그곳을 가리키는 메모만 둔다.
5. 장점은 명확하다 — 원본 1개, 한 번에 수정, 에이전트 갈아타기 자유, 폴더 구조 깔끔.
6. 실무 한 줄 — "스킬은 복사하지 말고, 가리키게 하라."

실습 체크리스트

• 전역 스킬과 지역 스킬의 차이를 한 문장으로 설명할 수 있다
• 각 에이전트의 고유 스킬 폴더 위치를 확인했다 (​.claude/skills, ​.codex/skills 등)
• 한 에이전트로 지역 스킬을 직접 만들어 봤다
• 다른 에이전트에서 그 스킬이 인식되지 않는 것을 확인했다
• 심볼릭 링크를 만들어 다른 에이전트에서도 같은 스킬이 보이게 했다
• "실제 파일이 어디 있냐"고 물어 원본 위치를 한 곳으로 검증했다
• 원본을 수정한 뒤, 모든 에이전트에서 변경 사항이 반영되는지 확인했다
• 전역에 둘 스킬과 프로젝트별 지역에 둘 스킬을 분리하는 기준을 정했다

---

AI 에이전트 진영은 매달 모양이 바뀐다. 어제는 Claude Code, 오늘은 Codex, 내일은 또 다른 친구가 등장할지 모른다. 도구가 갈아끼워질 때마다 스킬도 같이 갈아끼워야 한다면, 그건 도구가 아니라 짐이다. "한 번 만들어 어디서나" — 이 단순한 원칙 하나가 도구의 변화를 따라가는 가장 가벼운 방식이다.

— AI 노트 · 스킬 관리 정리

AI 노트