클로드 코드 스킬 설치 방법: SKILL.md, 플러그인, npx skills add 3가지 (2026년 11월)

같은 스킬인데 README마다 설치법이 다른 이유

어떤 저장소는 /plugin install 을 쓰라고 하고, 다른 곳은 npx skills add 를 치라고 하고, 또 다른 곳은 폴더를 복사하라고 합니다. 셋 다 맞습니다. 스킬을 어디에 놓느냐가 다를 뿐이고, 어떤 길로 와도 결과는 SKILL.md가 든 폴더 하나입니다.

인기 있는 스킬 저장소를 별 수로 정리한 글은 /ai/basics/claude-skills-top10 에 있습니다. 여기서는 어떤 스킬을 깔든 같은 설치 과정에 집중합니다.

스킬은 SKILL.md가 든 폴더 하나

공식 문서의 정의는 단순합니다. 스킬은 SKILL.md 파일이 있는 폴더이고, 파일은 맨 위에 --- 로 둘러싼 설정(YAML)이 있고 그 아래에 마크다운 지침이 옵니다. 설정 항목은 모두 선택이지만 description(무엇을 하고 언제 쓰는지)은 권장됩니다. 클로드는 이 설명을 보고 지금 요청에 쓸지 판단합니다.

아래는 가장 작은 예입니다. 폴더를 하나 만들고 이 파일을 넣으면 스킬 하나가 됩니다.

---
name: meeting-notes
description: 회의 메모를 안건, 결정, 할 일 3칸으로 정리한다. 사용자가 회의록 정리를 부탁할 때 쓴다.
---

# 회의록 정리

1. 안건을 한 줄씩 적는다.
2. 정해진 결정은 따로 모은다.
3. 할 일은 담당자와 기한을 붙여 표로 만든다. 담당자가 없으면 비워 둔다.

스킬, 플러그인, 마켓

정리하면 플러그인은 스킬을 배달하는 상자 중 하나입니다. 스킬만 필요하면 폴더로도 충분하고, 훅이나 MCP 서버까지 같이 받아야 하면 플러그인이 맞습니다.

• 스킬

  뜻

  SKILL.md가 든 폴더 하나

  이름이 붙는 방식

  /스킬이름

• 플러그인

  뜻

  스킬, 에이전트, 훅, MCP 서버를 묶은 꾸러미

  이름이 붙는 방식

  플러그인 안의 스킬은 /플러그인이름:스킬이름

• 마켓(marketplace)

  뜻

  플러그인 목록 카탈로그. GitHub 저장소 하나가 마켓이 될 수 있음

  이름이 붙는 방식

  플러그인@마켓이름

• 커스텀 명령(.claude/commands)

  뜻

  예전 방식. 공식 문서에 따르면 스킬로 합쳐졌고 기존 파일은 계속 동작함

  이름이 붙는 방식

  /이름

방법 1: 플러그인 마켓

공식 마켓(claude-plugins-official)은 대화형 터미널 세션을 처음 열 때 자동으로 등록됩니다. 여기 있는 플러그인은 마켓을 따로 추가하지 않고 바로 설치하면 됩니다. 다른 마켓에 있는 것은 마켓을 먼저 추가합니다.

세션 안에서 /plugin install 을 치면 바로 설치되지 않고 플러그인 상세 창이 열립니다. 여기서 추가되는 구성(명령, 에이전트, 스킬, 훅, MCP 서버)을 읽고 설치 범위를 고릅니다. 범위는 세 가지입니다. 이 컴퓨터의 모든 프로젝트(user), 저장소 협업자 모두(project), 이 저장소의 나만(local).

/plugin install superpowers@claude-plugins-official

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

claude plugin marketplace add anthropics/skills
claude plugin install document-skills@anthropic-agent-skills

방법 2: npx skills add

vercel-labs가 만든 skills CLI입니다. README 기준으로 Node.js 22.20 이상이 필요하고, 클로드 코드 말고도 여러 에이전트를 지원합니다. 명령을 치면 설치할 스킬과 대상 에이전트를 고르는 화면이 나옵니다. 기본은 현재 프로젝트에만 설치되고, -g 를 붙이면 모든 프로젝트에서 씁니다.

막히는 곳이 하나 있습니다. 클로드 코드 세션 안에서 클로드에게 이 명령을 대신 돌리게 하면 비대화형으로 실행되어, 클로드 코드가 읽지 않는 공용 폴더(.agents/skills/)에만 깔리는 경우가 있다고 marketingskills 저장소 README가 경고합니다. 에이전트를 직접 지정하면 피할 수 있습니다.

npx skills add coreyhaines31/marketingskills

npx skills add coreyhaines31/marketingskills --skill cro -a claude-code

npx skills list
npx skills update
npx skills remove

방법 3: .claude/skills 폴더에 직접

같은 이름이 여러 곳에 있으면 조직 설정, 개인, 프로젝트 순으로 앞쪽이 이깁니다. 저장소를 복사해 올 때는 스킬 폴더 통째로 옮겨야 합니다. SKILL.md만 옮기면 같은 폴더의 스크립트와 참고 파일이 빠집니다.

클로드 코드는 이 폴더들을 감시하기 때문에 추가, 수정, 삭제가 재시작 없이 반영됩니다. 다만 세션을 연 뒤에 처음 만든 최상위 skills 폴더는 /reload-skills 를 쳐야 읽힙니다.

• 개인

  경로

  ~/.claude/skills/<이름>/SKILL.md

  쓰이는 범위

  이 컴퓨터의 모든 프로젝트

• 프로젝트

  경로

  .claude/skills/<이름>/SKILL.md

  쓰이는 범위

  이 저장소에서 연 세션. 커밋하면 팀이 같이 씀

• 하위 폴더

  경로

  <폴더>/.claude/skills/<이름>/SKILL.md

  쓰이는 범위

  그 폴더 안에서 시작한 세션

• 플러그인

  경로

  <플러그인>/skills/<이름>/SKILL.md

  쓰이는 범위

  플러그인이 켜진 곳

git clone https://github.com/anthropics/skills ~/skills-src
mkdir -p ~/.claude/skills
cp -r ~/skills-src/skills/pdf ~/.claude/skills/pdf

설치됐는지 확인

직접 부를 때는 메시지를 /스킬이름 으로 시작합니다. 이름이 문장 중간에 있으면 클로드에게 쓸 권한을 줄 뿐 바로 실행되지는 않습니다.

• /skills : 로드된 스킬 목록. claude.ai에서 동기화된 스킬은 따로 표시됩니다.
• /context : 스킬이 컨텍스트를 얼마나 쓰는지 묶어서 보여 줍니다.
• / 를 쳐서 메뉴에서 이름 찾기. 플러그인 스킬은 /플러그인이름:스킬이름 형태입니다.
• claude plugin list (터미널) : 설치한 플러그인의 버전, 범위, 상태.
• 클로드에게 "사용 가능한 스킬이 뭐야?"라고 묻기. 공식 문서도 이 방법을 점검 순서에 넣었습니다.

지우기

프로젝트 설정(.claude/settings.json)에서 켜 둔 플러그인을 지우려 하면, 나만 끌지 모두에게서 지울지 묻습니다. 팀 저장소에서는 나만 끄는 쪽부터 고르세요.

깔았는데 안 보이거나 안 켜질 때

대화가 길어진 뒤 스킬 지침을 안 따른다면 다른 문제입니다. 공식 문서는 대화가 압축되면 호출된 스킬의 앞부분만 남을 수 있으니 스킬을 다시 불러 오라고 안내합니다. 반드시 지켜야 할 규칙은 스킬 지침이 아니라 훅으로 옮기는 편이 확실합니다.

모르는 저장소의 플러그인은 설치 창의 구성 목록을 읽고 깔아야 합니다. 플러그인은 스킬 외에 훅과 MCP 서버를 실행할 수 있습니다. 클로드 웹·앱의 스킬 업로드는 별개의 절차이고 이 글에서는 다루지 않았습니다.

• /plugin isn't available in this environment

  원인

  비대화형 실행(claude -p), 웹 세션 등에서는 /plugin 이 안 돌아감

  해결

  터미널에서 claude plugin install 로 설치

• 설치했는데 /스킬 이름이 없다

  원인

  열린 세션이 아직 새 플러그인을 안 읽음

  해결

  /reload-plugins. 새로 만든 skills 최상위 폴더는 /reload-skills

• /스킬이름은 되는데 알아서 안 켜진다

  원인

  YAML 설정이 깨지면 본문은 로드되지만 설명이 비어 클로드가 매칭하지 못함

  해결

  --debug 로 파싱 오류 확인, claude plugin validate .claude/skills 로 검사(v2.1.233 이상)

• 알아서 안 켜진다

  원인

  설명에 사용자가 실제로 쓰는 말이 없음

  해결

  설명에 "언제 쓰는지"와 사용자가 쓸 법한 표현을 넣기

• 스킬이 많은데 일부가 반응 없다

  원인

  목록 예산(컨텍스트 창의 1%)을 넘으면 설명이 잘림. 설명 한 개는 1,536자까지만

  해결

  안 쓰는 스킬 끄기, /skill-doctor 로 확인

• 저장소 설정엔 켜져 있는데 설치 안 됨

  원인

  프로젝트 범위는 켜기만 공유되고 내려받기는 각자 해야 함

  해결

  각 협업자가 claude plugin install <이름>@<마켓> --scope project

• npx skills add 후 클로드 코드가 못 찾음

  원인

  공용 폴더(.agents/skills/)에만 깔림

  해결

  -a claude-code 를 붙여 다시 설치

• 같은 이름을 고쳤는데 반영이 다르다

  원인

  여러 위치에 같은 이름이 있으면 개인이 프로젝트를 이김

  해결

  /skills 로 어느 쪽이 로드됐는지 확인하고 하나만 남기기

같이 알아두면 좋은 말

SKILL.md

스킬의 본체 파일. 위쪽에 이름·설명 설정, 아래쪽에 지침을 적습니다.

플러그인

스킬, 에이전트, 훅, MCP 서버를 묶어 설치하는 꾸러미.

마켓(marketplace)

플러그인 목록 카탈로그. /plugin marketplace add 로 등록합니다.

훅(hook)

특정 시점에 클로드 코드가 반드시 실행하는 동작. 스킬 지침과 달리 매번 실행됩니다.

자주 묻는 질문

관련 페이지

• 클로드 스킬 TOP 10 (깃허브 별 순)
• 디자인 스킬 모아 보기
• 영상 만드는 클로드 스킬
• 마케팅용 클로드 스킬
• 클로드 한도가 끝났을 때
• AI 요금 비교