npx skills 실전 가이드: AI 에이전트 스킬을 npm처럼 설치하는 오픈 도구

AI 에이전트마다 수동 설정하는 고통

Claude Code를 쓰다가 Cursor로 넘어가면? 설정 다시 해야 한다. Cursor에서 쓰던 컨텍스트 파일, 커맨드 템플릿, 코딩 가이드라인을 새 에이전트에 맞게 처음부터 세팅해야 한다.

AI 에이전트가 하나씩 늘어날수록 이 작업이 배수로 늘어난다. Claude Code에는 .claude/commands/에 마크다운을 넣고, Cursor에는 .cursorrules를 따로 작성하고, Codex에는 또 다른 형식을 쓴다. 각 에이전트마다 인터페이스가 다르고, 같은 “능력”을 여러 번 설정해야 한다.

skills CLI는 이 문제를 정면으로 해결한다. GitHub repo 하나에 스킬을 정의해두면, 어떤 에이전트에도 한 줄로 설치할 수 있다. npm이 Node.js 패키지를 표준화한 것처럼, skills는 AI 에이전트 스킬을 표준화한다.

skills CLI란

skills는 AI 에이전트용 스킬 패키지 관리자다. 핵심 아이디어는 단순하다:

• 스킬 제작자: GitHub repo에 SKILL.md와 참고 자료를 올린다
• 스킬 사용자: npx skills add <owner/repo>로 그 스킬을 에이전트에 설치한다
• 에이전트: 설치된 스킬의 컨텍스트를 읽고 해당 작업을 더 잘 수행한다

npm과 구조가 거의 같다. npm registry 대신 GitHub를 저장소로 쓰고, node_modules 대신 에이전트별 설정 디렉토리에 설치된다. package.json 대신 SKILL.md가 스킬의 메타데이터와 설명을 담는다.

Vercel Labs가 2026년 1월에 공개한 이후 반년 만에 GitHub 스타 25K를 넘겼고, 2026년 7월 기준 Claude Code, Codex, Cursor, GitHub Copilot, Windsurf를 포함해 72개 에이전트를 공식 지원한다.

주요 명령어

설치는 별도 전역 설치 없이 npx로 바로 실행한다.

스킬 설치

npx skills add <owner/repo>

특정 에이전트를 지정해 설치하려면 -a 플래그를 쓴다:

npx skills add anthropics/skills -a claude-code

여러 스킬 중 특정 스킬만 선택하려면 --skill 옵션을 쓴다:

npx skills add anthropics/skills -a claude-code --skill 'pdf'

전체 스킬을 한번에 설치하고 프롬프트 없이 자동 확인하려면:

npx skills add anthropics/skills -a claude-code --skill '*' -y

설치된 스킬 목록 확인

npx skills list

현재 프로젝트 또는 전역으로 설치된 스킬 목록을 에이전트별로 보여준다.

스킬 제거

npx skills remove <skill-name>

스킬 검색

npx skills find <keyword>

키워드로 공개 스킬을 검색하거나, 키워드 없이 실행해 인터랙티브로 탐색한다. “testing”, “react”, “deploy” 같은 키워드로 관련 스킬을 찾을 수 있다.

새 스킬 초기화

npx skills init

현재 디렉토리에 스킬 제작을 위한 기본 파일 구조를 생성한다.

동작 원리

skills CLI는 GitHub API를 통해 지정된 repo의 구조를 읽는다. 스킬 repo의 핵심 파일은 두 가지다:

SKILL.md: 스킬의 선언 파일. 에이전트에게 “이 스킬로 무엇을 할 수 있는지”, “어떻게 사용하는지”를 설명하는 마크다운 문서다. 에이전트는 이 파일을 읽고 스킬의 역할을 이해한다.

references/ 디렉토리: 스킬이 참조하는 모든 문서, 예제, 가이드가 들어간다. 코드 스니펫, API 문서, 패턴 가이드, FAQ 등을 여기에 넣으면 에이전트가 작업 시 이 파일들을 컨텍스트로 활용한다.

설치 시 skills CLI는 이 파일들을 에이전트별 설정 위치에 복사한다. Claude Code라면 .claude/ 디렉토리, Cursor라면 .cursor/ 디렉토리에 알맞은 형식으로 변환해 넣는다. 스킬 제작자는 각 에이전트의 세부 형식을 몰라도 된다 — skills CLI가 변환을 처리한다.

에이전트 호환성

skills가 지원하는 주요 에이전트와 설치 명령의 -a 플래그 값:

에이전트	플래그 값
Claude Code	claude-code
OpenAI Codex	codex
Cursor	cursor
GitHub Copilot	github-copilot
Windsurf	windsurf
OpenCode	opencode
Continue	continue

플래그 없이 npx skills add를 실행하면 현재 디렉토리에서 사용 중인 에이전트를 자동 감지하거나 선택 메뉴를 보여준다.

여러 에이전트에 동시 설치도 가능하다:

npx skills add anthropics/skills -a claude-code -a codex

스킬 만들기

팀 내부용이든 공개 배포용이든, 스킬 제작은 GitHub repo 하나를 만드는 것에서 시작한다.

기본 구조

my-skill/
├── SKILL.md          # 스킬 선언 (필수)
├── references/       # 참고 자료 디렉토리
│   ├── guide.md
│   └── examples/
└── README.md         # GitHub용 설명 (선택)

npx skills init을 실행하면 이 구조를 자동으로 생성해준다.

SKILL.md 형식

---
name: my-skill
description: 무엇을 하는 스킬인지 한 줄 설명
version: 1.0.0
---

# My Skill

## 용도

이 스킬을 설치하면 에이전트가 [구체적인 작업]을 더 잘 수행합니다.

## 사용 방법

에이전트에게 [이런 요청]을 하면 이 스킬의 가이드라인을 따릅니다.

## 주의사항

- [중요한 제약사항]
- [알아야 할 패턴]

references 디렉토리 활용

references 디렉토리의 파일들은 에이전트의 컨텍스트로 직접 들어간다. 스킬의 품질은 이 디렉토리에 얼마나 좋은 자료를 넣느냐에 달려 있다.

• API 문서 요약본
• 자주 쓰는 코드 패턴
• 오류 해결 가이드
• 작업 체크리스트

마켓플레이스 노출

만든 스킬은 GitHub repo에 공개하는 것으로 배포가 끝난다 — 누구나 npx skills add <owner/repo>로 설치할 수 있다. 공개 스킬의 키워드 검색은 npx skills find가, 인기 리더보드와 주제별 탐색은 skills.sh 디렉토리가 맡는다.

실전: Anthropic 공식 스킬 설치하기

설치 흐름을 실제 repo로 확인해보자. Anthropic이 공개한 공식 스킬 repo(anthropics/skills)에는 PDF·DOCX·PPTX·XLSX 문서 처리 스킬이 들어 있다. Claude Code에 설치하려면:

# Claude Code에 공식 스킬 전체 설치
npx skills add anthropics/skills -a claude-code --skill '*' -y

또는 특정 스킬만 설치할 수도 있다:

# pdf 스킬만 설치
npx skills add anthropics/skills -a claude-code --skill 'pdf'

설치 후 Claude Code를 재시작하면 에이전트가 해당 스킬의 SKILL.md를 읽고, PDF 편집이나 문서 생성 요청에서 그 가이드라인을 따른다.

npm이 만든 생태계, skills가 만들 생태계

npm이 등장하기 전 Node.js 개발자들은 라이브러리를 직접 복사하거나 수동으로 관리했다. npm이 표준 인터페이스를 제공하자 생태계가 폭발적으로 성장했다. 오늘날 npm에는 200만 개 이상의 패키지가 있다.

AI 에이전트는 지금 그 변곡점 직전에 있다. 각자 자기 에이전트를 수동으로 설정하고, 같은 작업을 위한 설정을 따로따로 만들고, 에이전트를 바꿀 때마다 다시 시작한다.

skills는 이 분산된 설정 작업을 표준화한다. 좋은 스킬이 GitHub에 올라오면 누구나 설치할 수 있고, 스킬 제작자는 한번 만들면 70개 이상의 에이전트에서 동작하는 스킬을 배포할 수 있다.

1인 개발자에게 이 흐름은 실용적인 기회다. 자신이 반복하는 작업을 스킬로 만들면 팀 없이도 재사용 가능한 워크플로우를 갖출 수 있다. 그 스킬을 공개하면 커뮤니티 기여가 된다.

도구는 이미 있다. 어떤 스킬을 만들지만 결정하면 된다.

---

참고 링크

• skills CLI GitHub — 소스코드 및 공식 문서
• 스킬 마켓플레이스 — 공개 스킬 검색
• Anthropic 공식 스킬 repo — PDF·DOCX 등 문서 처리 스킬 모음