커서에 스킬 설치하는 방법

Node.js 18 이상이 있는 아무 터미널에서 실행하세요. --agent cursor를 붙이면 CLI가 공용 위치인 ~/.agents/skills 대신 커서 폴더에 씁니다. -y는 대화형 질문을 건너뜁니다. 소유자, 저장소, 스킬 이름은 이 사이트의 스킬 페이지에 있는 값으로 바꾸세요.

--agent 없이 실행하면 CLI가 어느 에이전트에 설치할지 묻고 여러 개를 고를 수 있습니다. 커서와 클로드 코드를 함께 쓴다면 괜찮지만, 커서만 쓴다면 이 옵션이 설치 결과를 예측 가능하게 합니다.

npx skills add vercel-labs/agent-skills@web-design-guidelines --agent cursor -y

-g를 붙이면 사용자 계정에 설치됩니다. 스킬이 ~/.cursor/skills/<이름>/에 들어가고 어떤 프로젝트를 열어도 쓸 수 있습니다. -g를 빼면 현재 저장소의 .agents/skills/<이름>/에 들어가며, 커밋해 두면 팀원도 체크아웃만으로 같은 스킬을 받습니다.

커서는 프로젝트 안의 .cursor/skills/도 읽습니다. CLI가 거기에 쓰지는 않지만 폴더를 직접 복사한다면 두 위치 모두 됩니다. 어디서나 쓰고 싶은 스킬(디자인 검토, 커밋 메시지 형식)은 전역으로, 특정 코드베이스의 프레임워크에 묶인 스킬은 프로젝트로 설치하세요.

npx skills add vercel-labs/agent-skills@web-design-guidelines --agent cursor -g -y

# Global:  ~/.cursor/skills/web-design-guidelines/SKILL.md
# Project: .agents/skills/web-design-guidelines/SKILL.md

커서는 새 에이전트 채팅이 시작될 때 스킬 폴더를 훑으므로, 이전 채팅을 이어 가지 말고 새 채팅을 여세요. 입력창에 슬래시를 치면 명령 목록에 폴더 이름으로 스킬이 나타나야 합니다. 커서 설정의 Rules 항목에서도 스킬 목록을 볼 수 있습니다. 거기 없는 스킬은 디스크에서 찾지 못한 것입니다.

목록이 갱신되지 않으면 창을 다시 불러오세요. 명령 팔레트(Ctrl+Shift+P, macOS는 Cmd+Shift+P)를 열고 Developer: Reload Window를 실행합니다. 커서를 완전히 재시작할 일은 거의 없습니다.

직접 부르지 않아도 됩니다. 커서는 채팅 시작 시 설치된 모든 스킬의 이름과 설명을 읽고, 요청이 맞을 때만 SKILL.md 전체를 불러옵니다. 강제로 쓰려면 채팅에 /스킬이름을 입력하고 요청을 이어 쓰세요. 처음에는 자동 매칭에 의존하기 전에 스킬이 무엇을 하는지 보기 위해 강제로 불러 보는 것이 좋습니다.

스킬과 커서 Rules는 다른 것입니다. 규칙(.cursor/rules/*.mdc)은 매칭되는 파일에 항상 적용되고, 스킬은 작업에 따라 필요할 때 불러옵니다. 규칙을 스킬로 바꾸거나 그 반대로 하지 마세요. 짧고 항상 참인 제약은 규칙으로, 긴 절차는 스킬로 두세요.

npx skills update는 CLI가 설치한 모든 스킬을, CLI가 쓴 모든 에이전트 폴더에서 갱신합니다. 삭제하려면 ~/.cursor/skills/나 프로젝트의 .agents/skills/에서 폴더를 지우고 새 채팅을 시작하세요. 커서에 알려야 하는 삭제 명령은 없습니다. 폴더가 곧 등록입니다.

npx skills update

설치는 됐는데 커서 목록에 없다: 가장 흔한 원인은 --agent cursor 없이 설치되어 ~/.agents/skills/에 들어간 경우입니다. 구버전 커서는 그곳을 읽지 않습니다. 옵션을 붙여 다시 설치하거나 폴더를 ~/.cursor/skills/로 옮긴 뒤 새 채팅을 시작하세요.

CLI가 No valid skills found를 출력한다: 그 저장소의 SKILL.md 머리말에 name이나 description이 없거나 제작자가 위치를 옮긴 것입니다. 스킬 페이지의 저장소 링크를 열어 현재 경로를 확인하고, 폴더를 .cursor/skills/에 직접 복사해도 됩니다.

목록에는 있는데 발동하지 않는다: 커서는 내 말을 스킬 설명과 대조합니다. 스킬 페이지의 설명을 읽고 같은 방식으로 요청하거나 슬래시로 부르세요. 설명이 비었거나 한 글자뿐인 스킬은 슬래시로만 동작합니다.

윈도우: 전역 설치는 일부 에이전트 폴더에 심볼릭 링크를 만드는데, 링크에는 개발자 모드나 관리자 터미널이 필요합니다. CLI가 권한 오류를 내면 윈도우 설정에서 개발자 모드를 켜거나 관리자 PowerShell에서 한 번 실행하세요. node --version으로 npx가 잡히는지도 먼저 확인하세요.

설치 후 에이전트가 더 나빠졌다: 큰 SKILL.md는 발동할 때마다 통째로 올라와 작은 컨텍스트에서는 내 코드를 밀어냅니다. 스킬 페이지에서 크기를 확인하고, 30KB가 넘으면 전역보다 프로젝트별로 설치하세요.