npx skills 실전 가이드: AI 에이전트 스킬을 npm처럼 설치하는 오픈 도구
- npx skills: GitHub 10.4K stars의 오픈소스 AI 에이전트 스킬 관리 CLI
- npm for AI agents:
npm install처럼npx skills add <repo>로 에이전트 능력을 설치 - 18+ 에이전트 지원: Claude Code, Codex, Cursor, Copilot, Windsurf 등
- GitHub 기반 배포: GitHub repo에서 SKILL.md를 읽어 에이전트에 직접 설치
- agentic30 통합:
npx skills add october-academy/agnt -a claude-code로 학습 커맨드 설치 가능
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가 스킬의 메타데이터와 설명을 담는다.
2025년에 공개된 이후 꾸준히 성장해 10.4K GitHub 스타를 달성했다. Claude Code, Codex, Cursor, GitHub Copilot, Windsurf를 포함해 18개 이상의 에이전트를 공식 지원한다.
주요 명령어
설치는 별도 전역 설치 없이 npx로 바로 실행한다.
스킬 설치
npx skills add <owner/repo>
특정 에이전트를 지정해 설치하려면 -a 플래그를 쓴다:
npx skills add october-academy/agnt -a claude-code
여러 스킬 중 특정 스킬만 선택하려면 --skill 옵션을 쓴다:
npx skills add october-academy/agnt -a claude-code --skill 'continue'
전체 스킬을 한번에 설치하고 프롬프트 없이 자동 확인하려면:
npx skills add october-academy/agnt -a claude-code --skill '*' -y
설치된 스킬 목록 확인
npx skills list
현재 프로젝트 또는 전역으로 설치된 스킬 목록을 에이전트별로 보여준다.
스킬 제거
npx skills remove <skill-name>
스킬 검색
npx skills search <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가 변환을 처리한다.
스코프 선택: -s project (기본값, 현재 프로젝트에만 설치) 또는 -s user (전역 설치, 모든 프로젝트에서 사용 가능) 중 선택할 수 있다. 특정 프로젝트에만 쓰는 스킬이라면 project scope, 모든 작업에서 항상 쓰는 스킬이라면 user scope를 권장한다.
에이전트 호환성
skills가 지원하는 주요 에이전트와 설치 명령의 -a 플래그 값:
| 에이전트 | 플래그 값 |
|---|---|
| Claude Code | claude-code |
| OpenAI Codex | codex |
| Cursor | cursor |
| GitHub Copilot | copilot |
| Windsurf | windsurf |
| Aider | aider |
| Continue | continue |
플래그 없이 npx skills add를 실행하면 현재 디렉토리에서 사용 중인 에이전트를 자동 감지하거나 선택 메뉴를 보여준다.
여러 에이전트에 동시 설치도 가능하다:
npx skills add october-academy/agnt -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 문서 요약본
- 자주 쓰는 코드 패턴
- 오류 해결 가이드
- 작업 체크리스트
references 파일은 크기가 작을수록 좋다. 에이전트의 컨텍스트 창은 유한하기 때문에, 한 파일에 모든 것을 담기보다 주제별로 나눈 여러 파일이 실제 사용 시 더 효과적이다.
마켓플레이스 등록
만든 스킬을 공개 마켓플레이스에 등록하면 npx skills search에서 검색된다. skills CLI GitHub 레포의 CONTRIBUTING.md에 등록 방법이 안내되어 있다. 기본적으로 PR을 통해 마켓플레이스 레지스트리에 추가하는 방식이다.
agentic30 agnt 스킬 설치하기
agentic30의 학습 도우미 agnt도 skills 형식으로 배포되어 있다. Claude Code에서 /agnt:continue, /agnt:today, /agnt:submit 같은 학습 커맨드를 쓰려면:
# Claude Code에 agnt 스킬 전체 설치
npx skills add october-academy/agnt -a claude-code --skill '*' -y
또는 특정 커맨드만 설치할 수도 있다:
# continue 커맨드만 설치
npx skills add october-academy/agnt -a claude-code --skill 'continue'
설치 후 Claude Code를 재시작하면 /agnt: 네임스페이스의 커맨드들이 활성화된다. 학습 상태는 MCP 서버를 통해 서버와 동기화된다.
agnt 스킬은 agentic30 수강생 계정이 있어야 서버 동기화 기능이 작동한다. 계정 없이 설치하면 커맨드 구조는 설치되지만 진행 상황 저장이나 XP 적립은 동작하지 않는다.
npm이 만든 생태계, skills가 만들 생태계
npm이 등장하기 전 Node.js 개발자들은 라이브러리를 직접 복사하거나 수동으로 관리했다. npm이 표준 인터페이스를 제공하자 생태계가 폭발적으로 성장했다. 오늘날 npm에는 200만 개 이상의 패키지가 있다.
AI 에이전트는 지금 그 변곡점 직전에 있다. 각자 자기 에이전트를 수동으로 설정하고, 같은 작업을 위한 설정을 따로따로 만들고, 에이전트를 바꿀 때마다 다시 시작한다.
skills는 이 분산된 설정 작업을 표준화한다. 좋은 스킬이 GitHub에 올라오면 누구나 설치할 수 있고, 스킬 제작자는 한번 만들면 18개 에이전트에서 동작하는 스킬을 배포할 수 있다.
1인 개발자에게 이 흐름은 실용적인 기회다. 자신이 반복하는 작업을 스킬로 만들면 팀 없이도 재사용 가능한 워크플로우를 갖출 수 있다. 그 스킬을 공개하면 커뮤니티 기여가 된다.
도구는 이미 있다. 어떤 스킬을 만들지만 결정하면 된다.
참고 링크
- skills CLI GitHub — 소스코드 및 공식 문서
- 스킬 마켓플레이스 — 공개 스킬 검색
- agentic30 agnt 스킬 — 학습 커맨드 스킬 레포