심볼릭 링크로 AI 스킬 공용화하기(Claude Code·Codex·Copilot 경로 정리)-고슴도치 군단

스킬 공용화가 필요한 이유

AI 코딩 도구를 여러 개 사용하다 보면 동일한 스킬 파일을 각 도구 경로에 따로 복사해서 관리하게 됨.

내용을 수정할 때마다 Claude Code, Codex, Copilot 각각의 경로에 들어가 파일을 업데이트해야 하는 번거로움이 생김.

심볼릭 링크(Symbolic Link)를 활용하면 원본 파일 하나를 여러 경로에서 동시에 참조할 수 있어 유지보수가 훨씬 쉬워짐.

각 도구별 스킬 파일 위치

도구마다 스킬 파일을 읽어오는 경로가 다르기 때문에 먼저 각 경로를 정확히 파악하는 것이 중요함.

도구	전역 경로	프로젝트 경로
Claude Code	~/.claude/skills/<name>/SKILL.md	.claude/skills/<name>/SKILL.md
OpenAI Codex	~/.agents/skills/<name>/SKILL.md	.agents/skills/<name>/SKILL.md
GitHub Copilot	VS Code settings.json	.github/prompts/<name>.prompt.md

Claude Code와 Codex는 둘 다 SKILL.md 파일 기반이라 공용화에 가장 적합한 조합임.

Copilot은 .prompt.md 형식을 쓰고 프론트매터 구조가 달라서 별도 관리하는 편이 현실적임.

심볼릭 링크 개념

심볼릭 링크는 특정 파일이나 디렉토리를 가리키는 포인터 역할을 하는 특수 파일임.

원본 파일을 수정하면 링크를 통해 접근하는 모든 경로에서 변경 내용이 즉시 반영됨.

macOS와 Linux에서는 ln -s <원본> <링크경로> 명령으로 간단하게 생성할 수 있음.

공용 스킬 디렉토리 구조 설계

원본 스킬은 한 곳에 모아두고 각 도구의 경로에서 링크를 생성하는 방식으로 구성함.

아래처럼 ~/.shared-skills/ 디렉토리를 기준 저장소로 사용하는 것을 권장함.

~/.shared-skills/
├── tistory-poster/
│   └── SKILL.md
├── git-helper/
│   └── SKILL.md
└── code-reviewer/
    └── SKILL.md

이 구조에서 각 도구의 스킬 경로는 ~/.shared-skills/ 하위 디렉토리를 가리키는 링크로 구성됨.

원본 디렉토리는 별도 git 저장소로 관리하면 버전 이력까지 일원화할 수 있음.

도구별 링크 생성 예시

공용 디렉토리를 만든 뒤 각 도구의 경로에 심볼릭 링크를 생성함.

아래 명령어를 순서대로 실행하면 세 도구에서 동일한 스킬 파일을 참조할 수 있음.

# 공용 디렉토리 생성
mkdir -p ~/.shared-skills/tistory-poster

# 원본 SKILL.md 작성 (한 번만)
cat > ~/.shared-skills/tistory-poster/SKILL.md << 'EOF'
---
name: tistory-poster
description: 티스토리 포스팅 자동화 스킬
---
# 티스토리 자동 포스팅 스킬 내용...
EOF

# Claude Code 전역 링크
mkdir -p ~/.claude/skills
ln -s ~/.shared-skills/tistory-poster ~/.claude/skills/tistory-poster

# Codex 전역 링크
mkdir -p ~/.agents/skills
ln -s ~/.shared-skills/tistory-poster ~/.agents/skills/tistory-poster

# 프로젝트별 링크 (해당 프로젝트 루트에서 실행)
mkdir -p .claude/skills
ln -s ~/.shared-skills/tistory-poster .claude/skills/tistory-poster

링크가 올바르게 생성됐는지 ls -la ~/.claude/skills/ 명령으로 확인할 수 있음.

-> 화살표가 원본 경로를 가리키면 정상적으로 연결된 것임.

링크 상태 확인 및 관리

링크 전체 목록을 한눈에 확인하려면 아래 명령을 사용함.

# Claude Code 스킬 링크 확인
ls -la ~/.claude/skills/

# Codex 스킬 링크 확인
ls -la ~/.agents/skills/

# 깨진 링크 탐색 (원본이 삭제된 경우)
find ~/.claude/skills -type l ! -exec test -e {} \; -print

원본 파일을 삭제하거나 경로를 변경하면 링크가 깨지므로 원본 이동 시에는 링크도 함께 갱신해야 함.

링크를 삭제할 때는 rm 명령을 사용하며, 원본에는 영향을 주지 않음.

주의사항 정리

SKILL.md 내부에서 상대 경로로 다른 파일을 참조할 경우 링크 소스 기준인지 원본 기준인지 동작이 도구마다 다를 수 있음.

심볼릭 링크 자체는 git이 추적하지만 링크가 가리키는 ~/.shared-skills/ 원본 디렉토리는 별도 저장소로 관리해야 팀 공유가 가능함.

Claude Code와 Codex는 SKILL.md 파일 형식이 비슷하지만 프론트매터 키가 다를 수 있어 각 도구의 최신 문서를 확인하고 공통 필드만 사용하는 것을 권장함.

요약

심볼릭 링크를 활용하면 스킬 파일을 한 곳에서 관리하면서 여러 AI 도구에 동시에 적용할 수 있음.

특히 Claude Code와 Codex 조합은 동일한 SKILL.md 포맷을 공유하므로 파일 수정 없이 링크만으로 공용화가 가능함.

원본 디렉토리를 git으로 버전 관리하면 스킬 이력까지 체계적으로 관리할 수 있으니 적극 활용해 보길 권장함.