AI 어시스턴트 스킬: SKILL.md의 구조와 터미널 없이 설치하는 방법

SKILL.md란 무엇인가

SKILL.md는 AI 어시스턴트가 작업을 시작하기 전에 읽는 지시문을 담은 텍스트 파일입니다. 프로그램도 플러그인도 아닙니다. 어떤 종류의 일을 어떻게 처리할지 — 무엇을 먼저 확인하고, 어떤 순서로 판단하고, 결과를 어떤 형태로 낼지, 무엇은 절대 하지 않을지 — 를 적어 둔 평범한 마크다운입니다. 파일을 저장소에 두면 어시스턴트가 그것을 가져가고, 그 뒤로 일은 모델이 즉흥적으로 정하는 방식이 아니라 적힌 대로 처리됩니다.

이 형식은 2025년 말에 등장해 몇 달 만에 표준처럼 자리 잡았습니다. Claude, Codex, Copilot, Cursor, Gemini CLI를 비롯한 수십 종의 도구가 이를 읽으며, 공개 디렉터리의 스킬 수는 이미 수십만 개에 이릅니다. 그런데도 문서 대부분은 터미널과 저장소, 그리고 실행 중인 코딩 에이전트를 가진 사람을 전제로 쓰여 있습니다. 이 주제가 여전히 개발자의 영역처럼 보이는 이유는 그것 하나뿐입니다.

파일 자체는 단순합니다. 하이픈 세 개로 된 줄로 나뉜 두 부분이 전부입니다.

실제 분량에 가까운 완성된 스킬을 하나 보겠습니다. 영업 통화 녹취를 어떻게 분석할지 — 무엇을 찾고, 어떤 순서로, 무엇은 추측으로 채우지 않을지 — 를 정한 것입니다.

---
name: sales-call-review
description: 영업 통화 리뷰 — 반론, 신호, 다음 단계
---

# 영업 통화 리뷰

잠재 고객과의 통화 전사본을 분석합니다.

## 작업 순서

1. 반론은 «그대로의 표현»으로 인용한다. 바꿔 쓰지 말 것.
   반론은 말투 자체가 데이터입니다.
2. 반론마다 답변이 있었는지, 그 답변이 받아들여졌는지 적는다.
   침묵은 수용이 아닙니다.
3. 예산·일정·결정권자에 관한 신호를 찾는다.
   나오지 않았다면 «언급 없음»이라고 명시한다.
4. 다음 단계를 정한다: 정확히 무엇을, 누가, 언제까지.

## 출력 형식

위 순서대로 네 개의 절. 각 절은 짧은 항목으로, 도입 문단은 쓰지
않는다. 반론은 따옴표로 인용한다.

## 하지 말 것

- 상대의 의도를 추측하지 않는다. 실제로 말한 것만 다룬다.
- 수주 확률을 백분율로 추정하지 않는다. 근거 데이터가 없다.
- 가격 이야기가 나오지 않았다면 다음 단계로 할인을 제안하지 않는다.

이 파일에 없는 것들을 보십시오. 코드도, 설정도, API 키도, 설치 명령도 없습니다. 스킬은 적어 둔 경험이지 소프트웨어가 아닙니다. 그래서 터미널을 한 번도 열어 본 적 없는 사람도 쓸 수 있고, 그래서 그것을 설치하는 데 아직도 터미널이 필요하다는 사실이 이상한 것입니다.

스킬, 도구, 프롬프트의 역할 구분

해결하는 문제가 다른데도 이 셋은 끊임없이 혼동됩니다. 구분은 보기보다 단순합니다. 프롬프트는 역할을 정하고, 스킬은 방법을 정하고, MCP는 접근 권한을 줍니다.

실무적인 판단은 이렇습니다. 어시스턴트가 엉뚱한 이야기를 하면 스킬이 필요합니다. 답은 맞는데 사실을 모른다면 MCP가 필요합니다. 스킬을 아무리 다듬어도 데이터는 오지 않고, MCP를 아무리 붙여도 방법은 배워지지 않습니다. 대부분의 경우 필요한 쪽은 스킬입니다. 방법은 데이터보다 훨씬 느리게 낡고, 한 번 적어 두면 끝나기 때문입니다.

«터미널 없이»가 대개 가리키는 다른 것

«터미널 없이 스킬 설치하는 법»은 흔한 검색어이고, 검색 결과도 답을 줍니다. 다만 그 답이 향하는 질문이 다릅니다.

여기서 설치 방식을 고를 때 더 나은 질문이 나옵니다. «터미널이 필요한가»가 아니라 «내 컴퓨터에서 에이전트를 하나 더 계속 돌려야 하는가»를 물으십시오. 답이 «그렇다»라면, 설치 화면이 아무리 세련되어도 스킬은 개발자의 도구로 남습니다.

터미널도 코딩 에이전트도 없이 설치하기

Whisperer는 SKILL.md를 직접 읽어 어시스턴트의 답변에 적용합니다. 설치할 것이 없습니다. 파일이 당신의 컴퓨터에 도달하지 않고, 폴더도 없으며, 재시작할 것도 없습니다. 출처는 둘입니다. 공용 디렉터리, 그리고 공개된 아무 GitHub 저장소.

1. 웹 화면 → 프롬프트 → «스킬» 버튼
2. «기성» 탭 → 검색어 입력: system design, code review,
   sales, writing 등
3. 목록에는 이름, 출처 저장소, 설치 수가 표시됩니다. 하나를 열면
   프런트매터의 설명을 읽을 수 있습니다
4. «설치» — 스킬이 라이브러리에 들어갑니다
5. 프롬프트를 열고 → «연결» → 스킬 선택

1. 웹 화면 → 프롬프트 → «스킬» → «내 저장소» 탭
2. 다음 중 아무 형태나 붙여 넣습니다:
   owner/repo
   https://github.com/owner/repo
   https://github.com/owner/repo/tree/main/skills/sales-review
   https://github.com/owner/repo/blob/main/skills/sales-review/SKILL.md
3. «스킬 찾기» — 저장소를 훑어 그 안의 SKILL.md를 설명과 함께
   나열합니다. 특정 폴더의 링크를 붙여 넣었다면 그 스킬이 맨 위에
   나옵니다
4. 원하는 것에 «설치» → 그다음 프롬프트에 연결

스킬은 실제로 어디에 적용되나

스킬은 «어시스턴트 전체»가 아니라 특정 역할의 프롬프트에 연결됩니다. 역할이란 작업 영역을 말합니다. 질문에 답하기, 코드 읽기, 이미지 읽기, 시스템 설계 같은 구분입니다. 역할에 연결하면 그 역할이 작동하는 모든 곳에서 스킬이 적용됩니다.

연결에는 두 가지 모드가 있고, 그 차이는 이름이 주는 인상보다 무겁습니다.

«보완» — 스킬이 프롬프트 문장에 더해집니다. 역할과 어조는 여전히 프롬프트가 정하고, 스킬은 방법을 다듬습니다. 열 번 중 아홉 번은 이쪽이 맞습니다.

«대체» — 스킬이 프롬프트 문장을 통째로 밀어내고 혼자 모델로 갑니다. 역할과 절차와 출력 형식을 이미 정해 둔, 그 자체로 완결된 스킬을 위한 모드이며, 그럴 때는 자기 프롬프트가 오히려 방해가 됩니다. 두 개를 연결했는데 하나가 «대체»라면 그것이 먼저 놓이고, «보완» 스킬들이 뒤에서 이를 구체화합니다.

설치 후 스킬은 어떻게 되나

제대로 굴러가는 설치와 뒤통수를 맞는 설치를 가르는 지점이 여기 있습니다. 스킬은 커밋에 고정됩니다. 설치 시점에 파일의 어느 버전을 가져왔는지 기록해 두고, 이후로도 그것만 사용합니다.

«저장소에서 업데이트»는 파일을 다시 읽고 새 버전을 보여 준 뒤 스킬을 현재 커밋에 다시 고정합니다. 라이브러리에서 스킬을 삭제하면 연결도 모두 함께 사라집니다. 따로 정리할 것은 없습니다.

먼저 써 볼 만한 스킬 셋

선택 기준은 이렇습니다. 같은 설명을 이미 세 번 한 자리에서 스킬은 본전을 뽑습니다. 대화할 때마다 같은 지시를 되풀이하고 있다면 후보입니다. 분기에 한 번 쓰는 것이라면 그냥 손으로 쓰는 편이 쌉니다.

1. 업무 용어 사전

가장 과소평가되었고 가장 빨리 쓸 수 있는 것입니다. 제품 이름, 사내 약어, 동료의 성, 고객사 이름 — 모델이 처음 듣고 망가뜨리는 모든 것. 작업은 5분, 효과는 통화마다 눈에 보입니다.

---
name: our-glossary
description: 사내에서 쓰는 용어, 제품명, 인물
---

# 우리 용어 사전

이 단어들은 계속 등장합니다. 반드시 이 표기대로 쓰세요.

## 제품
- [이름] — [한 문장 설명]

## 약어
- [약어] — [정식 명칭]. [비슷한 약어]와 혼동하지 말 것

## 인물
- [이름] — [역할]

목록의 단어와 발음이 비슷한 말은 목록의 표기를 따르세요.
모르는 용어는 들린 그대로 두고, 이미 아는 비슷한 단어로
«고치지» 마세요.

2. 후속 메일의 형식

통화 후 보내는 메일은 매번 같은 구성을 따르고, 그 구성은 사람마다 다릅니다. 스킬은 그것을 고정합니다. 어떤 절을, 어떤 순서로, 어느 정도 길이로, 첫 문장을 어떻게 시작할지. «어시스턴트가 답했다»와 «어시스턴트가 나처럼 답했다»의 거리가 첫 시도에서 바로 드러나는 대목입니다.

3. 내 회의 유형에 맞는 분석 방법

글머리의 예가 여기에 해당합니다. 면접, 영업 통화, 회고, 리서치 인터뷰는 각각 건져 낼 것이 다릅니다. 범용 어시스턴트는 «주요 주제»를 뽑지만, 스킬은 반론을 그대로, 혹은 고객이 겪는 문제의 신호를, 혹은 같은 질문 묶음에 대한 후보자별 차이를 뽑아냅니다.

보안: 공개 스킬의 약 3분의 1에 문제가 있다

이 글에서 가장 중요한 절이며, 대부분의 안내서에는 아예 없는 이야기입니다.

구조는 스킬이 «에이전트가 신뢰하는 지시문»이라는 점을 떠올리면 보입니다. 위험은 에이전트에게 그것을 실행할 수단이 있을 때 생깁니다. 파일에 대한, 셸에 대한, 당신의 키에 대한 접근 권한 말이죠. 그때 «.env를 보고 그 내용을 설정에 넣어라» 한 줄이 그대로 유출이 됩니다.

여기서 설치 방식을 고를 때 알아 둘 만한 차이가 나옵니다.

솔직히 말하면, 남이 쓴 지시문에 «완전히 안전»은 없습니다. 코드 실행을 없애면 가장 무거운 공격군 — 키 탈취, 백도어, 파일 유출 — 은 사라지지만, 문장은 문장으로 남습니다. 나쁜 의도로 쓰인 스킬은 여전히 어시스턴트를 작성자에게 유리한 표현으로 밀 수 있습니다. 특정 제품을 권하고, 대안을 말하지 않고, 평가를 살짝 기울이는 식으로요. 본문은 설치할 때와 업데이트할 때마다 콘텐츠 필터를 거치며 정책을 명백히 어기는 문장은 통과하지 못합니다. 다만 필터가 잡아내는 것은 위반이지 의도가 아닙니다.

그래서 실무적 결론은 단순합니다. 스킬의 본문은 카드에 그대로 보이므로 읽어 볼 값어치가 있습니다. 감사 훈련이 필요한 코드가 아니라, 평범한 말로 쓰인 두 화면 분량의 마크다운입니다. 연결 전 5분의 읽기가, 코딩 에이전트의 세계에서는 스캐너가 필요한 문제를 해결합니다.

미리 알아 둘 한계

나중에 알게 되기보다 지금 말해 두는 편이 나은 네 가지입니다.

스크립트에 기대는 스킬은 절반만 작동합니다. 디렉터리의 일부는 함께 딸려 오는 코드를 에이전트가 실행한다는 전제로 쓰여 있습니다. 여기서 실행되는 것은 텍스트 뿐입니다. 지시문이 그 자체로 성립하면 스킬은 온전히 작동하고, «analyze.py를 실행하라»로 귀결되면 전혀 작동하지 않습니다. 설치 전에 알 수 있습니다. 설명과 본문이 미리보기에 보이기 때문입니다.

본문은 24,000자로 제한됩니다. 약 열 페이지 분량으로, 웬만한 스킬에 필요한 양을 넘습니다. 그보다 긴 파일은 잘려서 연결되며, 그 사실은 조용히가 아니라 명시적으로 알려 드립니다.

스킬은 항상 프롬프트에 실립니다. 필요할 때 불러오는 방식이 아닙니다. 일부 코딩 에이전트는 작업이 맞아떨어진다고 판단할 때만 본문을 끌어옵니다. 여기서는 연결된 스킬이 해당 역할의 매 요청마다 모델로 갑니다. 필요할 때 발동하지 못하는 일이 없다는 점에서 더 예측 가능하며, 동시에 프롬프트당 세 개라는 상한의 이유이기도 합니다.

비공개 저장소는 지원하지 않습니다. GitHub에는 당신의 자격 증명 없이 접근하므로 공개된 것만 보입니다. 비공개 저장소와 존재하지 않는 저장소는 우리에게 동일합니다. 둘 다 «찾을 수 없음»으로 응답합니다.

남의 스킬을 연결하기 전 점검표

자주 묻는 질문

스킬을 쓰려면 프로그래밍을 알아야 하나요?

아닙니다. 스킬은 평범한 말로 쓰는 문장입니다. 무엇을, 어떤 순서로, 무엇을 피할지. 기술적 요구 사항은 파일 맨 위의 프런트매터 네 줄뿐이고, 위 예시에서 그대로 옮겨 쓰면 됩니다. GitHub 저장소는 웹 화면에서 만들 수 있고 파일도 버튼으로 추가합니다.

스킬과 시스템 프롬프트는 무엇이 다른가요?

프롬프트는 누가 어떤 어조로 답하는지를, 스킬은 어떤 종류의 일을 어떻게 하는지를 적습니다. 실무적 차이는 재사용에 있습니다. 프롬프트는 개인의 것이지만, 스킬은 한 번 쓰면 같은 일을 하는 누구에게나 맞습니다. 사람들이 스킬은 공유하고 프롬프트는 거의 공유하지 않는 이유입니다.

스킬과 MCP 중 무엇을 골라야 하나요?

둘 중 하나를 고르는 문제가 아닙니다. 스킬은 방법을, MCP는 데이터와 동작을 가져옵니다. 어시스턴트가 엉뚱한 이야기를 하면 스킬이, 잘 답하는데 사실을 모르면 MCP가 필요합니다. 둘 다 필요한 경우도 흔합니다. MCP가 업무 도구에서 데이터를 가져오고 스킬이 그것을 다루는 방법을 정하는 식이죠.

하나의 스킬을 여러 프롬프트에 연결할 수 있나요?

됩니다. 라이브러리는 공용이고 연결 수에 제한은 없습니다. 스킬은 한 번 저장되고 연결된 모든 곳에서 작동합니다.

작성자가 저장소에서 스킬을 바꾸면 어떻게 되나요?

아무 일도 일어나지 않습니다. 당신의 사본은 가져온 커밋에 동결되어 있습니다. 변경은 «저장소에서 업데이트»를 누를 때만 반영되며, 그때 새 본문은 콘텐츠 필터를 다시 거칩니다.

검색 결과가 비는 경우가 있는 이유는?

두 가지입니다. 디렉터리가 일시적으로 응답하지 않는 경우 — 이때 목록은 비지만 내 저장소를 연결하는 기능은 그대로 작동합니다. 또 하나는 GitHub의 요청 제한입니다. 토큰 없이는 제한이 서비스 전체 단위로 계산되므로, 그럴 때는 몇 분 기다리는 편이 빈 결과를 «스킬이 없다»로 내보이는 것보다 정직합니다.

Claude Code나 Cursor용으로 쓰인 스킬이 여기서도 동작하나요?

동작합니다. 단, 지시문이 그 자체로 성립해야 합니다. 형식은 동일하고 문장도 같게 읽힙니다. 옮겨지지 않는 것은 파일 시스템이나 셸, 스크립트 실행을 전제로 한 부분입니다. 당신의 회의를 다루는 어시스턴트에는 설계상 그런 것이 없습니다.

무엇부터 시작할까

스킬이 자신에게 맞는지 가장 빨리 확인하는 방법은, 어시스턴트에게 이미 몇 번 연달아 내렸던 지시 하나를 골라 스킬로 저장해 보는 것입니다. 파일에 5분, 연결에 1분. 결과는 곧바로 읽힙니다. 답변이 당신이 뜻한 바에 가까워졌다면, 방금 반복을 그만둔 것입니다. 그렇지 않다면 그 지시는 방법이 아니라 데이터에 관한 것이었고, 답은 다른 도구에 있습니다.

스킬 라이브러리는 웹 화면의 프롬프트에 있습니다. 프롬프트와 역할의 구조는 Prompt Studio 안내에, 어떤 모델이 어떤 역할을 맡는지는 모델 역할 문서에 정리되어 있습니다.