작성자 여러 리포지토리에서 에이전트 스킬 공유 및 관리 방법
에이전트 스킬을 여러 리포지토리에 복사하면 버전 불일치가 발생합니다. 스킬을 의존성처럼 관리하여 중앙 리포지토리에 저장하고, 각 프로젝트가 특정 버전을 고정 및 검토하도록 설정하는 효율적인 운영 방안을 상세히 설명합니다.
리포지토리 간에 에이전트 스킬을 공유하는 방법
리포지토리 간에 에이전트 스킬을 공유하려면 파일을 복사하는 방식을 중단하고 의존성을 설정해야 합니다. 하나의 스킬 리포지토리를 유지하고 태그를 지정한 뒤, 각 프로젝트가 특정 태그를 고정(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)에서는 lock 파일에 기록된 모든 스킬을 재설치하여 다른 기기에서도 동일한 환경을 구성할 수 있도록 하는 skills install 명령을 요구하고 있습니다. 이 요청을 현재 진행 상황에 대한 보고서로 이해하면 됩니다. Lockfile 개념은 확립되었으나, 프로젝트별 관리 기능은 아직 개발 중입니다.
Specs and tests. SkillSpec은 다른 접근 방식을 취합니다. 이 도구는 SKILL.md을 신뢰해야 할 설명이 아닌 검증해야 할 계약으로 간주하며, 스킬을 "추적 가능하고, 테스트 가능하며, 증명 가능하게" 만드는 것을 목표로 합니다. skillspec doctor <path>은 에이전트가 작업을 중단할 가능성이 있는 지점을 보고합니다. skillspec boundary map <path>는 스킬이 접근할 수 있는 범위를 보고하며, skillspec boundary assess <path>은 이러한 결과를 위험도에 따라 정렬합니다. 이 도구는 Rust 크레이트로, 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에 설정된 이전 버전의 바이너리가 우선 적용되고 있다는 의미입니다.
Vendor practice. Google은 google/skills에서 스킬을 빌드하는 방법을 에이전트 스킬의 빌드, 테스트 및 확장 방식에 관한 게시물을 통해 설명했습니다. 규모를 제외하고 보면 이 메커니즘은 일반적인 지속적 통합(CI)과 같습니다. 모든 스킬은 병합되기 전에 frontmatter 메타데이터, 줄 수, 디렉터리 레이아웃, 명명 규칙에 대한 린터 검사를 통과해야 합니다. 링크 검사기는 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를 허용하며 sha는 허용하지 않습니다. 카탈로그 내부의 플러그인 소스는 둘 다 허용하며, 두 값이 모두 설정된 경우 sha이 우선 적용됩니다. 따라서 정확한 커밋 고정(exact-commit pin)은 카탈로그 항목에 지정해야 합니다.
각 소비 저장소는 커밋된 .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) 모드는 모든 자동 탐색을 건너뛰며, 이는 테스트 중인 스킬도 건너뛴다는 의미이므로 해당 스킬을 명시적으로 로드해야 합니다. 또한 베어 모드는 구독 로그인 정보를 읽지 않으므로, 환경 변수에 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 작업을 실패 처리하십시오. 이는 더 이상 존재하지 않는 리비전을 가리키는 핀을 잡아내며, 그렇지 않을 경우 에이전트가 내부 규칙을 조용히 무시하는 것처럼 보일 수 있습니다.
공유된 스킬은 실행 가능한 명령어입니다
두 가지 기능이 이를 문자 그대로 실현하며, 두 기능 모두 파일이 다른 팀에서 제공될 때 중요하게 작용합니다.
첫째, 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이 더 이상 선택되지 않을 수 있습니다. 절차가 이처럼 조기에 종료되기 시작하면 버전 업데이트만으로는 해결되지 않으며, 마지막 단계까지 강제로 수행하도록 지시 사항 자체에 구조를 부여해야 합니다. 이것이 바로 unlazy 스킬과 Depth Tree 방식의 핵심 접근법입니다.
이러한 환경에서 스모크 테스트가 중요한 역할을 하는 이유가 바로 여기에 있습니다. 각 스킬의 테스트를 푸시할 때뿐만 아니라 정기적인 일정에 따라 실행하십시오. 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에서도 수정 없이 로드됩니다. 사양 외의 특정 환경용 키나 본문 기능은 다른 곳에서 무시되거나 거부되므로, 널리 공유하려는 스킬에는 포함하지 마십시오.