작성자 리포지토리 간 에이전트 스킬 공유 및 버전 관리 방법
여러 리포지토리에 에이전트 스킬을 복사하면 발생하는 코드 파편화 문제를 해결합니다. 스킬을 의존성처럼 관리하여 단일 리포지토리에서 버전을 고정하고, 스모크 테스트를 통해 변경 사항을 안전하게 검토하는 표준화된 워크플로우를 안내합니다.
리포지토리 간에 에이전트 스킬을 공유하는 방법
리포지토리 간에 에이전트 스킬을 공유하려면 파일을 복사하는 방식을 중단하고 의존성을 설정해야 합니다. 하나의 스킬 리포지토리를 유지하고 태그를 지정한 뒤, 각 프로젝트가 특정 태그를 고정(pin)하도록 하십시오. 그런 다음 스킬별로 스모크 테스트를 추가하고, 의존성 버전을 올릴 때와 동일한 방식으로 모든 변경 사항을 검토하십시오.
이 과정은 네 부분으로 구성됩니다. 공유된 단일 진실 공급원(source of truth), 리포지토리별 고정 버전, 스킬별 스모크 테스트, 그리고 검토 경로입니다. 아래 내용은 각 요소가 필요한 이유, 2026년에 출시되는 도구들이 이를 어떻게 처리하는지, 그리고 외부 서비스 없이 자체 호스팅된 git 원격 저장소에서 전체 시스템을 구축하는 방법을 설명합니다.
에이전트 스킬은 SKILL.md 파일과 필요한 스크립트 및 참조 파일을 포함하는 폴더입니다. 해당 단위가 처음이라면 먼저 에이전트 스킬의 정의와 SKILL.md의 작동 방식을 읽어보시기 바랍니다. 이 페이지는 해당 단위를 둘러싼 공급망에 대해 다룹니다.
기술이 위치하는 곳과 공유가 어려운 이유
Claude Code는 세 곳에서 기술(skill)을 불러오며, 각 경로는 기술 문서에 명시되어 있습니다.
~/.claude/skills/<skill-name>/SKILL.md는 개인용입니다. 사용자의 모든 프로젝트에서 불러오며 다른 사람에게는 영향을 주지 않습니다..claude/skills/<skill-name>/SKILL.md는 프로젝트 수준입니다. 해당 저장소를 체크아웃하는 모든 사용자에게 적용됩니다.<plugin>/skills/<skill-name>/SKILL.md은 플러그인 내부에 포함됩니다. 해당 플러그인이 활성화된 모든 곳에서 불러옵니다.
중간에 있는 경로는 팀 단위 작업에 유용합니다. 커밋이 가능하며 저장소를 복제(clone)하는 모든 사람이 이를 공유받기 때문입니다. 하지만 바로 이 지점에서 문제가 발생합니다. .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 키가 존재하지 않습니다. 파일 내부 어디에도 어떤 복사본이 더 최신인지 기록하는 항목이 없습니다. 기술은 패키지가 아닌 문서의 일종이므로 이는 합리적인 설계입니다. 하지만 이는 버전 관리가 파일 외부 계층에서 이루어져야 함을 의미하며, 그 계층을 관리하는 것은 사용자의 몫입니다.
문제 1: 조용히 분기되는 8개의 복사본
복사 및 붙여넣기는 첫날에는 잘 작동합니다. 60일이 지나면 실패합니다. 누군가 payments 저장소의 잘못된 지침을 수정하지만 나머지 7개는 건드리지 않습니다. 다른 누군가는 orders에 페이지네이션 관련 규칙을 추가합니다. 이제 에이전트가 시작된 디렉터리에 따라 동일한 기술 이름이 서로 다른 리뷰를 제공하게 되며, 개발자 중 누구도 이를 알지 못합니다.
오류 상태가 존재하지 않기 때문에 이 실패는 조용히 발생합니다. 기술은 산문입니다. 오래된 지침은 자신감 있게 잘못된 답변을 생성하며, 이는 가장 비용이 많이 드는 유형의 오류입니다. 에이전트 내에는 귀하의 복사본을 다른 복사본과 비교하는 기능이 없으므로, 유일한 신호는 누군가가 두 저장소의 내용이 일치하지 않는다는 것을 알아차리는 것뿐입니다.
문제 2: 버전 고정의 부재
팀이 기술 문서를 한곳에 모아두더라도, 일반적인 공유 방식은 복사 단계에 의존합니다. 설정 스크립트, 온보딩 문서의 curl 한 줄, 혹은 폴더를 동기화하는 셸 별칭 등이 그 예입니다. 이러한 방식은 모두 현재 브랜치의 최신 상태에 있는 것을 설치합니다.
이는 동일한 애플리케이션의 동일한 커밋을 다루는 두 개발자가 서로 다른 명령을 실행하고 있을 수 있음을 의미합니다. 각자가 서로 다른 날짜에 동기화를 수행했기 때문입니다. 또한, 잘못된 에이전트 실행 후 가장 중요한 질문인 "어떤 버전의 기술이 이 결과를 생성했는가?"에 답할 수 없게 됩니다. 기록된 리비전이 없으면 실행 결과를 재현할 수 없으며, 따라서 버그 리포트를 처리할 수 없습니다.
문제 3: 기술이 여전히 작동하는지 아무도 모름
기술(skill)에는 컴파일러가 없습니다. 이는 모델을 대상으로 하는 지침이므로, 파일이 바이트 단위로 동일하게 유지되더라도 작동을 멈출 수 있습니다. 모델이 업그레이드되면 긴 지침을 따르는 정확도가 달라집니다. 기술이 호출하는 명령줄 도구의 플래그 이름이 변경될 수도 있습니다. 참조 파일의 URL이 404를 반환하기 시작하면 에이전트는 오류 페이지를 기반으로 작동하게 됩니다.
이러한 경우 중 어느 것도 명확하게 실패하지 않습니다. 에이전트는 여전히 답변을 내놓습니다. 단지 답변의 품질이 지난달보다 떨어질 뿐이며, 이는 풀 리퀘스트(pull request) 단위로 확인하기 매우 어려운 문제입니다.
2026년에 출시되는 도구들이 해결하는 문제
현재 여러 가지 해답이 제시되고 있으며, 버전 정보를 어디에 두어야 할지에 대해서는 의견이 갈리고 있습니다.
락파일(Lockfiles). Vercel Labs의 명령줄 도구인 skills(vercel-labs/skills, MIT 라이선스, 2026년 8월 5일 기준 v1.5.22)는 Git 저장소에서 에이전트가 요구하는 디렉터리로 스킬을 설치하며, 70개가 넘는 에이전트의 레이아웃을 지원합니다. npx skills add <repo>은 설치, npx skills update는 업그레이드, npx skills list는 설치된 항목을 확인하는 데 사용합니다. 설치 기록은 저장소별이 아닌 사용자별로 한 번씩 유지됩니다. 해당 프로젝트의 공개 요청(issue 283)에서는 락파일로부터 추적 중인 모든 스킬을 재설치하여 다른 머신에서도 동일한 환경을 구성할 수 있도록 하는 skills install 명령을 요구하고 있습니다. 이 요청을 현황 보고서로 참고하십시오. 락파일 개념은 확립되었으나, 프로젝트별 관리 기능은 아직 개발 중입니다.
사양 및 테스트. SkillSpec은 다른 관점에서 접근합니다. 이 도구는 SKILL.md을 신뢰해야 할 문장이 아닌 검증해야 할 계약으로 취급하며, 스킬을 "따라갈 수 있고(followable), 테스트 가능하며(testable), 증명 가능한(provable)" 상태로 만드는 것을 목표로 합니다. skillspec doctor <path>은 에이전트가 스레드를 놓칠 가능성이 있는 지점을 보고합니다. skillspec boundary map <path>는 스킬이 도달할 수 있는 범위를 보고하며, skillspec boundary assess <path>은 이러한 결과를 위험도에 따라 순위를 매깁니다. 이 도구는 Rust 크레이트(crate)이며 MIT 또는 Apache 2.0 듀얼 라이선스로, 2026년 7월 29일 기준 버전 0.2.2입니다. 최신 버전 대신 고정된 버전을 설치하십시오.
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked은 해당 크레이트가 배포될 당시의 의존성 버전으로 빌드하므로, 빌드 환경이 의도치 않게 변경되지 않습니다. skillspec --version를 실행하면 0.2.2이 출력되어야 합니다. 다른 숫자가 출력된다면 PATH 경로상에 있는 이전 버전의 바이너리가 우선 적용되고 있다는 의미입니다.
벤더 관행. Google은 google/skills에서 스킬을 빌드하는 방법을 에이전트 스킬의 빌드, 테스트 및 확장 방식에 관한 게시물을 통해 설명했습니다. 규모를 제외하고 보면 이 메커니즘은 일반적인 지속적 통합(CI)과 같습니다. 모든 스킬은 병합되기 전에 프런트매터 메타데이터, 줄 수, 디렉터리 레이아웃, 명명 규칙에 대한 린터(linter) 검사를 통과해야 합니다. 링크 검사기는 404를 반환하는 모든 URL에서 빌드를 실패 처리하며, 이를 통해 에이전트가 생성한 그럴듯한 가짜 링크를 잡아냅니다. 작성자는 스킬과 함께 평가 프롬프트 세트와 채점 기준표를 제공해야 합니다. 이후 예약된 평가 작업이 매주 전체 라이브러리를 대상으로 실행되어 회귀(regression)를 감지하며, 모든 스킬에는 품질 저하 시 수정 책임을 지는 담당자가 지정되어 있습니다.
세 가지 답변을 관통하는 패턴
이 중 하나를 선택할 필요는 없습니다. 그 이면에는 단일한 형태가 존재하며, 표준 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 명령으로 이를 해결하십시오. 맨 앞에 +가 표시된다면 체크아웃된 커밋이 기록된 커밋과 다르다는 뜻이며, 해당 개발자는 다른 사람들은 사용하지 않는 명령을 실행하고 있는 것입니다. 새로 복제(clone)할 때는 git clone --recurse-submodules이 필요하며, 일반적인 clone을 수행하면 vendor/agent-skills이 비어 있고 오류 메시지도 출력되지 않으므로 이 명령을 README에 포함해야 합니다.
업그레이드는 의도적으로 수행하며, 이것이 이 방식의 핵심입니다:
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 줄은 검토 경로입니다. 이는 다른 모든 소비 저장소가 보게 될 동일한 변경 사항을 보여주며, 풀 리퀘스트(pull request)에 포함하기 적합합니다.
플러그인 마켓플레이스를 이용한 고정(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를 허용하며 sha는 허용하지 않습니다. 카탈로그 내부의 플러그인 소스는 둘 다 허용하며, 두 설정이 모두 존재할 경우 sha이 우선 적용됩니다. 따라서 특정 커밋으로 고정하려면 카탈로그 항목에 설정해야 합니다.
각 소비 저장소는 커밋된 .claude/settings.json 파일에 마켓플레이스를 선언합니다:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}프로젝트 폴더를 신뢰하는 팀원은 마켓플레이스 설치 메시지를 받게 되며, 별도의 위키 페이지 안내 없이도 플러그인이 활성화됩니다. 이후 스킬은 /team-skills:api-review에 응답합니다. 플러그인 스킬은 플러그인 이름으로 네임스페이스가 지정되므로 동일한 이름의 프로젝트 스킬과 충돌하지 않기 때문입니다. 새로운 태그를 푸시한 후, 소비자는 /plugin marketplace update acme-agents로 새로고침을 수행하고, 설치 요약에서 요구할 경우 /reload-plugins을 실행합니다.
단일 스킬에 대한 스모크 테스트 작성
스모크 테스트는 알려진 결함이 있는 픽스처(fixture)와 하나의 어설션(assertion)을 대상으로 실행하는 스크립트 기반 에이전트 실행입니다. Claude Code는 -p 옵션과 함께 비대화형으로 실행되며, 사용자가 호출하는 스킬도 여기서 작동합니다. 프롬프트 문자열에 /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은 의도적인 결함이 하나 포함된 짧은 파일입니다. 어설션은 스킬이 해당 결함을 식별하는지 확인하는 것입니다. jq -e는 필터가 null를 생성할 때 0이 아닌 값으로 종료되므로, 주입된 결함을 더 이상 잡아내지 못하는 스킬은 스크립트 실패를 유발합니다. claude 자체도 실행이 실패하면 0이 아닌 값으로 종료되며, set -euo pipefail은 두 경우 모두를 테스트 실패로 처리합니다.
모델은 실행할 때마다 답변을 다르게 재구성하므로 전체 문장을 기준으로 어설션을 작성해서는 안 됩니다. 스킬이 출력해야 하는 식별자나 요청한 스키마의 필드를 기준으로 어설션을 작성하고, 실행 비용을 낮게 유지하기 위해 픽스처를 작게 유지하십시오.
CI 환경에서는 --bare을 추가하십시오. 이 옵션이 없으면 claude -p는 실행 중인 머신의 훅, 플러그인, CLAUDE.md을 포함하여 대화형 세션과 동일한 컨텍스트를 로드하므로, 팀원의 개인 설정이 결과에 영향을 줄 수 있습니다. 베어 모드(bare mode)는 모든 자동 탐색을 건너뛰며, 이는 테스트 중인 스킬도 건너뛴다는 의미이므로 해당 스킬을 명시적으로 로드해야 합니다. 또한 베어 모드는 구독 로그인 정보를 읽지 않으므로, 환경 변수에 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--output-format stream-json를 사용하면 실행의 첫 번째 이벤트에서 로드된 플러그인을 보고하고, 로드되지 않은 플러그인에 대한 plugin_errors 배열을 전달합니다. plugin_errors가 비어 있지 않으면 CI 작업을 실패 처리하십시오. 이는 더 이상 존재하지 않는 리비전을 가리키는 핀(pin)을 잡아내며, 그렇지 않을 경우 에이전트가 사용자의 하우스 룰을 조용히 무시하는 것처럼 보일 수 있습니다.
공유된 스킬은 실행 가능한 명령어입니다
두 가지 기능이 이를 문자 그대로 실현하며, 두 기능 모두 파일이 다른 팀에서 제공될 때 중요하게 작용합니다.
첫째, SKILL.md는 모델이 내용을 읽기 전에 셸 명령어를 실행할 수 있습니다. 본문에 다음과 같은 줄이 있으면 전처리 과정이 수행됩니다.
- Current branch: !`git rev-parse --abbrev-ref HEAD`이 명령어는 스킬을 로드하는 머신에서 실행되며, 그 출력 결과가 모델이 받는 텍스트의 플레이스홀더를 대체합니다. 백틱 세 개 뒤에 !을 붙여 연 코드 블록은 여러 명령어를 같은 방식으로 실행합니다. 런타임에 이를 승인하는 절차는 없습니다. 공유된 스킬을 읽는다는 것은 곧 그 안에 포함된 명령어 치환을 읽는다는 의미입니다.
둘째, 프런트매터(frontmatter)를 통해 도구를 사전 승인할 수 있습니다. allowed-tools은 스킬을 호출한 턴 동안 권한 확인 프롬프트 없이 나열된 도구에 대한 접근 권한을 부여합니다. 프로젝트 스킬의 경우, 사용자가 해당 폴더에 대한 워크스페이스 신뢰 대화 상자를 수락하면 이 권한 부여가 효력을 발휘합니다. Claude Code 문서에는 그 결과가 명확히 명시되어 있습니다. 저장소를 신뢰하기 전에 프로젝트 스킬을 검토하십시오. 스킬이 스스로 광범위한 도구 접근 권한을 부여할 수 있기 때문입니다.
따라서 스킬 업데이트는 의존성 업데이트와 동일하게 취급해야 합니다. 태그는 이동할 수 있고 브랜치는 정의상 계속 변하므로, 메커니즘이 허용하는 한 정확한 커밋 해시로 고정하십시오. 보안이 강화된 머신에서는 설정의 "disableSkillShellExecution": true을 통해 모든 명령어 치환을 실행하는 대신 문자 그대로의 텍스트인 [shell command execution disabled by policy]로 대체할 수 있으며, 관리형 설정을 통해 적용하면 사용자가 이를 재정의할 수 없습니다. 번들로 제공되거나 관리되는 스킬은 이 설정에서 제외됩니다.
스킬이 읽는 대상에 대해서도 동일한 주의가 필요합니다. env을 실행하거나 설정 파일을 여는 스킬은 발견한 모든 내용을 모델의 컨텍스트로 가져오며, 이는 실행 중인 에이전트가 비밀 정보를 다루지 않도록 관리하기에서 다룬 실패 사례와 같습니다. 페이지를 가져오거나 쿼리를 실행하는 스킬은 외부를 향한 동일한 노출 위험을 가집니다. 검색된 텍스트는 사용자가 작성한 지침과 똑같은 모습으로 컨텍스트에 포함되기 때문입니다. 이 경계에 대해서는 웹 검색을 위해 에이전트를 자신의 SearXNG 인스턴스에 연결하기를 읽어보고 숙지하는 것이 좋습니다.
버전 업데이트 시 확인해야 할 사항
- 모든
SKILL.md본문의 diff를 확인하십시오. 해당 텍스트는 에이전트가 따르게 될 지침입니다. - 모든 명령 치환(command substitution)을 확인하십시오. 스킬이 로드될 때 사용자의 머신에서 실행되기 때문입니다.
allowed-tools에 대한 모든 변경 사항을 확인하십시오. 해당 행은 프롬프트 없이 도구 사용 권한을 부여합니다.- 태그 뒤에서 실행되는 테스트를 확인하십시오. 공유 저장소가 CI에서 자체적인 스모크 테스트를 실행한다면, 고정하려는 태그에 성공(green)한 실행 결과가 포함되어 있어야 합니다.
10분 안에 전체 diff를 읽을 수 없는 리뷰어는 너무 커져 버린 스킬을 보고 있는 것입니다. 스킬을 분할하십시오. 에이전트가 읽는 저장소 문서에도 동일한 논리가 적용됩니다. 영구적인 규칙은 AGENTS.md와 HUMAN.md 분할에 설명된 파일에 유지하고, 아키텍처 관련 근거는 에이전트를 위해 작성된 DESIGN.md에 기록하며, 스킬은 좁은 범위의 절차로 유지하십시오.
모델이나 도구 변경으로 스킬이 작동하지 않을 때
스킬을 직접 수정하지 않아도 내부적으로 여러 요소가 변경될 수 있습니다. 모델이 업그레이드되면 긴 지시 사항을 따르는 신뢰도가 달라지므로, 9단계까지 도달하는 것에 의존하던 스킬이 더 이상 작동하지 않을 수 있습니다. 명령줄 도구에서 플래그 이름이 바뀌면 에이전트는 이전 플래그를 실행하고 오류를 읽은 뒤 임기응변으로 대응하게 됩니다. 참조된 URL이 404를 반환하기 시작할 수도 있습니다. 에이전트 하네스가 스킬을 선택하는 방식이 변경되어, 이전에는 선택되었던 description이 더 이상 선택되지 않을 수도 있습니다.
이러한 이유로 이 체계에서는 스모크 테스트가 매우 중요합니다. 각 스킬의 테스트를 푸시할 때뿐만 아니라 정기적인 일정에 따라 실행하십시오. Google이 전체 라이브러리를 대상으로 매주 평가 작업을 수행하는 이유도 바로 이것이며, 10개 정도의 스킬을 운영하는 팀이라면 소규모 VPS에서 매주 cron 작업을 실행하는 것만으로도 충분합니다. 개발자가 문제를 발견하기 전에 고장 사실을 파악할 수 있는 유일한 방법입니다.
이식성 또한 도움이 됩니다. Agent Skills 사양은 프런트매터를 6개의 키로 제한하므로, 해당 사양에 맞춰 작성된 스킬은 작성 시 사용한 도구 외의 다른 도구에서도 로드됩니다. 반면, 하네스별 키를 추가할 때마다 특정 벤더에 의존하게 됩니다. 모델 교체 후에도 살아남는 스킬을 작성하는 것은 별도의 기술이며, 모든 모델에서 스킬이 작동하도록 만들기에서 다룹니다.
FAQ
여러 저장소에서 하나의 에이전트 스킬을 공유하려면 어떻게 해야 합니까?
스킬을 별도의 git 저장소에 넣고 릴리스 태그를 지정하십시오. 각 프로젝트에서 파일을 복사하는 대신 해당 태그를 참조하게 합니다. 두 가지 방법이 있습니다. git submodule은 정확한 커밋을 기록하며, .claude/skills/<name>에서 submodule로 심볼릭 링크를 걸면 일반 프로젝트 스킬처럼 불러올 수 있습니다. 플러그인 마켓플레이스는 /plugin를 통해 동일한 작업을 수행하며, 소비하는 저장소의 .claude/settings.json에 고정 버전을 선언합니다. 두 방법 모두 git 기록에 버전을 남기므로, 특정 에이전트 실행이 어떤 지침에 의해 수행되었는지 확인할 수 있습니다.
에이전트 스킬을 특정 버전으로 고정할 수 있습니까?
SKILL.md 내부에서는 불가능합니다. 해당 frontmatter에는 version 키가 없기 때문입니다. 고정은 파일 외부 계층에서 이루어져야 합니다. git submodule은 설계상 정확한 커밋을 고정합니다. Claude Code 플러그인 마켓플레이스에서 플러그인 소스는 브랜치나 태그에 대해 ref를, 정확한 커밋에 대해 sha를 허용하며, 둘 다 존재할 경우 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에서도 변경 없이 로드됩니다. 특정 환경 전용 키나 사양을 벗어난 본문 기능은 다른 곳에서 무시되거나 거부되므로, 널리 공유하려는 스킬에는 포함하지 마십시오.