Agent Skills: .claude/skills와 .agents/skills 설정

Claude Code, Codex, Cursor, Gemini CLI에서 같은 저장소를 사용한다면 스킬 원본을 .agents/skills/<skill-name>/에 두세요. Claude Code가 각 공유 스킬을 읽을 수 있도록 .claude/skills/ 아래에 스킬 디렉터리를 가리키는 상대 심볼릭 링크를 만드세요. 팀 전체에 이 구성을 적용하기 전에 각 클라이언트가 스킬을 찾고 호출할 수 있는지 확인하세요.

이렇게 하면 작업 절차를 정의한 파일은 한 벌만 관리하면서 클라이언트마다 다른 탐색 규칙에 맞출 수 있습니다. 팀에서 Claude Code만 사용한다면 기존 .claude/skills/ 구성을 유지해도 됩니다. 같은 스킬을 다른 클라이언트에서도 사용해야 할 때 디렉터리를 옮기는 것이 유용합니다.

AAIF가 디렉터리 이름까지 표준화했나요?

표준은 AAIF 산하 프로젝트가 되었지만, 스킬 탐색 위치는 여전히 각 클라이언트가 정합니다. Anthropic은 2026년 10월 22일 Agent Skills 기증을 발표했고, AAIF도 이를 산하 프로젝트로 받아들였다고 밝혔습니다.

클라이언트 구현 가이드는 스킬 디렉터리를 어디에 둘지는 명세의 요구사항에 포함되지 않는다고 명시합니다. 상호운용성을 위해 클라이언트 고유 디렉터리와 함께 .agents/skills/도 고려하도록 권장합니다. 이 권장사항만으로 기존의 모든 클라이언트가 해당 경로를 탐색하게 되는 것은 아닙니다.

클라이언트 간에 공유하는 단위는 SKILL.md가 들어 있는 디렉터리입니다. 파일에는 시작 부분의 YAML 메타데이터인 프런트매터와 Markdown 지침이 들어갑니다. 형식 명세는 name과 description을 필수로 요구하며, 필요하면 관련 리소스를 함께 둘 수 있습니다. 호출 문법, 스크립트 실행 환경, 권한은 여전히 클라이언트에 따라 다릅니다. 특히 allowed-tools는 실험적 필드이고 구현마다 지원 수준이 달라, 모든 클라이언트에 동일하게 적용되는 권한 정책으로 사용할 수 없습니다.

각 도구는 어떤 경로에서 스킬을 찾나요?

아래 표에 나온 공식 문서의 로컬 탐색 경로를 사용하세요. 이 글의 경로와 조작 방법은 2026-10-26 기준 공식 문서를 따릅니다. 여기서 사용하는 구조를 만들려면 각 기본 경로 뒤에 <skill-name>/SKILL.md를 붙이면 됩니다.

도구	저장소 내 기본 경로	사용자 기본 경로	공유 저장소에서 사용할 방법
Claude Code	.claude/skills/	~/.claude/skills/	.claude/skills/에서 공유 디렉터리로 연결되는 링크를 스킬마다 만듭니다.
Codex CLI 및 IDE 확장	.agents/skills/	~/.agents/skills/	공유 디렉터리를 직접 읽게 합니다.
Cursor Agent	.agents/skills/, .cursor/skills/. 호환성을 위해 .claude/skills/와 .codex/skills/도 지원	~/ 아래의 동일한 네 디렉터리 이름	.agents/skills/를 사용합니다. Cursor용 링크를 추가할 필요가 없습니다.
Gemini CLI	.agents/skills/와 .gemini/skills/	~/.agents/skills/와 ~/.gemini/skills/	.agents/skills/를 직접 읽게 합니다. 같은 범위에서는 .gemini/skills/보다 우선합니다.

현재 Claude Code 가이드에는 .agents/skills/를 직접 탐색하는 기능이 나와 있지 않으며, 기능 요청 #31005도 열린 상태입니다. 반대로 위의 Codex 및 Gemini 가이드는 .claude/skills/를 탐색 기본 경로로 나열하지 않습니다. 두 디렉터리가 모든 클라이언트에서 서로 대체 가능하다고 가정하지 말고, 문서에 명시된 경로를 사용하세요.

이 표는 로컬 파일 탐색 경로를 설명합니다. 노트북의 홈 디렉터리에 있는 스킬이 원격 워커나 새 컨테이너에도 자동으로 제공되는 것은 아닙니다. 해당 실행 환경에도 스킬 파일을 전달해야 합니다.

공유 스킬을 만들고 Claude Code에 연결하기

스킬 전체를 .agents/skills/에 저장하고 그 디렉터리 자체를 링크하세요. 그러면 나중에 추가할 스크립트나 참고 자료도 같은 스킬 디렉터리에 포함됩니다. 스킬별로 링크를 만들면 기존의 Claude 전용 스킬도 함께 유지할 수 있습니다.

먼저 Git과, 설치 및 인증을 마쳐 해당 저장소에서 이미 작업할 수 있는 클라이언트가 필요합니다. 이 파일 시스템 설정에 새로운 API 인증 정보는 필요하지 않습니다. 다만 기존의 클라이언트 접근 조건과 도구 사용 권한은 그대로 적용됩니다.

여러 클라이언트에서 사용할 스킬 작성하기

편집기에서 .agents/skills/review-staged/SKILL.md를 만들고, 필요하면 상위 디렉터리도 생성하세요. 같은 이름의 스킬이 이미 있다면 다른 이름을 선택한 뒤 디렉터리, 프런트매터, 명령에 쓰인 이름을 일관되게 바꾸세요.

다음 내용을 파일에 그대로 붙여 넣으세요.

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

이 스킬은 다음 커밋에 포함하도록 준비한 변경 사항, 즉 Git 인덱스를 검토합니다. Git의 diff 레퍼런스는 이 비교에 --cached를 사용하고, 공백 오류와 충돌 마커 검사에는 --check를 사용한다고 설명합니다. 예제는 클라이언트별 프롬프트 확장 기능에 의존하지 않고, 에이전트가 일반적인 명령을 직접 실행하도록 지시합니다.

macOS 또는 Linux에서 Bash로 링크 만들기

이 스킬을 가리키는 상대 심볼릭 링크를 만드세요. Claude Code는 심볼릭 링크로 연결된 스킬 디렉터리를 지원한다고 명시합니다.

설정하려는 Git 저장소 안의 어느 위치에서든 다음 블록을 Bash로 실행하세요.

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

예상 출력은 ../../.agents/skills/review-staged이며 종료 코드는 0입니다. 두 개의 ..는 링크를 담고 있는 디렉터리인 .claude/skills/를 기준으로 계산되며, 저장소 루트까지 올라갑니다. 상대 경로의 기준은 명령을 시작한 위치가 아니라 링크의 상위 디렉터리입니다.

링크를 만들 경로에 항목이 이미 있다면 변경하기 전에 먼저 확인하세요. 올바른 링크라면 그대로 유지하고, 실제 스킬 디렉터리라면 원본과 내용을 비교해 어떤 내용을 남길지 정리하세요. 이 명령은 기존 디렉터리뿐 아니라 대상이 사라진 링크도 덮어쓰지 않습니다.

Windows에서 같은 링크 만들기

아래의 상대 디렉터리 링크를 만들려면 PowerShell 7.1 이상을 사용하세요. Microsoft의 New-Item 문서에 이 버전 조건이 나와 있습니다. Windows에서 심볼릭 링크를 만들려면 일반적으로 관리자 권한으로 실행하거나, 이를 지원하는 Windows 버전에서 개발자 모드를 켜야 합니다.

원본 SKILL.md를 저장한 상태에서 저장소 루트로 이동해 다음을 실행하세요.

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

결과에서 LinkType은 SymbolicLink여야 하고, 파일 확인 명령은 True를 반환해야 합니다. 권한 부족 오류로 생성에 실패한다면 조직에서 승인한 개발자 모드 설정 절차나 관리자 권한 실행 절차를 따르세요.

네이티브 Git Bash가 Linux와 동일하게 작동한다고 가정하지 마세요. Git for Windows 문서는 기본 ln -s 동작이 복사본을 만든다고 설명합니다. Windows에서는 위의 PowerShell 절차를 사용하고, 만들어진 항목이 실제 링크인지 확인하세요.

저장소를 복제한 뒤에는 다른 문제가 생길 수 있습니다. core.symlinks=false이면 Git은 심볼릭 링크를 대상 경로 문자열이 들어 있는 일반 파일로 체크아웃합니다. 다음 PowerShell 명령으로 이 경우인지 확인하세요.

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

링크 자리에 텍스트 파일이 있다면 내용을 먼저 확인한 뒤, 그 파일만 실제 링크로 교체하세요. 이후 저장소를 복제할 때는 환경에서 지원하는 심볼릭 링크 체크아웃 방식을 사용하도록 설정하세요. Git 설정만 바꾸어도 이미 체크아웃된 텍스트 파일이 디렉터리 링크로 변환되는 것은 아닙니다.

스킬 탐색, 활성화, 출력을 확인하기

먼저 클라이언트의 스킬 목록을 확인하고, 그다음 스킬을 명시적으로 호출하세요. 디스크에 파일이 있다는 사실만으로 클라이언트가 이를 찾았다고 볼 수는 없습니다. 목록에 이름이 나타나더라도 실제 지침이 로드되었는지는 별도로 확인해야 합니다.

각 클라이언트에서 저장소 루트를 열거나 그 위치에서 클라이언트를 시작하세요. 다음 조작은 Bash나 PowerShell 프롬프트가 아니라 클라이언트 안에서 수행합니다.

클라이언트	스킬 탐색 확인	예제 호출
Claude Code	/skills를 실행합니다. 필요하면 명령어 레퍼런스에 나온 /reload-skills를 사용합니다.	/review-staged를 보냅니다.
Codex CLI 또는 IDE 확장	/skills 또는 $ 스킬 선택기를 엽니다.	$review-staged Review my staged changes.를 보냅니다.
Cursor Agent	Customize → Skills를 연 다음 / 선택기에서 스킬을 찾습니다.	review-staged를 선택하고 스테이징된 변경 사항을 검토해 달라고 요청합니다.
Gemini CLI	/skills list를 실행합니다. 파일을 추가했다면 /skills reload를 사용합니다.	Use the review-staged skill to review my staged changes.라고 요청합니다.

Gemini의 문서화된 활성화 절차에서는 activate_skill을 호출하고 대화형 동의 창을 표시합니다. 요청이 나타나면 사용하려는 스킬 디렉터리가 맞는지 확인하고 승인하세요. 목록 조회와 새로고침 명령은 스킬 관리 가이드에 설명되어 있습니다.

예상 응답은 Skill loaded: review-staged로 시작하며, 이어서 발견한 문제와 권장 확인 명령을 제시합니다. 인덱스가 비어 있다면 No staged changes.가 나와야 합니다. 이 표시 문구뿐 아니라 스킬 활성화 또는 파일 읽기 기록, 실행된 Git 명령도 확인하세요. 여기서 확인하는 것은 작업 지침이 로드되었다는 사실이며, 코드 리뷰의 모든 지적이 정확하다는 뜻은 아닙니다.

이 구성에서 Cursor는 두 경로를 모두 읽습니다. 2026년 10월 14일자 IDE 3.25 릴리스 노트는 같은 이름의 스킬이 메뉴에서 별도 행으로 표시될 수 있다고 설명합니다. 설치한 버전에서 중복 항목이 나타나는지 확인하세요. 모든 클라이언트가 여러 링크를 통해 발견한 스킬의 중복을 같은 방식으로 제거한다고 가정하지 마세요.

모노레포와 CI에서 예측 가능한 구조 사용하기

공유 스킬은 저장소 루트에 두고, 최초 설정을 확인할 때는 모든 클라이언트를 그 위치에서 시작하세요. 특정 패키지에만 해당하는 작업 절차라면 스킬의 설명과 지침에 패키지 이름을 명시하세요. 클라이언트마다 중첩 디렉터리를 같은 방식으로 탐색할 것이라고 기대하지 않는 편이 좋습니다. 위 예제는 의도적으로 Git 인덱스 전체를 검토합니다.

다음처럼 각 위치의 역할을 나누면 관리할 파일과 연결용 경로가 분명해집니다.

위치	역할
.agents/skills/review-staged/SKILL.md	수정하고 관리하는 공유 지침 원본입니다.
.agents/skills/review-staged/references/	필요할 때 스킬과 함께 배포하는 참고 문서입니다.
.claude/skills/review-staged	공유 스킬의 전체 디렉터리를 가리키는 상대 링크입니다.
packages/mobile/	요청한 작업에서 지정한 애플리케이션 코드입니다.

스킬이 적용되는 범위의 규칙도 다릅니다. Claude Code와 Codex는 시작 디렉터리에서 저장소 루트까지 상위 디렉터리로 올라가며 각자의 스킬 디렉터리를 찾습니다. Cursor는 프로젝트의 중첩 디렉터리에 있는 스킬도 지원하며, 해당 디렉터리 아래 파일을 작업할 때 그 스킬을 적용하도록 범위를 정합니다. Gemini 관리 가이드는 워크스페이스 스킬을 현재 디렉터리 기준으로 설명합니다. 네 클라이언트를 모두 루트에서 시작하면 이러한 차이에 의존하지 않아도 됩니다.

각 공유 스킬은 스킬 기본 디렉터리 바로 아래의 하위 디렉터리에 두세요. Gemini의 시작 가이드는 탐색 깊이를 이 수준으로 제한합니다. Cursor가 재귀적으로 탐색한다고 해서 중간에 분류용 디렉터리를 추가한 구조가 다른 클라이언트에서도 통하는 것은 아닙니다.

단일 패키지만 연 워크스페이스에서는 그 위치에서 스킬 탐색을 다시 확인하세요. 필요하면 공유 스킬을 해당 워크스페이스에 설치하거나 링크로 연결하세요. 루트에 있는 링크의 ../../ 대상을 더 깊은 디렉터리에서 그대로 재사용하지 말고, 그 위치에 맞춰 상대 경로를 다시 계산해야 합니다.

팀의 체크아웃 환경이 심볼릭 링크를 지원한다면 원본 디렉터리와 상대 링크를 함께 커밋하세요. 링크 대상은 저장소 내부에 두세요. 그래야 새로 복제한 저장소에서도 특정 개발자의 홈 디렉터리에 접근하지 않고 링크 대상을 찾을 수 있습니다.

Linux CI에서 체크아웃한 뒤에는 다음 Bash 명령으로 필요한 파일과 링크가 있는지 확인할 수 있습니다.

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

종료 코드 0은 이 파일 시스템 검사가 통과했다는 뜻입니다. 클라이언트가 실제로 스킬을 탐색하고 호출하는지는 실행할 환경에서 앞서 설명한 방법으로 별도 확인해야 합니다.

스킬이 여전히 로드되지 않으면 어느 단계가 실패했는지 확인하세요

프롬프트를 계속 바꾸기보다는 실패한 단계를 찾아 수정하세요. 아래 항목은 증상별로 선택하는 진단 방법입니다. 모든 사용자가 순서대로 모든 설정을 바꿔야 하는 절차가 아닙니다.

• 목록에 스킬이 없습니다: 워크스페이스 루트, 디렉터리 철자, 정확한 파일 이름 SKILL.md를 확인하세요. 클라이언트가 탐색하는 경로를 통해 파일을 읽어 보세요. 원본 경로에서는 읽히지만 Claude 경로에서는 실패한다면 링크나 체크아웃 상태를 수정하세요.
• 파일은 찾았지만 메타데이터가 거부됩니다: YAML 구분선과 비어 있지 않은 description을 확인하세요. 설명은 최대 1024자여야 합니다. 디렉터리 이름과 name은 같아야 하며, 이름은 소문자·숫자·하이픈으로 구성된 1–64자여야 합니다. 처음이나 끝에 하이픈을 넣거나 연속으로 사용하지 마세요.
• 새 파일이 아직 보이지 않습니다: 위 명령으로 Claude 또는 Gemini 스킬을 다시 로드하세요. Codex 문서는 변경을 자동 감지한다고 설명하며, 반영되지 않으면 재시작하도록 안내합니다. Cursor에서 시작 시 탐색을 다시 수행해야 한다면 클라이언트를 다시 여세요.
• Gemini의 워크스페이스 스킬이 보이지 않습니다: /permissions trust로 폴더 신뢰 상태를 확인하세요. 현재 설정 레퍼런스에서 skills.enabled의 기본값은 true이지만 관리자 정책이 스킬을 금지할 수 있습니다. 비활성화된 설정이나 폴더 신뢰 상태는 해당 설정을 관리하는 기능을 통해 해결하세요.
• 다른 스킬이 실행됩니다: 같은 이름의 개인용 스킬과 프로젝트 스킬을 확인하세요. Claude는 개인용 스킬을 프로젝트 스킬보다 우선하고, Codex는 둘 다 목록에 표시할 수 있습니다. Gemini에서는 워크스페이스 스킬이 사용자 스킬보다 우선합니다. 서로 다른 작업 절차에는 구별되는 이름을 사용하세요.
• 목록에는 있지만 자동으로 선택되지 않습니다: 먼저 명시적으로 호출하세요. 이 방법으로 작동한다면 설명에 어떤 작업을 처리하는지 더 분명히 적으세요. 명확한 설명은 스킬 선택에 도움이 되지만, 이미 정상적으로 발견되는 파일을 옮기는 것은 해결책이 아닙니다.
• 지침은 로드되었지만 명령이 실패합니다: Git을 사용할 수 있는지, 작업 디렉터리가 올바른지, 어떤 권한 오류가 보고되었는지 확인하세요. 여러 클라이언트에서 읽을 수 있는 디렉터리 구조가 실행 환경을 설치하거나 명령 실행 권한을 부여하지는 않습니다.