에이전트 스킬을 정확한 버전으로 고정하는 방법

단순히 위치가 아니라, 그 내용의 지문(fingerprint)을 통해 스킬을 고정해야 합니다. 파일을 확인하고 그 지문을 기록하는 도구를 사용하여 정확한 버전으로 설치하고, 이 내용을 커밋할 수 있는 잠금 파일(lockfile)을 만드세요. 그런 다음 의도적으로 변경 사항을 확인하고 업데이트하기 전에 무엇이 바뀌었는지 읽어보세요. 이를 위해 mdr add, mdr outdated, 그리고 mdr diff를 사용하는 mdr 도구가 있습니다.

이는 중요합니다. 왜냐하면 이러한 파일들이 변하기 때문입니다. 레지스트리가 자체적으로 수집한 47,724개의 에이전트 마크다운 파일을 최소 14일 동안 모니터링한 결과, 그중 적어도 19.9%가 수집된 지로부터 14일 이내에 GitHub에서 변경되었습니다(SKILL.md 파일의 경우 19.4%). 또한 저희는 다섯 개의 Anthropic 스킬(자주 변경되는 특성 때문에 선택됨)을 살펴보았는데, 다른 저장소에서 발견된 총 75개의 정확한 바이트 복사본 중 47개(62.7%)가 이전 버전이었습니다. 경로를 통해 스킬을 로드하는 에이전트는 오늘 파일에 적힌 내용을 읽습니다. 이 수치와 측정 방법은 State of agent markdown, September 2026에서 확인할 수 있습니다.

| Kind | Watched 14+ days | Changed within 14 days | Share |
| --- | --- | --- |
| SKILL.md | 42,581 | 8,272 | 19.4% |
| ... |
어떤 종류의 에이전트 마크다운 파일이 인덱싱된 지로부터 14일 이내에 상류(upstream)에서 얼마나 자주 변경되었는지 보여줍니다 (하한선; 최소 14일 동안 모니터링된 파일만 계산). 레지스트리 크롤 데이터는 2026년 9월 27일에 동결되었으며, 방법 및 다운로드는 보고서에서 확인할 수 있습니다.

아래의 모든 명령어는 2026년 9월 27일의 실시간 레지스트리를 대상으로 실행되었으며, 출력은 표시된 대로입니다. CLI는 mdr CLI 페이지에서 설치하세요.

에이전트 스킬을 정확한 버전으로 고정하려면 어떻게 해야 하나요?

특정 버전으로 설치하고 그 내용물에 대한 지문(콘텐츠 해시)을 기록해야 합니다. mdr를 사용하면 mdr add owner/repo/[skill@version] 형식으로 실행할 수 있습니다 (mailto:skill@version). 이는 해당 버전의 파일을 GitHub의 소스 커밋에서 가져와, 무언가를 쓰기 전에 모든 파일이 게시된 지문과 일치하는지 확인합니다. mdr.lock에는 버전, SKILL.md의 SHA-256 해시값, 그리고 소스 커밋이 기록됩니다. 200개 이상의 파일을 가진 스킬은 거부되며 아무것도 작성되지 않습니다. 레지스트리가 인덱싱한 공개 스킬과 각 버전은 the SKILL.md page에 나열되어 있습니다.

$ mdr add anthropics/skills/skill-creator@git:20260225.3d59511 --dir skills/skill-creator
installed anthropics/skills/skill-creator@git:20260225.3d59511  18 files (18 hash-verified)  audit A  to skills/skill-creator

이 예시는 skills/skill-creator에 설치되므로 아래의 모든 경로가 읽기 쉽습니다. --dir 없이 실행하면 mdr는 에이전트가 스킬을 로드하는 위치, 즉 기본적으로 .claude/skills/<name> 또는 --agent codex, cursor 또는 opencode에 대한 일치하는 디렉토리에 설치합니다.

버전 레이블은 스킬의 프런트매터(frontmatter)에 있는 version (또는 metadata.version)이며, 숫자로 시작할 때는 앞에 v가 추가되고, 버전이 선언되지 않은 경우 여기처럼 커밋 날짜와 짧은 해시값이 사용됩니다. 선언된 버전은 여러 커밋에 걸쳐 반복될 수 있으므로, 두 버전이 같은 레이블을 공유하는 경우에는 콘텐츠 해시로 고정해야 합니다: mdr add owner/repo/skill@sha256:<prefix>. mdr info owner/repo/skill는 날짜, 커밋 및 감사 등급과 함께 최근 버전을 나열합니다.

agent 스킬에 대한 lockfile이 package-lock.json처럼 있나요?

네, mdr는 사용자가 실행하는 폴더에 mdr.lock이라는 작은 JSON 파일을 작성합니다. 이 파일에는 각 스킬의 버전 레이블, SHA-256 지문(fingerprint), 소스 커밋 및 설치 경로가 기록됩니다. 이를 저장소(repository)에 커밋하세요. mdr install은 정확히 그 내용을 다시 다운로드하고 확인한 후 설치하므로, 정확하게 설치되거나 실패합니다. GitHub의 gh 스킬은 다르게 작동합니다. 이는 태그나 커밋에 고정하며, 별도의 잠금 파일(lockfile)이 아닌 각 SKILL.md 내부에 git tree SHA를 기록합니다.

{
  "version": 1,
  "registry": "https://markdownregistry.com",
...

sha256은 해당 버전의 스킬 SKILL.md에 대한 해시 값이며, verified는 무언가를 작성하기 전에 확인된 파일 바이트 수를 나타냅니다. 만약 어떤 파일이라도 일치하지 않으면 아무것도 작성되지 않습니다.

설치된 에이전트 스킬이 오래되었는지 어떻게 확인하나요?

mdr outdated을 실행하세요. 이 명령어는 GitHub에서 SKILL.md가 변경된 모든 고정(pinned) 스킬 목록과 새로운 버전 및 해당 감사 등급(audit grade)을 보여줍니다. 만약 하나라도 변경되었거나 제거되었다면 상태 코드 2로 종료되므로, 자동화 빌드에서 실패할 수 있습니다. 공개 스킬의 경우, SKILL.md를 건드리지 않은 다른 파일의 변경은 감지되지 않습니다. mdr verify --min-grade A는 레지스트리(registry)가 더 이상 고정된 버전을 찾을 수 없거나 해당 등급이 최소 등급보다 낮은 경우 실패합니다. 스킬을 고정하기 전에 파일의 등급을 확인하려면, GitHub 링크를 체커에 붙여넣으세요.

$ mdr outdated
anthropics/skills/skill-creator  git:20260225.3d59511 to git:20260306.b0cbd3d  audit A  (2026-03-06)  mdr diff anthropics/skills/skill-creator
$ echo $?
...

$ mdr verify --min-grade A
✓ anthropics/skills/skill-creator  git:20260225.3d59511  audit A (>= A)  sha256:ba8bebb2c085
...

에이전트 스킬을 업데이트하기 전에 무엇이 변경되었는지 어떻게 확인하나요?

mdr diff owner/repo/skill을 실행하세요. 이는 사용자가 고정(pinned)한 버전부터 최신 버전까지 skill의 SKILL.md에서 변경된 라인을 보여주며, 뒤처져 있는 경우에 유용합니다. 두 버전을 비교하려면 두 개의 버전 레이블을 추가하세요. 이 명령어는 scripts와 같은 skill의 다른 파일들은 보여주지 않습니다. 해당 파일을 보려면 두 소스 커밋을 비교해야 합니다: mdr.lock은 사용자의 버전을 기록하고, mdr info owner/repo/skill은 각 최근 버전의 짧은 커밋 해시를 나열합니다.

$ mdr diff anthropics/skills/skill-creator
anthropics/skills/skill-creator: git:20260225.3d59511 to git:20260306.b0cbd3d  +8 -2
- description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, ...
...

긴 설명 라인은 여기에서 잘렸으며, 실제 출력에서는 전체 내용을 인쇄하고 그 뒤에 SKILL.md의 다른 변경된 라인들이 이어집니다. 이 두 버전 사이에는 skill의 Python 스크립트 중 두 개(improve_description.py는 51줄 추가 및 52줄 제거, run_loop.py는 4줄 제거)도 상위(upstream)에서 변경되었지만, mdr diff는 이를 보여주지 않습니다: 해당 파일들을 보려면 skill의 저장소 클론에서 git diff 3d59511 b0cbd3d -- skills/skill-creator를 실행하세요.

로컬 수정을 잃지 않고 설치된 스킬을 업데이트하는 방법은 무엇인가요?

mdr는 로컬 수정을 병합(merge)하지 않습니다. mdr update는 새 버전이 배포하는 모든 파일을 덮어쓰기(overwrite)하므로, 그 중 하나에 있는 수정 사항은 손실되며, 파일 삭제 기능이 없으므로 상위에서 제거된 파일은 사용자가 직접 제거할 때까지 남아 있습니다. 가장 안전한 방법은 설치된 스킬을 편집하지 않는 것입니다: 변경이 필요하다면, 그것을 소유하는 디렉터리 내의 새 이름으로 복사하고 그 사본을 유지하세요. 이미 수정했다면, 업데이트하기 전에 skill 디렉터리를 따로 옮겨 놓으세요(가장 최근 백업부터 제거). mdr update를 실행한 다음, 두 버전을 git diff --no-index로 비교하여 수동으로 변경 사항을 가져오세요. mdr install 역시 로컬 수정을 동일하게 덮어씁니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

$ rm -rf skill-creator.mine && mv skills/skill-creator skill-creator.mine
$ mdr update anthropics/skills/skill-creator
installed anthropics/skills/skill-creator@git:20260306.b0cbd3d 18 files (18 hash-verified) audit A to skills/skill-creator
...

우리는 이 과정을 2026년 9월 27일에 연속으로 두 번 실행했습니다 (1ed29a0에서 3d59511로, 그리고 여기 표시된 최신 업데이트까지). 첫 번째 실행 후에는 LICENSE.txt를 수정했고, 두 번째 실행 전에는 SKILL.md에 새로운 수정을 가했습니다. 이 두 수정 사항은 모두 나중에 skill-creator.mine에 포함되었고, 새 설치는 깨끗하게 이루어졌습니다. 만약 mdr update가 실패하면 디렉토리를 원래 위치로 옮기세요. 복사(copy)하는 대신 이동(move)해야 합니다. 왜냐하면 복사는 다음 업데이트에서 이전 백업 내부에 중첩되어 저장되고, 업스트림(upstream)이 제거한 파일을 숨기기 때문입니다. 반면 이동은 비교 과정에서 그 차이를 보여줍니다. 이 비교 목록에는 사용자의 수정 사항과 mdr diff가 표시하지 않는 두 개의 스크립트를 포함하여 모든 업스트림 변경 사항이 나열됩니다. 라인별로 확인하려면 --stat을 제거하세요. skill-creator.mine에만 나타나는 파일은 사용자가 추가한 것이거나, 아니면 업스트림에서 제거된 것 중 하나입니다. 어떤 것인지 알려면 mdr info와 소스 커밋(source commits)을 확인하세요. 두 디렉토리가 다를 경우 git diff --no-index는 상태 1로 종료되는데, 이는 여기서는 예상되는 결과입니다. 또한 우리는 git 히스토리에서 만든 패치로 수정 사항을 자동으로 가져오는 것도 시도해 보았지만, 여러 일반적인 히스토리(두 번째 업데이트, 공유 잠금 파일, 스쿼시 병합 등)에서 이 수정 사항이 손실되었기 때문에 권장하지 않습니다.

mdr, gh skill, 또는 파일을 복사하는 방법

GitHub의 CLI는 2026년 4월에 공개 프리뷰(public preview)로 gh skill을 추가했으며, 이는 GitHub 변경 로그에서 설명된 자체 고정 방식이 있습니다. 스킬 파일들을 사용자의 저장소에 복사하는 것이 세 번째 옵션입니다. 이들이 어떻게 다른지 살펴보겠습니다:

출처 (Sources)

• GitHub changelog: GitHub CLI로 에이전트 스킬 관리하기

최종 확인일 2026년 9월 27일. 페이지: https://markdownregistry.com/guides/pin-agent-skills

처음 게시됨 markdownregistry. 다른 가이드(AGENTS.md, CLAUDE.md, 스킬 보안 및 스킬 찾기)는 markdownregistry.com/guides에 있습니다.