2026년 7월 기준. 제품과 CLI의 경로·옵션은 이후 변경될 수 있다.
에이전트에 스킬을 추가하는 일은 쉽다. 반복해서 설명하던 코드 리뷰 기준, 문서 작성 방식, 배포 절차, 디자인 시스템 사용법을 SKILL.md에 적고 에이전트가 읽는 디렉토리에 두면 된다. 스킬 생성기를 사용하면 디렉토리 구조와 frontmatter까지 자동으로 만들 수 있고, 다른 사람이 공개한 스킬은 명령 한 줄로 설치할 수도 있다. 한 번 만들어 두면 매번 같은 프롬프트를 다시 작성하지 않아도 되므로, 스킬을 만드는 비용에 비해 얻는 편익은 크다.
문제는 설치된 스킬이 많아질수록 에이전트가 관측해야 하는 스킬의 표면도 함께 커진다는 점이다. 물론, Agent Skills는 progressive disclosure 방식으로 동작한다. 에이전트가 세션을 시작할 때 모든 SKILL.md의 본문과 부속 파일을 한꺼번에 읽는 것이 아니라, 우선 각 스킬의 이름과 설명 같은 metadata를 보고 현재 작업과 관련 있는 스킬을 고른다. 선택된 뒤에야 해당 SKILL.md의 본문을 읽고, scripts/, references/, assets/ 같은 부속 리소스는 실제로 필요할 때 추가로 연다(ref2).
하지만 그럼에도 불구하고 초기 목록조차 비용을 가진다. 모델이 적절한 스킬을 고르려면 최소한 어떤 스킬들이 존재하는지, 각각이 언제 쓰이는지를 나타내는 정보가 컨텍스트에 들어가야 한다. 실제로 Codex는 사용 가능한 스킬의 초기 목록이 모델 컨텍스트 윈도우의 2%, 컨텍스트 크기를 알 수 없을 때는 8,000자를 넘지 않도록 제한한다(ref3). 생각보다 그 한도에 금방 다다른다.
스킬을 직접 만드는 비용이 낮다는 사실뿐 아니라, Figma나 Hyperframes 같은 특정 제품·프레임워크를 지원하는 기능 하나를 추가한다고 생각할 수 있지만, 실제 패키지 안에는 서로 다른 역할의 스킬이 함께 들어 있기 때문에 관측 가능한 skill surface가 금방 불어나기 때문이다. 그래서 이 글에서는 스킬의 visibility에 대해 다룬다.
하지만 visibility를 다룰 땐 업데이트 문제도 함께 다루어야 한다. 스킬의 visibility는 스킬이 물리적/논리적으로 어디에 위치해 있는가로 결정되는 경우가 많은데, 위치 이동에 따라 업데이트의 책임이 달라지기 때문이다. 실제로 사용자가 스킬을 바라보는 적절 사용 범위는 시간이 지나면서 달라진다. 처음에는 어느 디렉토리에서 에이전트를 실행하든 보이도록 홈 디렉토리 아래에 두었지만, 실제로 사용해 보니 특정 repository에서만 필요한 스킬일 수 있다. 반대로 한 프로젝트를 위해 만들었던 스킬이 다른 프로젝트에서도 계속 쓰이면서 어디에서나 보이는 위치로 옮길 가치가 생길 수도 있다.
이렇게 스킬 visibility는 최초 설치 때 한 번 결정하고 끝나는 속성이 아니다. 스킬을 만들고, 사용하고, 범위를 좁히거나 넓히고, 필요하면 숨기는 과정이 계속된다. 그런데 스킬의 물리적 위치를 바꾸면 에이전트가 그것을 발견하는 범위는 즉시 달라지는 반면, 그 스킬을 설치하고 업데이트하던 도구가 같은 이동을 자동으로 이해하는 것은 아니다. 파일은 새 위치에서 잘 보이는데 updater의 lockfile은 예전 프로젝트에 남아 있거나, plugin manager는 여전히 기존 bundle version을 설치 상태로 기억할 수 있다.
그래서 이 글에서 다루려는 것은 어디에서(visibility), 어떻게 업데이트하냐(update R&R)다.
여기서 말하는 스킬은 모델이 가진 능력을 일반적으로 부르는 표현이 아니라, SKILL.md를 중심으로 instructions, scripts, references, assets를 묶는 파일 기반 형식을 뜻한다. 이 형식은 Anthropic이 2025년 10월 16일 Claude의 Skills 기능으로 먼저 공개했다. Anthropic은 같은 해 12월 18일 이를 cross-platform portability를 위한 공개 표준인 Agent Skills로 발표했다(ref1). Claude 안에서 시작한 workflow packaging 형식을 특정 제품에만 묶어두지 않고, 다른 agent host도 같은 디렉토리 구조와 metadata contract를 읽을 수 있게 하려는 흐름이었다. OpenAI의 Codex 문서 역시 현재의 skill 기능이 이 open Agent Skills standard를 기반으로 한다고 설명한다(ref3).
표준화의 대상은 단일 스킬과 artifact의 형식이다. 최소한 SKILL.md를 가진 디렉토리라는 점, SKILL.md 앞부분에 이름과 설명 같은 metadata가 있다는 점, 필요에 따라 실행 코드와 참고 자료를 함께 묶을 수 있다는 점, 그리고 metadata에서 instructions와 resources로 점진적으로 내용을 공개한다는 점이 공통 계약이 된다. 스킬 하나의 전형적인 구조는 다음과 같다.
my-skill/
├── SKILL.md # 필수: metadata와 instructions
├── scripts/ # 선택: 실행 가능한 코드
├── references/ # 선택: 상세 문서와 참고 자료
├── assets/ # 선택: 템플릿과 정적 리소스
└── ...
SKILL.md는 YAML frontmatter와 Markdown 본문으로 구성된다. name은 스킬의 식별자이고, description은 에이전트가 이 스킬을 언제 후보로 올릴지 판단하는 핵심 metadata다. 본문에는 실제 작업 절차를 적는다. 길고 세부적인 문서는 references/로, 결정적으로 실행돼야 하는 작업은 scripts/로 분리할 수 있다. 이 구조 덕분에 에이전트는 처음에는 작은 metadata만 보고, 선택된 스킬에 대해서만 더 많은 내용을 읽는다(ref2).
반면 어떤 디렉토리를 검색할지, 동일한 이름의 스킬이 겹쳤을 때 무엇을 우선할지, 사용자가 어떤 방식으로 스킬을 끄고 켤지는 각 agent host가 정한다(ref2). Agent Skills가 공개 표준이라고 해서 모든 도구가 동일한 설치 경로와 동일한 scope hierarchy를 사용한다는 뜻은 아니다.
이제 스킬 관리에서 서로 다른 세 가지를 분리해 볼 수 있다. 첫째, SKILL.md와 부속 파일로 구성된 artifact가 있다. 둘째, 에이전트가 어느 작업 범위에서 그 artifact를 발견할지 정하는 visibility scope가 있다. 셋째, artifact가 어디에서 왔고 누가 어떤 버전을 다시 가져올지 정하는 installation and update mechanism이 있다. 같은 artifact도 다른 디렉토리로 옮기면 scope가 달라질 수 있고, 같은 디렉토리에 있는 artifact도 copy, Git clone, installer, plugin 가운데 무엇으로 가져왔는지에 따라 업데이트 책임이 달라진다.
추상적으로 보면 홈 디렉토리 아래의 agent 전용 skill path에 놓인 스킬은 사용자의 모든 작업 공간에서 보이고, repository 내부의 agent 전용 skill path에 놓인 스킬은 그 repository에서만 보인다. 다만 실제 경로와 공식 명칭은 제품마다 다르다.
Claude Code는 다음 위치를 사용한다.
Personal
~/.claude/skills/<skill-name>/SKILL.md
Project
<repo>/.claude/skills/<skill-name>/SKILL.md
Claude Code에서 personal skill은 해당 사용자의 모든 프로젝트에 적용되고, project skill은 해당 프로젝트에서만 적용된다. Claude Code 문서가 이를 가장 간결하게 표현하는 문장은 “스킬을 어디에 저장하느냐가 누가 사용할 수 있는지를 결정한다”는 것이다(ref4).