스킬 팩 겹쳐 깔지 않고 하나로 끝내는 agent-skills 가이드
하루 6시간 만에AI 기초부터 나만의
서비스까지 완성
역할: agent-skills 설치와, 이미 깔린 스킬과의 겹침 정리를 맡는 담당 맥락: 이 컴퓨터에는 다른 스킬 묶음이 이미 깔려 있을 수 있고, 지금은 무엇이 켜져 있는지 목록으로 확인해 본 적이 없는 상태입니다 입력: <운영체제와 셸, 예: macOS zsh>, <이미 깔아 둔 스킬 묶음이 있으면 그 이름>, <목표 한 줄, 예: 지금 어느 단계인지 내가 짚으면서 시키고 싶다> 작업: 아래 다섯 단계를 순서대로 진행하세요. 1. 지금 깔린 것부터 확인: `npx skills list` 로 이미 설치된 스킬 이름을 전부 뽑아 그대로 보고하세요. 하나도 없으면 없다고 말하세요. 2. 겹칠 자리 미리 찾기: https://github.com/addyosmani/agent-skills 의 README 와 docs/comparison.md 를 읽고, 1번 목록과 **이름이 같은 스킬**을 표시하세요. 특히 test-driven-development 처럼 여러 묶음에 같은 이름이 있는 것을 찾으세요. 3. 목록 먼저 보고 설치: `npx skills add addyosmani/agent-skills --list` 로 무엇이 들어오는지 먼저 띄운 뒤 설치하세요. 명령과 설치 경로는 추측하지 말고 README 에서 확인한 값을 쓰세요. 4. 대화창을 새로 연 뒤, 설치된 스킬 목록에 spec 과 build 관련 항목이 보이는지 확인하세요. 5. 마지막에 무엇이 겹쳤고 무엇을 남겼는지, 개발을 처음 하는 사람도 이해할 수 있는 말로 다섯 줄 이내로 설명하세요. 제약: 추측으로 스킬 개수나 명령 이름을 말하지 마세요. 실제로 확인한 값만 쓰세요. 이미 깔려 있던 스킬을 제 확인 없이 지우지 마세요. 지울 후보만 알려주세요. 설치 뒤에는 대화창을 새로 열어야 한다는 점을 빠뜨리지 마세요. 비밀키와 자격 증명 파일을 읽거나 출력하지 마세요. 출력: 설치 전 목록, 겹치는 이름, 실행한 명령, 설치 후 목록, 남은 문제를 정리해 주세요. 검증: `npx skills list` 에 이번에 설치한 스킬 이름이 보여야 하고, 같은 이름이 두 번 나오는 줄이 없어야 합니다. 하나라도 실패하면 완료로 보고하지 말고 실패 지점과 다음 조치를 알려주세요.
이걸 깔면 무엇이 달라지나
스킬 묶음을 이미 한 번 깔아 봤다면, 이 글은 세 번째 묶음을 더 얹는 글이 아닙니다. 오히려 반대입니다. 저장소가 자기 문서에 "두 묶음을 동시에 주 길잡이로 두면 안 된다"고 적어 두었기 때문에, 깔기 전에 정리부터 하는 순서로 씁니다.
지금까지 다룬 스킬들은 알아서 걸리는 쪽이었습니다. 조건이 맞으면 튀어나오니 편한데, 대신 걸렸는지 안 걸렸는지를 사람이 모릅니다. agent-skills 는 그 반대편에 섰습니다. 개발 여섯 단계에 명령을 하나씩 붙여 두고, 사람이 부릅니다.
정하기 쪼개기 만들기 확인하기 검토하기 내보내기 ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ 무엇을 │ │ 어떻게 │ │ 한칸씩 │ │ 진짜로 │ │ 합치기 │ │ 실제로 │ │ 만드나 │ │ 나누나 │ │ 짓는다 │ │ 되는가 │ │ 전점검 │ │ 내보냄 │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ /spec /plan /build /test /review /ship
지금 어느 칸에 있는지가 화면에 보인다는 뜻입니다. 알아서 걸리기를 기다리지 않고 칸을 짚어 넘어갑니다. 저장소 문서에는 작은 변경이면 앞 칸을 건너뛰고 /test 와 /review 로 바로 갈 수 있다고 적혀 있습니다.
숫자부터 봅니다. 아래는 2026년 8월 30일에 깃허브에서 직접 읽은 값입니다.
- 깃허브 스타 90,636 · 복사해 간 저장소(포크) 9,702
- 공개 2026-02-15 · 마지막 수정 2026-08-28
- 라이선스 MIT · 무료
- 스킬 25개 · 명령 9개 · 검토 담당 4명 · 참고 체크리스트 7장
- 만든 곳 — 깃허브 프로필상 소속이 구글, 팔로워 52,835명
Quick Start
공식 저장소: agent-skills 공식 GitHub · MIT 무료
먼저 무엇이 들어오는지 목록만 봅니다. 스물다섯 개가 한 번에 들어오기 때문입니다.
npx skills add addyosmani/agent-skills --list
addyosmani/agent-skills 철자를 확인하세요.목록을 보고 결정했으면 통째로 깝니다.
npx skills add addyosmani/agent-skills
클로드 코드를 쓴다면 저장소가 권하는 경로가 따로 있습니다. 아래 첫 줄이 저장소를 설치 목록에 등록하는 명령이고, 둘째 줄이 실제 설치입니다.
/plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills
agent-skills 가 보입니다.여기서 권한이 거부됐다는 영문 줄(Permission denied (publickey))이 뜨면 주소를 끝까지 적어 다시 등록합니다. README 에 적힌 대처법입니다.
/plugin marketplace add https://github.com/addyosmani/agent-skills.git /plugin install agent-skills@addy-agent-skills
설치가 끝나면 대화창을 새로 여세요. 이 한 줄을 빠뜨려서 "깔았는데 아무 일도 안 일어난다"고 넘어가는 경우가 가장 많습니다.
진짜 걸리는지 확인
설치됐는지가 아니라 명령이 실제로 도는지를 봐야 합니다. 새 대화창에서 아래를 쳐 보세요.
/spec
SPEC.md 라는 이름으로 저장한 뒤 확인을 요청합니다. 바로 파일을 만들기 시작하면 대화창을 새로 열고 다시 확인하세요.STEP 1 · 3분이게 세 번째 묶음이 아니라는 것부터 알기
이 단계에서는 명령을 치기 전에 이미 깔린 것과의 관계부터 잡습니다. 스킬 묶음은 겹쳐 깐다고 좋아지는 물건이 아니기 때문입니다.
묶음마다 맨 앞에 길잡이 역할을 하는 스킬이 한 장씩 들어 있습니다. 일이 들어오면 "이건 어느 스킬로 보낼 일이다"를 정해 주는 자리입니다.
using-agent-skills 라는 이름이 붙어 있고, 새 일이 들어올 때마다 어느 단계인지 판단해 해당 스킬로 넘깁니다.문제는 이 안내 담당이 두 명이 되는 순간입니다. 저장소가 자기 문서에 그 상황을 이렇게 적어 두었습니다.
> 두 묶음을 동시에 주 안내 담당으로 돌리는 것은 되지 않습니다. 쌓인 안내 담당들이 명령 이름을 두고 다투고(/tdd 가 두 곳에 정의됩니다), 어디로 보낼지를 두고 경쟁하며, 서로 다른 개발 철학을 끌어옵니다. 그러면 양쪽의 좋은 점이 아니라 예측할 수 없는 동작을 얻습니다.
같은 문서가 대안도 적어 두었습니다. 주 안내 담당은 하나만 두고, 나머지 묶음에서는 스킬을 낱개로 빌려 쓰라는 것입니다. 그래서 이 글의 순서는 "깔고 → 겹침 확인"이 아니라 "겹침 확인 → 깔고 → 하나만 남기기"입니다.
STEP 2 · 3분깔고 대화창 새로 열기
이 단계에서는 실제로 깝니다. 명령은 한 줄이고, 그 뒤에 붙는 한 동작이 더 중요합니다.
낱개로 하나만 깔 수도 있습니다. 다만 저장소가 직접 적어 둔 제약이 하나 있습니다.
npx skills add addyosmani/agent-skills --skill test-driven-development
낱개로 깔면 그 스킬 폴더만 복사되고, 저장소가 따로 두고 있는 참고 체크리스트 일곱 장은 따라오지 않습니다. 스킬은 그래도 돌지만 체크리스트를 가리키는 자리가 비게 됩니다. 저장소는 이 문제를 숨기지 않고 공식 이슈 361번으로 열어 두었습니다. 처음이라면 통째로 까는 쪽이 편합니다.
STEP 3 · 4분명령 아홉 개가 어느 칸에 붙는지
이 단계에서는 아홉 개가 각각 언제 부르는 것인지 확인합니다. 이름을 외우는 것보다 어느 칸에서 부르는지를 아는 쪽이 실제로 쓰이기 때문입니다.
/ 를 먼저 치고 이름을 적어 부르는 명령입니다. 문장으로 부탁하는 대신 이름을 직접 불러서, 지금 어느 작업을 시키는지 사람이 정합니다.아래 "언제 부르나"와 "저장소가 박아 둔 원칙"은 저장소 README 의 표를 옮긴 것입니다. 제가 요약한 게 아닙니다.
| 명령 | 언제 부르나 | 저장소가 박아 둔 원칙 |
|---|---|---|
/spec | 무엇을 만들지 정할 때 | 코드보다 문서가 먼저다 |
/plan | 어떻게 만들지 나눌 때 | 작고 쪼갤 수 없는 일 단위로 |
/build | 한 칸씩 지을 때 | 한 번에 한 조각만 |
/test | 진짜 되는지 증명할 때 | 시험이 곧 증거다 |
/constraints | 품질 기준을 정할 때 | 한 번 정하고 어디서나 지킨다 |
/review | 합치기 전에 볼 때 | 코드의 건강을 올린다 |
/webperf | 웹 화면이 느릴 때 | 고치기 전에 먼저 잰다 |
/code-simplify | 코드가 읽기 어려울 때 | 영리함보다 명확함 |
/ship | 실제로 내보낼 때 | 빠른 쪽이 더 안전하다 |
명령을 안 불러도 걸리는 자리는 남아 있습니다. 화면을 만들면 화면 담당 스킬이, 연동 규격을 짜면 규격 담당 스킬이 알아서 붙는다고 README 에 적혀 있습니다. 부르는 쪽이 기본이고, 자동은 거드는 쪽입니다.
STEP 4 · 4분핑계를 미리 반박해 두는 자리
이 단계에서는 이 묶음에만 있는 장치 하나를 봅니다. 시키면 잘하다가 슬그머니 단계를 건너뛰는 일이 여기서 줄어들기 때문입니다.
스킬마다 「자주 나오는 핑계」 표가 들어 있습니다. AI가 단계를 건너뛰려고 흔히 대는 말과, 그 말에 대한 반박을 미리 나란히 적어 둔 표입니다. 저장소의 스킬 문서 25장을 직접 세어 보니 23장에 이 표가 있었습니다.
아래는 시험 담당 스킬에 실제로 적힌 줄을 옮긴 것입니다.
| AI가 대는 핑계 | 저장소가 미리 적어 둔 반박 |
|---|---|
| "코드가 돌아간 다음에 시험을 짜겠습니다" | 안 짭니다. 나중에 짠 시험은 동작이 아니라 구현을 검사합니다 |
| "이건 너무 단순해서 시험할 게 없습니다" | 단순한 코드가 복잡해집니다. 시험이 기대 동작을 적어 둔 문서입니다 |
| "시험을 짜면 느려집니다" | 지금만 느려집니다. 나중에 고칠 때마다 빨라집니다 |
| "손으로 눌러 확인했습니다" | 손으로 한 확인은 남지 않습니다. 내일 바꾼 게 깨져도 알 방법이 없습니다 |
| "이건 시제품이라 괜찮습니다" | 시제품이 그대로 실제 제품이 됩니다 |
핑계를 문서에 미리 적어 둔다는 발상이 이 묶음의 성격입니다. 규칙만 적어 두면 대화가 길어질수록 조용히 무시되는데, 무시할 때 쓸 문장까지 같이 반박해 두면 빠져나갈 자리가 줄어듭니다.
각 스킬은 「위험 신호」 목록으로도 닫힙니다. 예를 들어 시험 담당 스킬은 "한 번에 통과한 시험" 을 위험 신호로 적어 두었습니다. 생각한 것을 검사하고 있지 않을 수 있다는 이유입니다.
STEP 5 · 3분계획을 한 번만 승인하고 놓아 두기
이 단계에서는 사람이 매번 끼지 않아도 되는 방식을 봅니다. 칸마다 승인하는 게 기본인데, 그게 부담이 되는 경우가 있기 때문입니다.
/build 는 다음 한 칸만 짓고 멈춥니다. 뒤에 auto 를 붙이면 계획을 한 번 승인한 뒤 모든 칸을 이어서 짓습니다.
/build auto
검증을 없애는 게 아니라 사람이 작업 사이에 끼는 것만 없앱니다. README 에 그렇게 적혀 있고, 실제로 멈추는 조건이 문서에 박혀 있습니다.
- 설계 문서가 없으면 시작하지 않습니다.
/spec을 먼저 부르라고 말하고 멈춥니다. 요구사항을 지어내지 않습니다 - 저장 안 한 변경이 남아 있으면 멈추고 물어봅니다. 남의 작업을 자기 저장점에 섞지 않기 위해서입니다
- 시험이 통과하지 않거나 빌드가 깨지면 멈춥니다
- 되돌릴 수 없는 일 앞에서 멈춥니다 — 권한 변경, 데이터 이전, 결제, 삭제, 배포, 비밀값을 건드리는 일
- 승인은 분명한 말만 인정합니다. "괜찮아 보이네요" 같은 애매한 답은 승인으로 치지 않습니다
막힌 것을 사람이 풀어 준 뒤 다시 /build auto 를 부르면 멈춘 칸의 다음부터 이어 갑니다.
STEP 6 · 4분이미 깔아 둔 것과 부딪치는지 보고 하나만 남기기
이 단계에서는 STEP 1 에서 예고한 정리를 실제로 합니다. 같은 이름의 스킬이 두 곳에서 오면 어느 쪽이 도는지 알 수 없기 때문입니다.
먼저 지금 깔린 것을 전부 봅니다.
npx skills list
부딪치기 쉬운 이름은 정해져 있습니다. 시험 담당 스킬처럼 어느 묶음에나 들어 있는 이름입니다. 스킬 묶음을 두 개 이상 깔았다면 여기부터 봅니다.
지울 것을 정했으면 이름을 대고 지웁니다.
npx skills remove test-driven-development
npx skills list 를 쳐서 같은 이름이 한 번만 보이는지 확인하세요.정리 기준은 저장소 문서를 그대로 따릅니다. 주 안내 담당은 하나만 둡니다. 다른 묶음에서 쓰고 싶은 스킬이 있으면 그 스킬만 낱개로 남겨 두면 됩니다. 이건 문서 파일이라 낱개로 빌리는 데는 문제가 없다고 저장소가 적어 두었습니다.
STEP 7 · 3분근거가 어디서 왔는지 확인하기
이 단계에서는 이 묶음을 믿을지 말지를 별 개수 말고 다른 것으로 정합니다. 별 9만 개는 관심의 크기지 내용의 근거가 아니기 때문입니다.
열어서 확인할 수 있는 것은 두 가지였습니다.
첫째, 규칙의 출처를 이름으로 밝혀 둡니다. 스킬 안의 원칙들이 어느 책과 어느 문서에서 온 것인지 저장소가 직접 적었습니다. 연동 규격 설계의 하이럼 법칙, 시험의 비욘세 규칙과 시험 피라미드, 검토의 변경 크기 기준, 단순화의 체스터턴의 울타리가 그렇습니다. 출처는 구글 엔지니어링 관행 공식 문서와 Software Engineering at Google 공식 자료입니다. 마음에 안 들면 원문을 열어 반박할 수 있다는 뜻입니다.
둘째, 경쟁 저장소와의 비교 문서를 자기가 써 두었습니다. 저장소가 직접 쓴 비교 문서에서 superpowers 공식 GitHub와 mattpocock/skills 공식 GitHub를 나란히 놓고, 자기가 못 하는 것도 같이 적었습니다.
> 세 묶음 중 어느 것도 대화창을 넘겨 기억을 이어 가는 문제를 아직 잘 풀지 못했습니다. 한 대화창에서 배운 것이 다음 대화창으로 깔끔히 넘어가는 경우는 드뭅니다. 이게 지금 막고 있는 지점이라면, 어느 쪽을 골라도 오늘 나온 것으로는 부족하고 직접 메워야 한다는 것을 알아 두세요.
같은 문서가 별 개수를 일부러 뺐다고도 적었습니다. 블로그마다 다르게 인용되고 주마다 바뀌기 때문이라는 이유입니다. 자기 자랑에 쓸 수 있는 숫자를 스스로 뺀 문서라는 점이, 별 개수보다 확인하기 쉬운 신호입니다.
만든 사람 이름도 같은 잣대로 봅니다. 깃허브 프로필에 소속이 구글로 적혀 있고 팔로워는 52,835명이지만, 이름 자체는 근거가 아닙니다. 위 두 가지처럼 열어서 확인할 수 있는 것만 근거로 쓰세요.
자주 막히는 곳
| 증상 | 원인 | 해결 |
|---|---|---|
| 등록할 때 권한이 거부됐다는 영문 줄이 뜬다 | 저장소를 다른 방식으로 받으려 한다 | 주소를 https://github.com/addyosmani/agent-skills.git 로 끝까지 적어 다시 등록한다 |
| 깔았는데 명령이 목록에 없다 | 설치 전에 열어 둔 대화창이다 | 대화창을 새로 연다 |
| 낱개로 깔았더니 체크리스트를 못 찾는다 | --skill 은 공용 체크리스트를 안 가져온다 | 통째로 깔거나 저장소를 통째로 내려받는다 |
| 같은 이름의 스킬이 두 번 보인다 | 다른 묶음과 이름이 부딪친다 | 한쪽을 지우고 주 안내 담당을 하나만 남긴다 |
/build auto 가 시작하자마자 멈춘다 | 설계 문서가 없다 | /spec 을 먼저 부른다 |
| 명령을 불렀는데 엉뚱한 칸으로 간다 | 안내 담당이 두 명이라 서로 다툰다 | 다른 묶음의 안내 담당을 내린다 |
FAQ
이미 다른 스킬 묶음을 깔았는데 이것도 깔아도 되나요
낱개로 빌려 쓰는 것은 됩니다. 두 묶음을 동시에 주 안내 담당으로 두는 것은 안 됩니다. 저장소가 자기 문서에 그렇게 적어 두었고, 이유로 명령 이름 충돌과 서로 다른 개발 철학을 들었습니다. 하나를 주로 정하고 나머지는 필요한 스킬만 남기세요.
스물다섯 개를 다 깔아야 하나요
아닙니다. 낱개 설치가 됩니다. 다만 낱개로 깔면 공용 체크리스트가 안 따라오니, 그 점을 감수할지 먼저 정하세요.
npx skills add addyosmani/agent-skills --skill code-review-and-quality
클로드 코드 말고 다른 도구에도 되나요
됩니다. 저장소 README 에 도구별 명령이 따로 적혀 있습니다. 아래는 그중 두 개를 옮긴 것입니다.
codex plugin marketplace add addyosmani/agent-skills gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
커서·윈드서프·코파일럿은 명령이 아니라 파일을 놓는 방식이라, 저장소의 도구별 안내 문서를 보고 따라가야 합니다.
별이 9만 개면 안전한가요
아닙니다. 별은 관심도 신호일 뿐 코드의 안전이나 내 환경과의 호환을 보장하지 않습니다. 설치 전에 저장소 주인, 마지막 수정 날짜, 들어오는 파일 수를 확인하세요. 이 묶음은 통째로 깔면 스킬 25장이 한 번에 들어오니, --list 로 목록을 먼저 보는 편이 안전합니다.
명령을 아홉 개 다 외워야 하나요
아닙니다. 저장소 문서는 작은 변경이면 앞 칸을 건너뛰고 /test 와 /review 로 바로 가도 된다고 적었습니다. 처음에는 /spec 하나만 불러 보고, 되묻는 게 마음에 들면 다음 칸으로 넘어가는 쪽을 권합니다.
돈이 드나요
들지 않습니다. MIT 라이선스로 공개돼 있고, 설치 명령도 무료로 쓰는 방식입니다.
알아 둘 한계
대화창을 새로 열면 기억이 이어지지 않습니다. 저장소가 자기 비교 문서에 적어 둔 한계고, 자기만이 아니라 비교한 세 묶음 전부의 한계라고 밝혔습니다. 어제 대화에서 정한 것을 오늘 대화가 알고 있기를 기대하면 안 됩니다.
사람이 불러야 도는 자리가 있습니다. 칸마다 사람이 확인하고 넘어가는 방식이 기본값입니다. 시켜 놓고 아예 자리를 뜨고 싶다면 이 방식은 손이 더 갑니다.
낱개로 깔면 공용 체크리스트가 안 따라옵니다. 저장소가 이슈 361번으로 열어 둔 문제고, 아직 닫히지 않았습니다.
핑계 반박표가 모든 스킬에 있는 건 아닙니다. 저장소의 스킬 문서 25장을 직접 세어 보니 23장에 있었고, 두 장(idea-refine, using-agent-skills)에는 없었습니다.
우리는 이 묶음을 설치해서 돌려 보지 않았습니다. 이 글의 수치는 2026년 8월 30일에 깃허브에서 직접 읽은 값이고, 동작 설명은 저장소의 스킬 문서와 명령 문서를 읽고 옮긴 것입니다. 실제 설치 결과는 쓰는 도구와 버전에 따라 다를 수 있습니다.
공식 자료
- 저장소 — agent-skills 공식 GitHub · 스킬 25개 · MIT
- 소개 페이지 — agent-skills 공식 사이트
- 세 묶음 비교 — 저장소가 직접 쓴 비교 문서
- 설치에 쓰는 명령 — skills 명령 공식 저장소
- 규칙의 출처 — 구글 엔지니어링 관행 공식 문서 · Software Engineering at Google 공식 자료
- 낱개 설치 제약 — 공식 이슈 361번