여러 리포지토리에서 에이전트 스킬 공유 및 관리 방법
에이전트 스킬을 여러 리포지토리에 복사하면 버전 불일치가 발생합니다. 스킬을 의존성처럼 관리하여 중앙 리포지토리에 저장하고, 각 프로젝트가 특정 버전을 고정 및 검토하도록 설정하는 효율적인 운영 방안을 상세히 설명합니다.
리포지토리 간에 에이전트 스킬을 공유하는 방법
리포지토리 간에 에이전트 스킬을 공유하려면 파일을 복사하는 방식을 중단하고 의존성을 설정해야 합니다. 스킬 리포지토리를 하나로 유지하고 태그를 지정한 뒤, 각 프로젝트가 특정 태그를 고정(pin)하도록 합니다. 그런 다음 스킬별로 스모크 테스트를 추가하고, 의존성 버전을 올릴 때와 동일한 방식으로 모든 변경 사항을 검토하십시오.
이 과정은 네 부분으로 구성됩니다. 공유된 단일 진실 공급원(source of truth), 리포지토리별 고정 버전, 스킬별 스모크 테스트, 그리고 검토 경로입니다. 아래 내용은 각 부분이 존재하는 이유, 2026년에 출시되는 도구들이 이를 어떻게 처리하는지, 그리고 외부 Git 호스트나 패키지 레지스트리 없이 자체 호스팅된 Git 원격 저장소에서 이 전체 시스템을 구축하는 방법을 설명합니다. 단, 스모크 테스트는 예외입니다. 스모크 테스트는 Claude Code를 실행하며, 이 과정에서 모든 요청이 모델 API로 전송되므로 해당 단계는 서버 외부로 데이터가 나갑니다.
에이전트 스킬은 SKILL.md 파일과 그에 필요한 스크립트 및 참조 파일을 포함하는 폴더입니다. 해당 단위가 처음이라면 먼저 에이전트 스킬의 정의와 SKILL.md의 작동 방식을 읽어보십시오. 이 페이지는 해당 단위를 둘러싼 공급망에 대해 다룹니다.
기술이 저장되는 위치와 공유가 어려운 이유
Claude Code는 다음 위치를 포함한 여러 곳에서 기술을 불러오며, 각 경로는 기술 문서에 명시되어 있습니다.
.claude/skills/<skill-name>/SKILL.md는 관리형 설정 디렉터리 내부에 위치하며 기업용 경로입니다. 조직이 배포한 머신을 사용하는 모든 사용자에게 적용됩니다.~/.claude/skills/<skill-name>/SKILL.md는 개인용 경로입니다. 사용자의 모든 프로젝트에서 불러오며 다른 사용자와는 공유되지 않습니다..claude/skills/<skill-name>/SKILL.md는 프로젝트 수준의 경로입니다. 해당 저장소를 체크아웃하는 모든 사용자에게 적용됩니다.<plugin>/skills/<skill-name>/SKILL.md은 플러그인 내부에 포함됩니다. 해당 플러그인이 활성화된 모든 곳에서 불러옵니다.
Claude Code는 중첩된 프로젝트 디렉터리, --add-dir로 제공된 디렉터리, 그리고 claude.ai 계정에 활성화된 기술도 함께 불러옵니다.
프로젝트 수준의 경로는 팀 단위 작업에 유용합니다. 커밋된 상태로 저장소에 포함되므로 저장소를 복제하는 모든 사용자가 기술을 사용할 수 있기 때문입니다. 하지만 여기서 문제가 발생합니다. .claude/skills/에 있는 기술은 특정 저장소에 종속됩니다. 만약 저장소가 8개라면, 기술을 8번 복사해야 합니다.
프런트매터(frontmatter)는 이 문제를 해결해주지 않습니다. Agent Skills 사양은 6개의 키를 허용하며, 이를 강제하는 배포 경로는 다른 키를 사용할 경우 다음과 같은 목록을 출력합니다.
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name누락된 항목을 확인하십시오. version 키는 존재하지 않습니다. metadata 아래에 버전을 기록할 수는 있지만, 사양상 의존성 고정이나 업데이트 메커니즘은 정의되어 있지 않습니다. 기술은 패키지가 아닌 문서의 형태이므로 이는 합리적인 설계입니다. 결과적으로 버전 관리는 파일 주변의 계층에서 수행해야 하며, 그 계층을 관리하는 것은 사용자의 몫입니다.
문제 1: 조용히 분기되는 8개의 복사본
복사 및 붙여넣기는 첫날에는 잘 작동합니다. 60일이 지나면 실패합니다. 누군가 payments 저장소의 잘못된 지침을 수정하지만 나머지 7개는 건드리지 않습니다. 다른 누군가는 orders에 페이지네이션 규칙을 추가합니다. 이제 에이전트가 어떤 디렉터리에서 시작했느냐에 따라 동일한 기술 이름이 서로 다른 리뷰를 제공하게 되며, 개발자들은 이 사실을 알지 못합니다.
오류 상태가 없기 때문에 이 실패는 조용히 발생합니다. 기술은 산문입니다. 오래된 지침은 자신감 있게 잘못된 답변을 생성하며, 이는 비용이 많이 드는 유형의 오류입니다. 에이전트 내에는 복사본을 다른 복사본과 비교하는 기능이 없으므로, 유일한 신호는 누군가가 두 저장소의 내용이 서로 다르다는 것을 알아차리는 것뿐입니다.
문제 2: 버전 고정 미비
팀이 기술 관련 자료를 한곳에 모아두더라도, 일반적인 공유 방식은 복사 단계에 의존합니다. 설정 스크립트, 온보딩 문서의 curl 줄, 혹은 폴더를 동기화하는 셸 별칭 등이 이에 해당합니다. 이러한 방식은 모두 현재 브랜치의 최신 상태에 있는 것을 설치합니다.
이는 동일한 애플리케이션의 같은 커밋을 사용하는 두 개발자가 서로 다른 명령을 실행하고 있을 수 있음을 의미합니다. 서로 다른 날짜에 동기화를 수행했기 때문입니다. 또한, 잘못된 에이전트 실행 후 가장 중요한 질문인 "어떤 버전의 기술이 이를 생성했는가?"에 답할 수 없게 됩니다. 기록된 리비전이 없으면 실행 결과를 재현할 수 없으므로, 버그 리포트를 처리할 수 없습니다.
문제 3: 기술이 여전히 작동하는지 아무도 모름
기술(skill)에는 컴파일러가 없습니다. 이는 모델을 대상으로 하는 지침이므로, 파일이 바이트 단위로 동일하게 유지되더라도 작동을 멈출 수 있습니다. 모델이 업그레이드되면 긴 지침을 얼마나 정확하게 따르는지가 달라집니다. 기술이 호출하는 명령줄 도구에서 플래그 이름이 변경될 수도 있습니다. 참조 파일의 URL이 404 오류를 반환하기 시작하면 에이전트는 오류 페이지를 기반으로 작업을 수행하게 됩니다.
이러한 경우 중 어느 것도 명확하게 실패하지 않습니다. 에이전트는 여전히 답변을 내놓습니다. 단지 그 답변이 지난달보다 질이 떨어질 뿐이며, 이는 풀 리퀘스트(pull request) 단위로 확인하기 매우 어려운 문제입니다.
2026년에 출시된 도구들이 해결하는 문제
현재 여러 가지 해결책이 등장하고 있으며, 버전 정보를 어디에 저장해야 하는지에 대해서는 의견이 갈리고 있습니다.
잠금 파일(Lockfiles). Vercel Labs에서 제공하는 명령줄 도구인 skills(vercel-labs/skills, MIT 라이선스, 2026년 10월 9일 기준 v1.7.2)는 Git 저장소에서 에이전트가 요구하는 디렉터리로 스킬을 설치하며, 70개 이상의 에이전트 레이아웃을 지원합니다. npx skills add <repo>은 설치, npx skills update는 업그레이드, npx skills list는 설치된 항목을 확인하는 데 사용합니다. 이 도구는 두 개의 잠금 파일을 유지합니다. ~/.agents/.skill-lock.json에 위치한 전역 잠금 파일은 특정 사용자가 설치한 항목을 기록합니다. v1.4.1(2026년 2월 20일)부터는 프로젝트 범위에 설치할 경우 프로젝트 루트에 skills-lock.json 파일이 생성되며, 도구 소스 코드에 따르면 이 파일은 버전 관리 시스템에 포함해야 합니다. npx skills experimental_install은 이 파일을 사용하여 프로젝트의 스킬을 복원합니다. 다른 머신에서 전역 잠금 파일을 복원하기 위한 skills install 명령을 요청한 이슈 283은 2026년 11월 5일에 '계획 없음(not planned)'으로 종결되었습니다. 관리자는 이를 이슈 549와 동일한 요청으로 간주하고 있습니다. 두 이슈 모두 현황 보고서로 참고하십시오. 프로젝트별 잠금 파일은 존재합니다. 릴리스된 v1.8.1 버전에서 복원 명령은 여전히 도움말에 실험적 기능으로 표시되어 있지만, 소스 없이 npx skills install을 실행해도 프로젝트 잠금 파일이 복원됩니다.
사양 및 테스트. SkillSpec은 다른 접근 방식을 취합니다. 이 도구는 SKILL.md을 신뢰해야 할 설명문이 아닌 검증해야 할 계약으로 취급하며, 스킬을 "추적 가능하고, 테스트 가능하며, 증명 가능하게" 만드는 것을 목표로 합니다. skillspec doctor <path>는 에이전트가 스레드를 중단할 가능성이 있는 지점을 보고합니다. skillspec boundary map <path>은 스킬의 내용을 보여주며, skillspec boundary assess <path>는 위험도 순으로 스킬이 접근할 수 있는 범위를 보고합니다. 이 도구는 Rust 크레이트이며 MIT 또는 Apache 2.0 라이선스로 제공됩니다. 0.2.2 버전은 2026년 7월 29일에 게시되었으며, 2026년 10월 10일 기준으로 crates.io에서 가장 최신 버전입니다. 최신 버전 대신 고정된 버전을 설치하십시오:
cargo install skillspec --version 0.2.2 --locked
skillspec --version2026년 11월 12일에 릴리스된 Cargo 1.100부터 cargo install는 패키지된 잠금 파일을 기본으로 사용하며, --locked은 아무런 동작을 하지 않습니다(no-op). skillspec --version을 실행하면 0.2.2이 출력되어야 합니다. 다른 숫자가 출력된다면 PATH 환경 변수에 설정된 경로상의 이전 바이너리가 우선 적용되고 있는 것입니다.
벤더 관행. Google은 google/skills에서 스킬을 빌드하는 방법을 에이전트 스킬의 빌드, 테스트 및 확장 방식이라는 게시물을 통해 설명했습니다. 규모를 제외하고 보면 이 메커니즘은 일반적인 지속적 통합(CI)과 같습니다. 모든 스킬은 병합되기 전에 프런트매터 메타데이터, 줄 수, 디렉터리 레이아웃 및 명명 규칙에 대한 린터 검사를 통과해야 합니다. 링크 체커는 404를 반환하는 모든 URL에서 빌드를 실패 처리하며, 이를 통해 에이전트가 생성한 그럴듯한 가짜 링크를 잡아냅니다. 작성자는 스킬과 함께 평가 프롬프트 제품군과 채점 기준표를 제공해야 합니다. 이후 예약된 평가 작업이 매주 전체 라이브러리를 대상으로 실행되어 회귀 오류를 포착하며, 모든 스킬에는 품질 저하 시 수정 책임을 지는 담당자가 지정되어 있습니다.
세 가지 답변을 관통하는 패턴
이 중 하나를 선택할 필요는 없습니다. 그 이면에는 단일한 구조가 존재하며, Git만으로도 이 모든 것을 구현할 수 있습니다.
- 단일 진실 공급원(Single source of truth). 기술(skill)은 정확히 한 곳에만 존재하며, 모든 저장소는 복사본을 보유하는 대신 해당 위치를 참조합니다.
- 저장소별 버전 고정(Pinned version). 각 프로젝트는 자신이 사용하는 정확한 리비전을 기록합니다. 따라서 업그레이드는 해당 프로젝트 내에서 작성자와 날짜가 기록된 커밋으로 처리됩니다.
- 기술별 스모크 테스트(Smoke test). 기술이 약속한 결과를 여전히 생성함을 증명하는 실행 가능한 검사 하나를 포함합니다.
- 검토 경로(Review path). 공유 기술에 대한 변경 사항은 검토를 거치며, 모든 소비자는 변경 사항을 적용하기 전에 diff를 확인합니다.
이것이 의존성의 구조입니다. 기술은 이를 둘러싼 도구보다 더 빠르게 공유 아티팩트로 발전했습니다. 따라서 이미 신뢰하고 있는 도구를 사용하는 것이 가장 안전한 방법입니다.
자체 호스팅 Git 원격 저장소를 사용하는 소규모 팀을 위한 레이아웃
하나의 저장소에 기술 관련 내용을 담습니다. 다른 내용은 포함하지 않으므로, 저장소의 이력은 곧 지침의 변경 로그(changelog) 역할을 합니다.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.md릴리스는 태그로 관리합니다. 주석이 달린 태그(annotated tags)를 사용하십시오. 태그에는 메시지와 날짜가 포함되며, 메시지에는 사용자가 버전을 올릴 이유를 명시합니다.
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0원격 저장소로 Gitea, Forgejo, GitLab을 사용하거나, 직접 운영하는 VPS에서 SSH를 통해 bare 저장소를 사용하더라도 아래 내용은 동일하게 적용됩니다. 이 방식은 기본적으로 git과 심볼릭 링크(symlink)를 활용합니다.
Git 서브모듈을 이용한 고정(Pinning)
서브모듈은 다른 저장소의 특정 커밋 하나를 내 저장소 안에 기록합니다. 이 기록이 바로 고정(pin)입니다. 각 소비 프로젝트에서는 다음과 같이 합니다.
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"심볼릭 링크는 이 방식이 작동하게 만드는 핵심 요소입니다. 프로젝트 수준의 skill 항목은 디스크상의 다른 위치에 있는 디렉터리를 가리키는 심볼릭 링크일 수 있으며, Claude Code는 이를 따라가서 대상 위치의 SKILL.md를 읽습니다. 따라서 skill은 일반적인 프로젝트 skill로 로드되지만, 실제 데이터는 사용자가 선택한 커밋 시점의 서브모듈 안에 존재하게 됩니다.
고정 상태를 확인합니다.
git submodule status정상적인 줄은 공백으로 시작하며, 그 뒤에 커밋, 경로, 가장 가까운 태그가 순서대로 표시됩니다.
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)맨 앞에 -이 표시된다면 서브모듈이 초기화되지 않았다는 뜻입니다. 이 경우 .claude/skills/api-review은 아무것도 가리키지 않으며, skill은 아무런 오류 메시지 없이 로드되지 않습니다. git submodule update --init 명령으로 이를 해결하십시오. 맨 앞에 +가 표시된다면 현재 체크아웃된 커밋이 기록된 커밋과 다르다는 뜻입니다. 즉, 해당 개발자는 다른 사람들은 사용하지 않는 명령을 실행하고 있는 것입니다. 새로 클론을 받은 경우에는 git clone --recurse-submodules이 필요하며, 이 명령은 README에 포함해야 합니다. 단순히 클론만 받으면 vendor/agent-skills이 비어 있게 되며 아무런 오류도 출력되지 않기 때문입니다.
업그레이드는 의도적으로 수행해야 하며, 이것이 이 방식의 핵심입니다.
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"diff 줄은 검토 경로를 나타냅니다. 이 줄은 다른 모든 소비 저장소가 보게 될 동일한 변경 사항을 보여주며, 풀 리퀘스트에 포함하기 적합합니다.
플러그인 마켓플레이스를 이용한 고정(Pinning) 방식
모든 개발자에게 서브모듈을 학습하도록 요구하고 싶지 않다면, Claude Code 플러그인 시스템을 통해 배포를 자동화할 수 있습니다. 이 방식은 자체 호스팅된 원격 저장소와 연동됩니다. 스킬 저장소의 .claude-plugin/marketplace.json 경로에 카탈로그를 배치하십시오:
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}여기서는 두 가지 서로 다른 소스가 관여하며, 이 둘을 혼동하는 것이 흔한 실수입니다. 마켓플레이스 소스, 즉 카탈로그 자체를 가져오는 위치는 브랜치나 태그에 대해 ref을 허용하며, Claude Code v2.1.324 이상 버전에서는 전체 소문자 commit SHA도 허용합니다. 별도의 sha 필드는 허용하지 않습니다. 카탈로그 내부의 플러그인 소스는 두 가지 모두를 허용하며, 둘 다 설정된 경우 sha이 실제 고정값으로 적용됩니다. 마켓플레이스 소스의 ref를 통해 카탈로그를 고정하고, 카탈로그 항목의 sha를 통해 플러그인을 고정하십시오. 유형 이름도 서로 다릅니다. 카탈로그 내부에서 url은 복제할 git 저장소를 의미합니다. 마켓플레이스 소스에서 url은 marketplace.json 파일로의 직접 링크를 의미하며, git 저장소는 git로 표기합니다.
각 소비 저장소는 커밋된 .claude/settings.json 파일에 마켓플레이스를 선언합니다:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code는 팀원이 프로젝트 폴더에 대한 작업 공간 신뢰 대화 상자를 수락하면 별도의 위키 페이지 안내 없이도 해당 팀원을 위해 마켓플레이스를 등록합니다. 카탈로그 항목은 상대 경로가 아닌 git URL을 가리키므로, 플러그인 자체가 저장소 설정만으로 설치되지는 않습니다. 각 팀원은 claude plugin install team-skills@acme-agents --scope project을 한 번 실행해야 하며, 그전까지 Claude Code는 플러그인이 프로젝트 설정에서 활성화되어 있지만 설치되지는 않았다고 보고합니다. 이후 스킬은 /team-skills:api-review에 응답합니다. 플러그인 스킬은 플러그인 이름으로 네임스페이스가 지정되므로 동일한 이름의 프로젝트 스킬과 충돌할 수 없기 때문입니다. 새 태그를 푸시하고 카탈로그 및 소비 저장소의 고정값을 업데이트한 후, 소비자는 /plugin marketplace update acme-agents으로 새로 고침을 수행하고 설치 요약에서 요구하는 경우 /reload-plugins를 실행합니다.
한 skill의 smoke test 작성
smoke test는 알려진 결함이 있는 fixture에 대해 에이전트를 스크립트로 실행하고, 하나의 assertion을 수행하는 테스트다. Claude Code는 -p를 사용해 비대화형으로 실행할 수 있으며, 사용자가 호출하는 skill도 이 방식으로 동작한다. 프롬프트 문자열에 /skill-name을 넣으면 실행이 시작되기 전에 확장된다.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md은 의도적으로 결함 하나를 넣은 짧은 파일이다. assertion은 skill이 해당 결함을 식별하는지 확인한다. jq -e은 필터가 null을 생성하면 0이 아닌 상태 코드로 종료하므로, 시드한 결함을 더 이상 포착하지 못하는 skill은 스크립트에서 실패한다. claude 자체도 실행이 실패하면 0이 아닌 상태 코드로 종료하며, set -euo pipefail은 두 실패를 모두 실패한 테스트로 처리한다.
모델은 실행할 때마다 답변의 표현을 바꾼다. 따라서 전체 문장을 대상으로 assertion을 작성해서는 안 된다. 대신 skill이 출력해야 하는 식별자나 요청한 스키마의 필드를 대상으로 assertion을 작성한다. 실행 비용이 낮게 유지되도록 fixture도 작게 만든다.
CI에서는 --bare을 추가한다. 이 옵션이 없으면 claude -p이 대화형 세션과 동일한 컨텍스트를 로드한다. 여기에는 실행 중인 시스템의 hook, plugin, CLAUDE.md이 포함되므로 팀원의 개인 설정이 결과를 바꿀 수 있다. bare mode는 --add-dir으로 명시적으로 지정한 디렉터리 아래의 .claude/skills/에 있는 skill을 제외하면 자동 검색을 건너뛴다. 따라서 여기서 테스트하는 프로젝트 skill은 명시적으로 로드해야 한다. bare mode는 subscription 로그인 정보도 읽지 않으므로, 먼저 환경 변수에 ANTHROPIC_API_KEY을 설정한다.
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format json--plugin-dir으로 로드한 plugin은 .claude-plugin/plugin.json에서 이름을 가져온다. 해당 manifest가 없으면 plugin 이름은 디렉터리 이름이 된다. skills repository의 catalog 옆에 "name": "team-skills"이 포함된 plugin.json을 커밋해야 한다. 그렇지 않으면 위 명령에서 대신 /agent-skills:api-review을 호출해야 한다.
--output-format stream-json을 사용하면 system/init event가 로드된 plugin을 보고하고, 로드되지 않은 plugin에 대해서는 plugin_errors 배열을 포함한다. startup event가 먼저 발생하지 않는 한 이 event가 stream을 연다. plugin_errors이 비어 있지 않으면 CI job을 실패시킨다. 이렇게 하면 더 이상 존재하지 않는 revision을 가리키는 pin을 감지할 수 있다. 그렇지 않으면 에이전트가 내부 운영 규칙을 조용히 무시하는 것처럼 보인다.
공유 skill은 실행 가능한 지시입니다
이 의미를 분명하게 만드는 기능은 2가지이며, 파일이 다른 팀에서 제공된 경우에는 둘 다 중요합니다.
첫째, SKILL.md은 모델이 어떤 내용이든 읽기 전에 셸 명령을 실행할 수 있습니다. 본문에 다음과 같은 줄이 있으면 전처리로 처리됩니다.
- Current branch: !`git rev-parse --abbrev-ref HEAD`이 명령은 skill을 로드하는 컴퓨터에서 실행되며, 그 출력이 모델이 받는 텍스트에서 placeholder를 대체합니다. 세 개의 백틱 다음에 !가 있는 fenced block은 같은 방식으로 여러 명령을 실행합니다. 런타임에는 이 작업에 대해 사용자에게 묻지 않습니다. Claude Code는 각 명령을 권한 규칙과 대조합니다. auto mode가 아니면 해당 규칙이 허용하지 않는 명령이 skill을 중단합니다. 단, 아래의 두 번째 기능을 통해 skill이 해당 명령을 사전 승인한 경우는 예외입니다. deny 및 ask 규칙은 사전 승인을 여전히 우선합니다. 공유 skill을 읽는다는 것은 해당 skill의 명령 대체도 읽는다는 의미입니다.
둘째, frontmatter는 도구를 사전 승인할 수 있습니다. allowed-tools은 skill을 호출한 해당 turn 동안 나열된 도구를 권한 확인 없이 사용할 수 있도록 허용합니다. workspace trust는 이 허용을 제한하지 않습니다. Claude Code는 아무도 신뢰하지 않은 폴더에서 -p를 실행하더라도 프로젝트 skill의 allowed-tools를 적용합니다. Claude Code 문서는 그 결과를 명확히 설명합니다. skill은 광범위한 도구 접근 권한을 스스로 부여할 수 있으므로, Claude Code를 실행하기 전에 repository에 커밋된 skill의 allowed-tools을 검토해야 합니다. 조직은 관리되는 설정에서 allowManagedPermissionRulesOnly을 설정하여 프로젝트 및 개인 skill에서 이 필드를 사용하지 못하게 할 수 있습니다. 이 기능에는 Claude Code v2.1.282 이상이 필요합니다.
따라서 skill 업데이트는 dependency 업데이트와 동일하게 처리해야 합니다. 메커니즘이 허용하는 경우 정확한 commit으로 고정해야 합니다. tag는 이동될 수 있고 branch는 정의상 이동하기 때문입니다. 잠금된 컴퓨터에서는 설정의 "disableSkillShellExecution": true이 모든 명령 대체를 실행하지 않고 문자 그대로의 [shell command execution disabled by policy]로 바꿉니다. 관리되는 설정을 통해 적용하면 사용자가 이를 재정의할 수 없습니다. 번들 skill과 관리되는 skill에는 이 설정이 적용되지 않습니다.
skill이 읽는 내용에도 같은 주의를 기울여야 합니다. env을 실행하거나 config 파일을 여는 skill은 그 안에서 찾은 내용을 모두 모델의 context로 가져옵니다. 이는 실행하는 agent에서 비밀을 제외하는 방법에서 다룬 실패 원인입니다. 페이지를 가져오거나 query를 실행하는 skill은 같은 노출을 외부로 확장합니다. 가져온 텍스트가 작성한 지시와 정확히 같은 형태로 context에 들어가기 때문입니다. 웹 검색을 위해 자체 SearXNG 인스턴스를 agent에 지정하는 방법을 살펴보기 전에 이 경계를 이해해야 합니다.
버전 업데이트 시 확인해야 할 사항
- 모든
SKILL.md본문의 diff를 확인하십시오. 해당 텍스트는 에이전트가 따를 지침입니다. - 모든 명령 치환(command substitution)을 확인하십시오. 스킬이 로드될 때 사용자의 머신에서 실행되기 때문입니다.
allowed-tools에 대한 모든 변경 사항을 확인하십시오. 해당 줄은 프롬프트 없이 도구 사용 권한을 부여합니다.- 태그 뒤에서 실행되는 테스트를 확인하십시오. 공유 저장소가 CI에서 자체적인 스모크 테스트를 실행한다면, 고정하려는 태그에 성공(green) 상태의 실행 결과가 포함되어 있어야 합니다.
10분 안에 전체 diff를 읽을 수 없는 리뷰어는 너무 커져 버린 스킬을 보고 있는 것입니다. 스킬을 분할하십시오. 에이전트가 읽는 저장소 문서에도 동일한 논리가 적용됩니다. 영구적인 규칙은 AGENTS.md 및 HUMAN.md 분할에 설명된 파일에 유지하고, 아키텍처에 대한 근거는 에이전트를 위해 작성된 DESIGN.md에 기록하며, 스킬은 좁은 범위의 절차로 유지하십시오.
모델이나 도구 변경으로 스킬이 작동하지 않을 때
스킬을 직접 수정하지 않아도 내부적으로 여러 요소가 변경될 수 있습니다. 모델이 업그레이드되면 긴 지시 사항을 따르는 신뢰도가 달라지므로, 9단계까지 도달하는 것에 의존하던 스킬이 더 이상 그 단계에 이르지 못할 수 있습니다. 명령줄 도구의 플래그 이름이 바뀌면 에이전트는 이전 플래그를 실행하고 오류를 읽은 뒤 임기응변으로 대응합니다. 참조된 URL이 404 오류를 반환하기 시작할 수도 있습니다. 에이전트 하네스가 스킬을 선택하는 방식이 변경되어, 이전에는 선택되던 description이 더 이상 선택되지 않을 수 있습니다. 절차가 이처럼 조기에 종료되기 시작하면 버전 업데이트만으로는 해결되지 않으며, 마지막 단계까지 강제로 수행하도록 지시 사항 자체에 구조를 부여해야 합니다. 이것이 바로 unlazy 스킬과 Depth Tree 방식의 핵심 접근법입니다.
이러한 환경에서 스모크 테스트가 중요한 역할을 하는 이유가 바로 여기에 있습니다. 각 스킬의 테스트를 푸시할 때뿐만 아니라 정기적인 일정에 따라 실행하십시오. Google이 이러한 이유로 매주 전체 라이브러리를 대상으로 평가 작업을 수행하는 것과 마찬가지로, 10개 정도의 스킬을 운영하는 팀이라면 소형 VPS에서 주간 cron 작업만으로도 충분합니다. 이것이 개발자가 문제를 발견하기 전에 오류를 파악할 수 있는 유일한 방법입니다.
이식성 또한 도움이 됩니다. Agent Skills 사양은 프런트매터를 6개의 키로 제한합니다. 따라서 해당 사양에 맞춰 작성된 스킬은 처음 작성한 도구 외의 다른 도구에서도 로드될 수 있지만, 하네스 전용 키를 추가할 때마다 특정 벤더에 의존하게 됩니다. 모델 교체 후에도 살아남는 스킬을 작성하는 것은 그 자체로 하나의 기술이며, 모든 모델에서 스킬이 작동하도록 만들기에서 다룹니다.
FAQ
여러 저장소에서 에이전트 스킬을 하나로 공유하려면 어떻게 해야 합니까?
스킬을 별도의 git 저장소에 넣고 릴리스 태그를 지정하십시오. 각 프로젝트에서 파일을 복사하는 대신 해당 태그를 참조하게 합니다. 두 가지 방법이 있습니다. git submodule은 정확한 커밋을 기록하며, .claude/skills/<name>에서 submodule로 심볼릭 링크를 걸면 일반 프로젝트 스킬처럼 로드됩니다. 플러그인 마켓플레이스는 /plugin을 통해 동일한 작업을 수행하며, 사용하는 저장소의 .claude/settings.json에 고정(pin) 정보를 선언합니다. 두 방법 모두 git 기록에 버전을 남기므로, 특정 에이전트 실행 결과가 어떤 지침에서 생성되었는지 추적할 수 있습니다.
에이전트 스킬을 특정 버전으로 고정할 수 있습니까?
SKILL.md 내부에서는 불가능합니다. 해당 frontmatter에는 version 키가 없기 때문입니다. 고정은 파일 외부 계층에서 이루어져야 합니다. git submodule은 설계상 정확한 커밋을 고정합니다. Claude Code 플러그인 마켓플레이스에서 플러그인 소스는 브랜치나 태그를 위한 ref과 정확한 커밋을 위한 sha을 허용하며, 둘 다 존재할 경우 sha가 우선합니다. 마켓플레이스 소스 자체는 브랜치, 태그 또는 Claude Code v2.1.324 이상 버전에서는 전체 소문자 커밋 SHA를 위한 ref을 허용합니다. 태그는 검토 후에도 변경될 수 있으므로 커밋 고정을 권장합니다.
스킬 스모크 테스트는 무엇을 검증해야 합니까?
안정적인 항목을 검증하십시오. 알려진 결함이 포함된 픽스처(fixture)를 대상으로 스킬을 비대화형으로 실행한 다음, 출력에 특정 식별자(예: 스킬이 보고해야 하는 규칙 ID)가 나타나는지 확인하십시오. --output-format json와 --json-schema를 사용하여 구조화된 출력을 요청하면 검증이 정확해지며, jq -e은 값이 누락되었을 때 스크립트를 실패 처리합니다. 모델은 실행할 때마다 답변을 다르게 표현하므로 전체 문장을 검증하지 마십시오.
다른 팀의 저장소에서 공유 스킬을 설치해도 안전합니까?
실행 가능한 지침이므로 코드 의존성으로 취급하십시오. SKILL.md은 ! 명령 치환 형식을 통해 로드 시점에 셸 명령을 실행할 수 있으며, frontmatter의 allowed-tools 필드는 프롬프트 없이 도구를 사전 승인할 수 있습니다. 업데이트 시마다 diff를 확인하고, 브랜치 대신 정확한 커밋으로 고정하며, 직접 제어할 수 있는 소스를 우선적으로 사용하십시오. 관리형 머신에서는 설정의 "disableSkillShellExecution": true을 통해 사용자, 프로젝트, 플러그인 및 추가 디렉터리 스킬에서 명령 치환이 실행되지 않도록 차단할 수 있습니다. 단, 번들 및 관리형 스킬은 예외입니다.
공유 스킬이 Claude Code 이외의 에이전트에서도 작동합니까?
사용하는 frontmatter에 따라 다릅니다. Agent Skills 사양은 name, description, license, compatibility, metadata, allowed-tools의 6가지 키를 정의합니다. 이 키들만 사용하는 스킬은 해당 사양을 구현하는 도구에서 로드되며, Claude Code에서도 수정 없이 로드됩니다. 특정 환경 전용 키나 사양을 벗어난 본문 기능은 다른 곳에서 무시되거나 거부되므로, 널리 공유하려는 스킬에는 포함하지 마십시오.