2026 커서 에이전트 스킬 설치와 팀 설정

증상 → 빠른 해법
커서에서 에이전트 스킬이 보이지 않거나 팀원마다 다르게 동작합니다. → 저장소 루트에서 skills.sh로 mattpocock/skills를 프로젝트 단위로 설치한 뒤 /setup-matt-pocock-skills를 실행합니다.

이 방법은 커서에서 테스트 주도 개발, 오류 진단, 코드 검토 흐름을 빠르게 쓰려는 개발자에게 적합합니다. 여러 구성원의 에이전트 동작을 맞추고 설정을 Git으로 관리하려는 기술 책임자에게도 유용합니다. 로컬 맥과 원격 맥 개발 환경을 함께 운영하는 팀은 마지막 검수 단계까지 따라가야 합니다.

마지막 업데이트: 2026년 8월 13일. 설치 명령과 설정 이름은 게시 전에 mattpocock/skills 최신 읽어보기와 skills.sh 명령 문서에서 다시 확인해야 합니다.

프로젝트 설치와 전역 설치를 먼저 비교하기

팀 저장소라면 프로젝트 단위 설치를 기본값으로 선택합니다. 설치 위치는 저장소 루트의 .cursor/skills/ 또는 .agents/skills/입니다. 커서는 두 경로에 있는 SKILL.md를 프로젝트 스킬로 발견할 수 있습니다.

사용자 단위 경로인 ~/.cursor/skills/와 ~/.agents/skills/는 개인 작업용으로 남겨두는 편이 안전합니다. 개인 설정을 팀 저장소에 섞으면 구성원마다 다른 스킬이 호출될 수 있습니다.

커서의 에이전트 스킬 변경 기록은 스킬이 SKILL.md를 바탕으로 필요할 때 발견되고 호출되는 절차형 지침이라고 설명합니다. 반면 커서 규칙 공식 문서는 프로젝트의 지속적인 지침과 코드 작성 제약을 규칙 파일로 관리하는 방식을 안내합니다.

npx skills add mattpocock/skills는 어느 폴더에서 실행해야 하나요?
설정 파일을 저장소에 포함하려면 대상 저장소의 루트에서 실행합니다. package.json이 있는 하위 폴더나 다른 프로젝트에서 실행하면 엉뚱한 저장소에 스킬이 생성될 수 있습니다.

실행 전에는 다음 항목을 확인합니다.

• Node.js와 npx가 정상 동작하는지 확인합니다.
• 현재 위치가 올바른 저장소인지 git rev-parse --show-toplevel로 확인합니다.
• 작업 중인 변경 사항을 별도 브랜치나 커밋으로 보존합니다.
• 스킬 파일과 내부 스크립트를 검토할 저장소 쓰기 권한을 준비합니다.
• Claude Code 플러그인을 이미 설치했다면 중복 설치 여부를 확인합니다.

첫 단계: 설치 방식과 충돌 범위 고정하기

mattpocock/skills는 여러 개발 흐름을 묶은 모음입니다. 처음부터 모든 스킬을 선택하지 마십시오. 요구사항 정리, 테스트 주도 개발, 오류 진단, 코드 검토처럼 팀에서 실제로 사용할 흐름만 고르는 편이 안전합니다.

프로젝트 루트에서 다음 명령을 실행합니다.

npx skills@latest add mattpocock/skills

설치기는 사용할 스킬과 대상 에이전트를 선택하게 합니다. 첫 설치에서는 setup-matt-pocock-skills를 반드시 선택합니다. 나머지는 첫 검증 과제에 필요한 항목만 추가합니다. 설치 절차는 저장소의 설치 안내를 기준으로 확인합니다.

저장소 읽어보기는 Claude Code 플러그인과 skills.sh 방식의 관리 경계를 구분합니다. 두 방식을 함께 설치하면 같은 스킬이 서로 다른 위치에서 발견될 수 있으므로 하나만 선택해야 합니다.

Claude Code 플러그인과 skills.sh를 동시에 설치해도 되나요?
권장하지 않습니다. 같은 이름의 스킬이 서로 다른 위치에서 발견되면 어떤 설명과 파일이 우선되는지 구성원마다 다르게 경험할 수 있습니다. Claude Code를 관리형으로 운영할 팀은 플러그인만 사용합니다. 커서와 여러 에이전트에서 파일을 직접 수정하고 Git으로 검수할 팀은 skills.sh 설치만 사용합니다.

설치 직후에는 다음 명령으로 파일 상태를 확인합니다.

find .cursor/skills .agents/skills -name SKILL.md -print 2>/dev/null
git status --short
git diff --stat

스킬 이름, 파일 위치, 폴더 구조가 예상과 다르면 바로 중단합니다. 잘못된 저장소에 설치한 뒤 파일만 옮기면 연결된 참조와 설정이 어긋날 수 있습니다.

스킬과 커서 규칙의 역할을 분리하기

커서 에이전트 스킬과 커서 규칙은 어떻게 나누나요?
Skills는 필요할 때 실행하는 절차입니다. Cursor Rules는 계속 지켜야 하는 프로젝트 제약입니다.

예를 들어 테스트 주도 개발 스킬에는 테스트 작성, 실패 확인, 구현, 다시 검증하는 순서를 둡니다. 반면 규칙에는 사용하는 테스트 도구, 모듈 경계, 오류 처리 방식처럼 대부분의 작업에 지속해서 적용되는 기준을 둡니다.

프로젝트 규칙은 버전 관리할 수 있고 파일 경로에 따라 범위를 나눌 수 있습니다. 따라서 코드 검토 때만 필요한 절차를 규칙 파일에 넣거나, 모든 코드에 적용되는 이름 규칙을 스킬에 넣는 식의 혼합을 피해야 합니다.

팀 저장소에서는 다음처럼 나누면 관리하기 쉽습니다.

.cursor/
├── rules/
│   ├── architecture.mdc
│   └── testing.mdc
└── skills/
    ├── tdd/
    │   └── SKILL.md
    ├── diagnosing-bugs/
    │   └── SKILL.md
    └── code-review/
        └── SKILL.md

두 번째 단계: 설정 스킬을 저장소에 맞게 실행하기

설치가 끝나면 커서 에이전트에서 다음 명령을 수동으로 호출합니다.

/setup-matt-pocock-skills

이 스킬은 에이전트가 항상 먼저 실행하는 단계가 아닙니다. 설정 스킬 안내 문서는 저장소마다 한 번 실행하고, 이후 다른 엔지니어링 스킬이 읽을 설정을 생성하는 흐름으로 설명합니다.

실행 중에는 최소한 다음 결정을 확인합니다.

1. 이슈 추적 시스템을 GitHub, Linear, 로컬 마크다운 중 무엇으로 사용할지 정합니다.
2. 분류 스킬을 설치했다면 실제 팀 라벨 이름을 확인합니다.
3. 도메인 문서와 작업 문서를 저장할 위치를 정합니다.
4. 기존 AGENTS.md 또는 CLAUDE.md를 덮어쓰지 않는지 확인합니다.
5. 생성된 파일을 바로 Git 차이로 검토합니다.

설정 후에는 docs/agents/ 아래에 이슈 추적과 도메인 문서 관련 파일이 생길 수 있습니다. 저장소에 이미 AGENTS.md가 있다면 새 설정과 기존 지침이 충돌하지 않는지 확인합니다. 설정 스킬은 정해진 틀을 무조건 복사하는 도구가 아니라 저장소를 살펴본 뒤 질문하고 파일을 작성하는 방식입니다.

스킬이 보이지 않을 때와 자동 호출을 제한할 때

설치했는데 왜 커서에 스킬이 나타나지 않나요?
다음 순서로 확인합니다.

• 현재 열려 있는 폴더가 설치한 저장소 루트인지 확인합니다.
• SKILL.md 파일명이 정확한지 확인합니다.
• YAML 앞부분의 name과 description이 빠지지 않았는지 확인합니다.
• .cursor/skills/스킬명/SKILL.md 또는 .agents/skills/스킬명/SKILL.md 구조가 맞는지 확인합니다.
• 커서를 다시 불러온 뒤 새 에이전트 대화에서 확인합니다.

새 파일을 만든 직후 기존 대화에 바로 반영되지 않는 경우가 있습니다. 설정 화면의 Skills 목록이나 에이전트의 슬래시 호출 메뉴에서 스킬 이름을 확인합니다.

description은 에이전트가 스킬을 발견할 때 사용하는 설명입니다. disable-model-invocation: true를 넣으면 자동 호출을 막고 수동 호출 중심으로 운영할 수 있습니다. 자주 쓰지 않는 코드 검토나 배포 점검 스킬에 적합합니다. 다만 실제 표시 방식은 커서 버전에 따라 달라질 수 있으므로 최신 변경 기록을 확인해야 합니다.

세 번째 단계: 작은 작업으로 팀 동작 검증하기

설치가 성공했다고 바로 팀 표준으로 확정하지 마십시오. 첫 검증은 범위를 작게 잡습니다. 테스트가 하나 부족한 함수나 재현 가능한 작은 오류를 선택합니다.

권장 순서는 다음과 같습니다.

1. 요구사항이 모호하면 요구사항 정리 스킬을 호출합니다.
2. 새 동작을 추가한다면 /tdd를 수동 호출합니다.
3. 오류 재현이 필요하면 진단 스킬만 호출합니다.
4. 변경이 끝난 뒤 코드 검토 스킬로 차이를 검사합니다.
5. 결과에 실제 저장소 문서와 스크립트가 반영되었는지 확인합니다.

모든 스킬을 동시에 켜면 어떤 절차가 결과에 영향을 주었는지 추적하기 어렵습니다. 한 작업에 한두 개의 스킬만 사용하고 호출 기록과 생성 파일을 함께 검토해야 합니다.

• [ ] 저장소 루트에서 설치 명령을 실행했습니다.
• [ ] setup-matt-pocock-skills를 첫 선택 항목에 포함했습니다.
• [ ] 설치된 SKILL.md의 이름과 설명을 확인했습니다.
• [ ] docs/agents/ 생성 파일을 Git 차이로 검토했습니다.
• [ ] AGENTS.md 또는 CLAUDE.md의 기존 내용을 보존했습니다.
• [ ] 테스트 주도 개발, 진단, 코드 검토 중 필요한 스킬만 선택했습니다.
• [ ] 같은 작업을 새 커서 대화에서 다시 실행했습니다.
• [ ] 스킬이 참조한 스크립트와 문서가 저장소 안에 실제로 존재합니다.
• [ ] 개인 설정과 팀 공통 설정을 분리했습니다.
• [ ] 팀 브랜치에서 되돌릴 수 있는 커밋 단위로 저장했습니다.

네 번째 단계: 업데이트와 권한 검토를 팀 절차로 만들기

skills.sh 방식은 파일을 직접 관리하는 대신 업데이트도 직접 책임지는 방식입니다. 업데이트 전에는 최신 변경 내용을 먼저 읽어야 합니다.

npx skills update

특히 다음 파일을 우선 검토합니다.

• SKILL.md의 절차 변경
• 실행 스크립트와 셸 명령
• 외부 문서나 경로를 참조하는 파일
• 권한 상승, 네트워크 접근, 파일 삭제와 관련된 코드
• 팀이 수정한 문장과 설정 파일

npx skills update를 바로 실행해 팀이 수정한 파일을 덮어쓰지 마십시오. 별도 브랜치에서 변경을 가져오고, 팀이 추가한 설정과 상류 변경을 분리해서 검토해야 합니다. 스킬이 실행 파일이나 외부 참조를 포함한다면 설치량이나 인기도를 안전성의 근거로 사용해서는 안 됩니다.

현재 맥과 원격 맥을 같은 기준으로 검수하기

로컬에서 정상 동작했다고 해서 다른 개발 환경에서도 자동으로 같아지는 것은 아닙니다. 원격 맥 개발 환경을 추가한다면 설치 결과보다 재현 절차를 비교해야 합니다.

결론은 세 가지로만 남기는 것이 좋습니다.

• 통과: 파일 구조, 발견 상태, 초기화 결과, 대표 작업이 모두 일치합니다.
• 조정 필요: 권한, 경로, 재시작, 사용자 단위 파일 차이 중 하나가 남아 있습니다.
• 보류: 스킬이 보이지 않거나 설정 파일이 다르게 생성되며 원인을 설명하지 못합니다.

원격 환경의 실제 설치 결과와 실패 기록은 공개 문서만으로 추정하지 마십시오. 팀이 직접 실행한 기록과 저장소 차이를 기준으로 판단해야 합니다. 환경을 반복해서 전달해야 한다면 MacHTML의 원격 맥 개발 환경 안내와 관리 화면을 확인하면서 초기화 단계와 권한 처리를 문서화하는 편이 좋습니다.

개인 개발자이고 로컬 맥만 사용한다면 전역 설치가 편할 수 있습니다. 그러나 여러 사람이 같은 저장소를 작업하거나 원격 환경으로 넘길 예정이라면 프로젝트 단위 설치가 더 적합합니다. 전역 스킬은 개인 편의에는 좋지만 팀의 재현성과 코드 검토에는 약점이 있습니다.

현재 방식이 개인 맥에만 의존하면 환경 차이, 수동 설정 누락, 스킬 버전 불일치가 반복됩니다. 반면 MacHTML의 맥 개발 환경을 임시로 사용하면 저장소별 초기화 절차를 분리하고, 팀원이 같은 작업 공간에서 설치와 검수를 반복할 수 있습니다. 장기적으로 고정된 고부하 작업이나 물리 장비 연결이 필요하다면 직접 구매가 더 맞습니다. 팀 온보딩과 커서 에이전트 검증처럼 기간이 짧고 되돌릴 가능성이 있는 작업이라면 먼저 재현 가능한 맥 환경에서 시험하는 편이 안전합니다.