데일리 밥

Agent Skills 설치하는 법 — Claude Code 에 시니어의 작업 순서를 심는 플러그인 [1/6]

Daily BaapIT/전자기기

Claude Code 한테 일을 시키면 사양도 안 묻고, 테스트도 안 짜고, 곧바로 코드부터 쓰기 시작하는 게 불안하신가요?

답부터 드리면, Agent Skills 라는 플러그인을 설치하면 Claude Code 가 「사양 → 계획 → 구현 → 테스트 → 검토 → 출시」 순서를 지키게 만들 수 있어요. Addy Osmani 가 만들어 GitHub 에 MIT 라이선스로 공개한 것이고, 설치는 명령 두 줄이에요. 이 글은 그 설치와 첫 확인까지를 다루고, 명령 하나하나는 다음 글부터 이어서 봅니다.

이 시리즈 — ① 설치와 첫 확인(이 글) · ② /spec — 만들 것을 먼저 문서로 · ③ /plan — 일을 한 번에 끝낼 크기로 · ④ /build 와 /test · ⑤ /review 와 /ship · ⑥ 알아서 켜지는 스킬과 한계

Agent Skills 가 뭔가 — 「스킬」부터

Claude Code 에서 스킬(skill) 은 폴더 하나에 SKILL.md 파일을 둔 것이에요. 파일 머리에 「이 스킬은 무엇을 하고 언제 쓴다」는 설명이 있고, 본문에 절차가 적혀 있어요. Claude Code 는 매 대화에서 스킬들의 설명만 먼저 읽어 두다가, 지금 하는 일과 맞는 스킬이 있으면 본문을 꺼내 그대로 따라가요. 공식 문서 Claude Code — Skills에 이 구조가 설명돼 있어요.

Agent Skills 는 그런 스킬을 24개 묶어 놓은 플러그인이에요. 저장소 addyosmani/agent-skills 의 README 는 이걸 「시니어 엔지니어가 소프트웨어를 만들 때 따르는 작업 순서와 품질 검문을 문서로 적어, AI 에이전트가 매번 같은 순서로 일하게 한 것」이라고 설명해요. 개발 단계별로 나뉘어 있어요.

  DEFINE       PLAN        BUILD       VERIFY      REVIEW      SHIP
  아이디어 →   사양   →    코드   →    테스트  →   검토   →    출시
  /spec        /plan       /build      /test       /review     /ship

여기에 검토·보안·테스트·성능을 각각 맡는 에이전트(페르소나) 4개와, 위 순서를 명령 한 줄로 부르는 슬래시 명령 8개가 같이 들어 있어요.

스킬 하나의 생김새는 전부 같아요. 「무엇을 하나 → 언제 쓰나 → 절차 → 건너뛰고 싶을 때 대는 핑계와 그 반박 → 잘못되고 있다는 신호 → 끝났다고 말하려면 필요한 증거」순이에요. README 가 강조하는 설계 원칙 하나가 재미있어요. 「설명이 아니라 절차다」, 그리고 「증거 없이 끝났다고 하지 않는다」 — 테스트 통과 출력이나 실행 결과가 없으면 “된 것 같다”는 말은 인정하지 않아요.

시작하기 전에 — 필요한 것

  • Claude Code 가 설치되고 로그인돼 있어야 해요. 터미널용 Claude Code 는 Pro·Max·Team·Enterprise 구독이나 API 계정이 필요하다고 공식 문서에 적혀 있어요. 설치 자체는 이 블로그의 코딩 몰라도 쓰는 코딩 AI 글에 화면 순서대로 정리해 두었어요.
  • GitHub 에 접근되는 인터넷 연결. 플러그인은 GitHub 저장소를 내려받아 설치돼요.
  • jq 가 있으면 좋아요. 세션이 열릴 때 안내 스킬을 자동으로 넣어 주는 훅이 jq 를 써요. 없어도 설치는 되고 스킬도 하나하나는 동작하지만, 자동 안내만 빠져요. 훅 스크립트가 그렇게 적어 두고 있어요.

설치 절차 — 명령 두 줄

Claude Code 를 켠 상태에서 아래를 차례로 입력해요. 공식 문서 Claude Code — Discover and install plugins 에 나오는 마켓플레이스 방식이에요.

  1. 터미널에서 claude 를 실행해 Claude Code 대화창을 열어요.
  2. 마켓플레이스를 등록해요. 이 저장소 자체가 마켓플레이스 역할을 해요.
/plugin marketplace add addyosmani/agent-skills
  1. 플러그인을 설치해요. 이름 뒤의 @addy-agent-skills 가 방금 등록한 마켓플레이스 이름이에요.
/plugin install agent-skills@addy-agent-skills
  1. 대화창을 닫고 claude 를 다시 켜요. 플러그인의 스킬과 명령은 새 세션부터 실려요.

설치됐는지 확인하는 법 — 두 가지

첫째는 대화창에서 /agent-skills: 까지 쳐 보는 거예요. 자동완성에 spec·plan·build·test·review·ship·webperf·code-simplify 가 뜨면 된 거예요. README 에는 /spec 처럼 짧게 적혀 있지만, 플러그인으로 설치한 명령은 앞에 플러그인 이름이 붙어요.

둘째는 터미널에서 구성 목록을 보는 거예요. 이 글을 쓰면서 설치된 환경에서 실제로 돌린 출력이에요.

$ claude plugin details agent-skills@addy-agent-skills

agent-skills 0.6.6
  Source: agent-skills@addy-agent-skills

Component inventory
  Skills (32)  api-and-interface-design, browser-testing-with-devtools, build, …
  Agents (4)   code-reviewer, test-engineer, web-performance-auditor, security-auditor
  Hooks (1)    SessionStart  (harness-only — no model context cost)

Projected token cost
  Always-on:   ~2,814 tok   added to every session

스킬이 24개가 아니라 32개로 나오는 건 슬래시 명령 8개도 스킬 형태로 등록되기 때문이에요. 맨 아래 「항상 켜져 있는 토큰 약 2,800개」 는 뒤에서 다시 볼 값이에요. 이 플러그인을 켠 이상 모든 대화가 그만큼 무거워진다는 뜻이에요.

다른 도구에서도 쓸 수 있나

돼요. Cursor·Codex·Copilot 같은 도구에는 Vercel 이 만든 skills CLI 로 넣을 수 있다고 README 가 안내해요.

npx skills add addyosmani/agent-skills            # 24개 전부
npx skills add addyosmani/agent-skills --list     # 목록만 먼저

다만 이 글의 나머지 부분은 Claude Code 기준이에요. 슬래시 명령과 에이전트는 도구마다 붙이는 방법이 달라서, 저장소의 docs/ 폴더에 도구별 안내가 따로 있어요.

명령 8개 지도 — 어느 것부터 쓰나

지금 하려는 일 명령 한 줄 원칙
무엇을 만들지 정한다 /spec 코드보다 사양이 먼저
어떻게 만들지 쪼갠다 /plan 작고 검증 가능한 작업으로
하나씩 만든다 /build 한 번에 한 조각
되는지 증명한다 /test 테스트가 곧 증거
합치기 전에 본다 /review 코드 건강을 올리는가
웹 성능을 잰다 /webperf 재기 전엔 고치지 않는다
복잡한 걸 덜어낸다 /code-simplify 영리함보다 명료함
내보낸다 /ship 빠른 것이 안전한 것

처음이라면 /spec 하나만 써 보시길 권해요. 사양 문서 없이는 뒤의 /plan·/build auto 가 아예 시작하지 않게 만들어져 있어서, 이 순서를 몸에 익히는 데 그게 가장 빨라요. 다음 글에서 다룰게요.

설치가 막히는 경우

git@github.com: Permission denied (publickey) 로 설치가 실패해요. 마켓플레이스 등록은 되는데 install 만 실패하면 거의 이거예요. Claude Code 가 플러그인을 SSH 주소로 내려받는데, GitHub 에 SSH 키를 등록하지 않은 컴퓨터가 많아요. README 가 안내하는 해결은 GitHub 의 SSH 주소를 HTTPS 로 바꿔 쓰게 git 에 한 번 설정해 두는 거예요.

git config --global url."https://github.com/".insteadOf git@github.com:

이 설정은 이 컴퓨터의 다른 GitHub 작업에도 적용되니, 나중에 되돌리려면 git config --global --unset url."https://github.com/".insteadOf 를 쓰면 돼요.

스킬 하나만 골라 받았는데 어떤 검토 목록이 없다고 해요. npx skills add … --skill 이름 으로 하나만 받으면 스킬 폴더만 복사되고, 저장소 공용 references/ 폴더(보안·성능·접근성 체크리스트)는 따라오지 않아요. README 가 이 한계를 이슈 #361 로 적어 두었어요. 전체를 받는 쪽이 간단해요.

설치했는데 아무것도 안 달라져요. 설치 뒤 세션을 새로 열지 않은 경우가 대부분이에요. 그리고 스킬은 강제 장치가 아니라 지침이에요. 모델이 설명을 읽고 스스로 꺼내는 방식이라, 일이 너무 작거나 지시가 「빨리 해 줘」 쪽이면 스킬을 건너뛸 수 있어요. 확실히 태우고 싶으면 슬래시 명령으로 직접 부르세요.

이럴 땐 굳이 쓰지 마세요

오타 하나 고치기, 변수 이름 바꾸기, 파일 옮기기처럼 한 줄이면 끝나는 일에는 이 플러그인이 하는 일이 없어요. 스킬마다 「이럴 땐 쓰지 마라」 항목이 따로 있고, 전부 이런 경우를 꼽고 있어요.

그리고 코드가 아닌 일 — 메모 정리, 문서 폴더 정돈 — 에 Claude Code 를 쓰는 분이라면 이 플러그인의 값이 별로 없어요. 스킬들이 전부 테스트·빌드·커밋을 전제로 하기 때문이에요. 그런 용도라면 항상 켜지는 토큰만 늘어나요.

✔ 요약

  • Agent Skills = Claude Code 스킬 24개 + 에이전트 4개 + 명령 8개, MIT
  • 설치 두 줄: /plugin marketplace add addyosmani/agent-skills → /plugin install agent-skills@addy-agent-skills
  • 새 세션에서 /agent-skills: 자동완성 또는 claude plugin details 로 확인
  • 항상 켜지는 토큰 약 2,800개 — 켜 두는 비용이 있다
  • publickey 에러는 insteadOf 설정 한 줄로
  • 한 줄짜리 일과 코드 아닌 일에는 값이 없다
  • 2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: addyosmani/agent-skills 저장소 · Claude Code — Plugins · Claude Code — Skills · Claude Code — Discover and install plugins

← 목록으로