Claude Code 팀 애디 오스마니의 Agent Skills 25개 정리: AI 코딩 에이전트를 '신입'처럼 다루는 법 (2026)

AI 코딩 에이전트에게 "로그인 기능 만들어 줘"라고 하면 대부분 바로 코드부터 씁니다. 무엇을 위한 기능인지 묻지 않고, 테스트는 "나중에" 쓰겠다고 하고, 다 됐다고 말한 뒤 실제로는 돌아가지 않는 경우도 많습니다. 이 문제를 정면으로 다루는 스킬 모음이 Agent Skills(addyosmani/agent-skills)입니다. 구글에서 14년 넘게 일하고 2026년 앤트로픽에 합류해 Claude Code 일을 하고 있는 애디 오스마니(Addy Osmani)가 만든 저장소로, 11월 13일 아침에도 GitHub 데일리 트렌딩 목록에 올라 있었습니다.

이 글은 민둥이 채널의 소개 영상을 보고 출발했지만, 설명과 숫자는 모두 저장소 README, 각 스킬 파일(SKILL.md), 평가 문서, 오스마니 본인의 블로그 글로 다시 확인했습니다. 스타·포크 수는 2026년 11월 13일 오전 8시 52분(한국시간) GitHub API로 조회한 값입니다.

지난 글(11월 10일 깃허브 트렌딩 AI 오픈소스 TOP 10)에서 다룬 앤트로픽 공식 저장소(anthropics/skills)는 "스킬 표준과 예제"에 가깝고, 오늘 소개하는 저장소는 "개발 업무 방식"을 스킬로 묶은 별개의 프로젝트입니다.

Agent Skills는 어떤 저장소인가

addyosmani/agent-skills GitHub 저장소 화면 (2026-11-13 촬영)

README의 한 줄 소개는 "AI 코딩 에이전트를 위한 실무 수준의 엔지니어링 스킬"입니다. 숙련된 개발자가 소프트웨어를 만들 때 지키는 작업 순서, 품질 관문, 모범 사례를 스킬 파일로 만들어 두고, 에이전트가 개발의 모든 단계에서 그것을 일관되게 따르게 하는 것이 목표입니다.

• 스타 약 116,700개, 포크 약 12,200개, MIT 라이선스 (2026년 2월 공개)
• 스킬 25개: 24개의 단계별 스킬 + 어떤 스킬을 쓸지 골라 주는 메타 스킬(using-agent-skills) 1개
• 개발 과정을 정의(Define) → 계획(Plan) → 구현(Build) → 검증(Verify) → 리뷰(Review) → 배포(Ship) 여섯 단계로 나누고, 각 단계에 맞는 슬래시 명령 9개(/spec, /plan, /build, /test, /review, /ship 등)를 제공
• Claude Code, Cursor, Codex, Gemini CLI, Copilot, Windsurf, OpenCode, Kiro 등 여러 도구 설치 방법을 README에 정리

README의 6단계 개발 흐름 도식

오스마니는 블로그에서 AI 코딩 에이전트를 "가장 짧은 길로 '완료'에 가려는" 존재로 설명합니다. 스펙, 테스트, 리뷰처럼 diff에 드러나지 않는 일을 건너뛰는 버릇이 있으니, 숙련된 개발자가 옆에서 챙겨 줄 일을 미리 글로 적어 두자는 발상입니다. README도 이 스킬들에 구글의 엔지니어링 관행(Software Engineering at Google, 구글 코드 리뷰 가이드 등)이 녹아 있다고 밝힙니다.

출처: GitHub · Addy Osmani 블로그 "Agent Skills"

1. interview-me: 짐작에 확신도를 붙여서 하나씩 묻는다

interview-me 스킬의 1단계: 가설과 확신도 숫자를 먼저 적는다

요청이 모호할 때 쓰는 스킬입니다. 특징은 질문하기 전에 AI가 "지금 내가 이해한 요청은 이것이고, 확신도는 약 30%"처럼 자기 짐작과 숫자를 먼저 적는다는 점입니다. 확신도가 70%보다 낮으면 무엇이 부족한지도 함께 적어야 합니다. 그다음 질문은 한 번에 하나씩, 각 질문에 자기 추측을 붙여서 던집니다. 사용자는 빈칸을 채우는 것보다 틀린 추측을 고치는 쪽이 훨씬 빠르기 때문입니다.

"빠르게 해 줘" 같은 말은 해석하지 않고 숫자로 되묻는 것이 원칙이고, 확신도가 약 95%에 이르면 질문을 멈추고 이해한 내용을 5~8줄로 정리해 확인받습니다.

왜 중요한가: AI가 요구사항의 빈칸을 몰래 채워 넣는 순간부터 결과물이 엇나갑니다. 확신도 숫자는 AI가 "대충 알겠다"고 넘어가지 못하게 만드는 장치입니다.

써 보기: 이 스킬 하나만 설치할 수도 있습니다. npx skills add addyosmani/agent-skills --skill interview-me

출처: interview-me/SKILL.md

2. 스펙과 계획: 쓰고, 멈추고, 승인받는다

spec-driven-development 스킬은 코드를 쓰기 전에 목표, 명령어, 구조, 코드 스타일, 테스트, 경계를 담은 스펙 문서를 쓰게 합니다. 경계는 세 칸으로 나눕니다.

• 항상 할 일(Always): 커밋 전 테스트 실행, 이름 규칙 지키기, 입력값 검증
• 먼저 물어볼 일(Ask first): DB 스키마 변경, 의존성 추가, CI 설정 변경
• 절대 하지 않을 일(Never): 비밀 키 커밋, vendor 폴더 수정, 승인 없이 실패하는 테스트 삭제

스펙을 다 쓰면 스킬 문서에 대문자로 "STOP"이 적혀 있습니다. 사람에게 승인을 요청하고 그 턴을 끝내야 하며, 계획이나 코드는 승인을 받은 다음 턴부터 시작합니다. 이어지는 planning-and-task-breakdown 스킬은 작업을 DB·서버·화면 같은 층별로 나누지 않고 기능 하나를 끝까지 관통하는 얇은 조각(vertical slice)으로 자르고, 작업마다 무엇으로 확인할지(검증 방법)를 붙이게 합니다.

왜 중요한가: 층별로 만들면 마지막에 합칠 때까지 아무것도 돌아가지 않습니다. 기능 단위로 자르면 조각마다 실제로 동작하는 결과를 확인할 수 있습니다.

출처: spec-driven-development · planning-and-task-breakdown

3. 변명 방지표(Anti-rationalization): AI가 할 핑계에 미리 답해 둔다

test-driven-development 스킬의 Common Rationalizations 표

이 저장소에서 가장 독특한 부분입니다. 모든 스킬에 "흔한 핑계 ↔ 실제" 표가 들어 있습니다. 예를 들어 테스트 주도 개발(TDD) 스킬에는 이런 줄이 있습니다.

• "코드가 돌아가면 그때 테스트를 쓰겠다" → 안 쓸 것이다. 사후에 쓴 테스트는 동작이 아니라 구현을 검사한다.
• "너무 간단해서 테스트할 필요가 없다" → 간단한 코드도 복잡해진다.
• "손으로 직접 확인했다" → 수동 확인은 남지 않는다. 내일 변경이 망가뜨려도 알 방법이 없다.

표 아래에는 의심해야 할 신호(Red Flags) 목록이, 스킬 맨 끝에는 증거 요구 목록(Verification)이 붙습니다. 테스트 통과 결과나 실제 실행 기록 같은 증거가 있어야 "다 했다"가 인정됩니다.

오스마니는 블로그에서 이 표를 "에이전트가 아직 하지도 않은 거짓말에 미리 써 둔 반박"이라고 부르며, 다른 팀이 가장 가져갔으면 하는 설계라고 적었습니다. LLM은 "이번 작업은 스펙이 필요 없는 이유"를 그럴듯하게 지어내는 데 능하기 때문입니다.

써 보기: 스킬을 설치하지 않더라도, 팀이 자주 하는 핑계와 반박을 AGENTS.md나 사내 위키에 적어 두라는 것이 오스마니의 제안입니다.

출처: test-driven-development/SKILL.md · 블로그 원문

4. constraint-driven-development: 기준을 낮추는 꼼수를 잡는다

에이전트는 검사를 통과하기 어려우면 검사 자체를 느슨하게 만들기도 합니다. 실패하는 테스트에 .skip을 붙이거나, 단언문(assertion)을 빼거나, @ts-ignore·eslint-disable을 슬쩍 넣거나, 통과 기준 숫자를 내리는 식입니다. 이 스킬은 품질 기준을 사용자와 함께 정해 CONSTRAINTS.md에 숫자로 적고, 리뷰 때 diff에서 이런 흔적을 찾게 합니다. 원칙은 한 문장입니다. "기준을 올리는 건 조용히 해도 되지만, 내리는 건 시끄럽게 해야 한다."

왜 중요한가: "테스트 전부 통과"라는 보고가 테스트를 지워서 얻은 결과일 수 있습니다. 기준 변경 자체를 검토 대상으로 삼으면 이런 착시를 막을 수 있습니다.

출처: constraint-driven-development/SKILL.md

5. doubt-driven-development: 결론은 빼고 결과물만 검토자에게

AI가 "이 부분은 안전합니다"처럼 자신 있게 말할 때 쓰는 스킬입니다. 새 맥락의 검토자(서브에이전트)를 따로 띄우고 "이 결과물에서 틀린 곳을 찾아라, 작성자가 자신감이 지나치다고 가정하라"는 적대적 리뷰를 맡깁니다.

핵심은 넘기는 정보입니다. 검토자에게는 결과물과 지켜야 할 조건(계약)만 주고, 작성자의 결론과 추론은 주지 않습니다. 스킬 문서는 "결론을 넘기면 결론을 맞다고 해 주는 답이 돌아온다"고 이유를 적어 두었습니다. 다만 반대로 검토자가 맥락이 없어서 틀릴 수도 있으니, 반대 의견은 "판결이 아니라 정보"로 다루라고도 적혀 있습니다.

출처: doubt-driven-development/SKILL.md

6. /ship: 검토자 셋이 따로 보고, 결론은 GO 또는 NO-GO

배포 직전에 /ship을 실행하면 세 명의 전문 검토자(페르소나)가 동시에 붙습니다.

• code-reviewer: 정확성, 가독성, 구조, 보안, 성능 다섯 축 리뷰
• security-auditor: OWASP Top 10, 비밀 키 처리, 인증·권한, 의존성 취약점 점검
• test-engineer: 정상 경로, 경계값, 오류 경로, 동시성에서 테스트가 빠뜨린 경우 찾기

세 검토자는 서로를 부르지 않고 각자 보고서만 돌려줍니다. 메인 에이전트가 이를 합쳐 GO 또는 NO-GO 한 가지로 결론을 내고, 하나라도 심각(Critical) 문제가 나오면 사용자가 위험을 명시적으로 받아들이지 않는 한 기본값은 NO-GO입니다. GO를 내기 전에는 롤백 계획(되돌릴 조건과 절차, 목표 복구 시간)을 반드시 적어야 합니다.

출처: .claude/commands/ship.md

7. 스킬이 실제로 켜지는지까지 측정한다

스킬은 설치해 둔다고 매번 쓰이지 않습니다. 모델이 "이 스킬이 필요하다"고 판단해야 불려 나옵니다. 이 저장소는 스킬마다 평가 케이스(evals/cases, 25개 파일)를 두고, 스킬이 제대로 켜지는지와 엉뚱한 상황에서 켜지지 않는지를 함께 시험합니다.

평가 문서에 적힌 사례가 흥미롭습니다. 코드 리뷰를 부탁하는 네 가지 표현으로 시험했더니 리뷰 스킬이 27번 중 7번만 켜졌습니다. 스킬 설명에 "diff를 대화창에 바로 붙여 넣은 경우에도 적용된다"는 구절 하나를 넣자 27번 중 21번으로 늘었고, 켜지면 안 되는 상황에서는 여전히 0번이었습니다. 문서는 이를 "나아졌지만 해결된 것은 아니다"라고 정리합니다. 모델과 Claude Code 버전에 따라 수치가 달라질 수 있어 버전을 고정하고 기록하라는 당부도 함께 있습니다.

왜 중요한가: 직접 스킬을 만들어 쓰는 분이라면 "왜 내 스킬이 안 켜지지?"의 답이 대개 스킬 설명(description) 문구에 있다는 실전 힌트입니다.

출처: evals/README.md

Superpowers, 맷 포콕 스킬과 무엇이 다를까

저장소의 docs/comparison.md 비교표

저장소에는 비슷한 스킬 모음 두 개와 자신을 비교한 문서(docs/comparison.md)가 있습니다. 요약하면 이렇습니다.

	Agent Skills	Superpowers (obra)	맷 포콕 스킬
성격	기획부터 배포까지 전체 개발 주기	서브에이전트 중심의 자율 실행 방법론	한 개발자의 Claude Code 일상 작업 도구 모음
스킬 수(문서 기준)	25개	약 14개	약 30개
추천 상황	기능 하나를 단계마다 사람이 확인하며 끝까지	큰 덩어리를 맡기고 자리를 비울 때	요구사항 다듬기(grill-me)와 TDD 위주의 가벼운 일상 작업
스타(11/13 08:52 조회)	약 11.7만	약 31.7만	약 32.3만

비교 문서는 셋 중 "최고"는 없고 작업에 맞게 고르라고 결론 내립니다. 또 여러 스킬 모음을 동시에 "주 라우터"로 켜 두면 /tdd 같은 명령 이름이 겹치고 TDD 철학도 서로 달라 동작이 예측하기 어려워지니, 하나를 주력으로 두고 나머지는 필요한 스킬만 골라 쓰라고 권합니다. 참고로 이 문서는 스타 수를 일부러 싣지 않았고, 표의 스타 수는 제가 GitHub API로 조회해 덧붙였습니다.

출처: docs/comparison.md · obra/superpowers · mattpocock/skills

설치와 시작 방법

공식 소개 사이트 skills.addy.ie 첫 화면

README에 나온 방법 중 많이 쓸 만한 것만 추렸습니다.

• 도구 상관없이 한 번에: npx skills add addyosmani/agent-skills (25개 전체), 먼저 목록만 보려면 --list
• Claude Code: /plugin marketplace add addyosmani/agent-skills 후 /plugin install agent-skills@addy-agent-skills. Claude Code에 기본 /review 명령이 있으므로 이 스킬의 리뷰는 /agent-skills:review로 부릅니다.
• Codex(CLI v0.122 이상): codex plugin marketplace add addyosmani/agent-skills 후 codex plugin add agent-skills@agent-skills
• Cursor: 스킬 폴더를 프로젝트의 .cursor/skills/로 옮기고, 짧은 규칙만 .cursor/rules/*.mdc에 두라고 안내합니다(규칙 파일에 스킬 전체를 붙여 넣지 말 것).

주의할 점도 있습니다. 스킬 하나만 npx로 설치하면 저장소 공통 체크리스트(references/ 폴더)는 함께 복사되지 않습니다. 스킬은 동작하지만 일부 참고 문서 경로를 쓸 수 없어서, 전체를 쓰려면 저장소 단위로 설치하는 편이 낫습니다. 또 스킬은 모두 마크다운 글이라, 설치가 부담스럽다면 마음에 드는 부분만 내 에이전트 지침 파일에 옮겨 적어도 됩니다.

애디 오스마니 블로그의 Agent Skills 해설 글 (2026년 5월 3일)

출처: README Quick Start · skills.addy.ie

확인한 사실과 확인하지 못한 내용

확인한 사실

• 스타·포크·라이선스·생성일: GitHub API (2026-11-13 08:52 한국시간 조회)
• 11월 13일 GitHub 데일리 트렌딩 등재: github.com/trending (같은 날 08:52 한국시간 확인)
• 스킬 25개 구성, 9개 명령, 설치 방법: README
• 확신도 30%·95%, Always/Ask first/Never, STOP 규칙, 변명 방지표, "기준 낮추기는 시끄럽게", 결론을 빼고 검토 요청, /ship 3인 검토와 롤백 계획: 각 SKILL.md와 ship.md 원문
• 리뷰 스킬 27번 중 7번 → 21번: evals/README.md
• "아직 하지 않은 거짓말에 미리 쓴 반박": 오스마니 블로그(2026년 5월 3일)
• 오스마니의 경력(구글 14년 이상, 2026년 앤트로픽 합류, Claude Code 담당): addyosmani.com 약력 페이지와 GitHub 프로필

바로잡거나 확인하지 못한 내용

• 소개 영상은 오스마니를 "Claude Code를 만든 사람"이라고 표현했지만, 본인 약력에는 2026년 앤트로픽에 합류해 Claude Code 일을 하고 있다고만 적혀 있습니다. 이 글은 약력 표현을 따랐습니다. 저장소 자체는 그가 구글에 있던 2026년 2월에 공개됐습니다.
• 영상의 "매주 트렌딩에 올라온다"는 표현은 오늘 데일리 트렌딩 등재만 확인했고, 주간 단위로 매번 올랐는지는 확인하지 않았습니다.
• 공식 소개 사이트(skills.addy.ie) 첫 화면에는 아직 "24 skills"라고 적혀 있어, README의 25개(24개 + 메타 스킬)와 차이가 있습니다.

마치며

Agent Skills를 읽어 보면 처음부터 끝까지 한 가지 태도가 일관됩니다. AI의 말을 그대로 믿지 않는다는 것입니다. 무엇을 만들지 물을 때는 확신도를 숫자로 대게 하고, 만드는 중에는 핑계에 미리 답해 두고, 다 됐다고 할 때는 증거와 별도 검토자를 요구합니다. 모델이 똑똑해질수록 오히려 이런 "선배 개발자의 잔소리"가 더 쓸모 있어지는 느낌입니다. 전부 설치하지 않더라도 interview-me와 변명 방지표 두 가지만 내 프로젝트 지침에 옮겨 보시길 권합니다.

출처

• 영감을 받은 영상: 민둥이 | 쉽게 배우는 AI, "매주 깃허브 트렌딩에 올라오는 이유: 클로드 코드 개발자의 AI 노하우 25개" (YouTube)
• addyosmani/agent-skills README, SKILL.md, docs/comparison.md, evals/README.md (2026-11-13 조회)
• Addy Osmani, "Agent Skills" (2026-05-03) · Addy Osmani 약력