[심층분석] AI에게 '시니어처럼 일하는 법'을 가르칠 수 있을까? Addy Osmani의 agent-skills 뜯어보기

들어가며: 코드는 잘 짜는데, '일하는 법'을 모르는 AI

요즘 AI 코딩 도구 안 쓰는 분 거의 없으시죠. Claude Code, Cursor, Copilot 같은 도구들이 코드를 뚝딱 짜주는 시대인데요. 그런데 써보신 분들은 다들 비슷한 답답함을 느끼실 거예요. 코드 자체는 잘 짜는데, 일하는 방식이 없다는 거예요.

비유하자면 이런 거거든요. 알고리즘 문제는 기가 막히게 푸는 신입 개발자가 들어왔어요. 그런데 스펙 정리도 안 하고 바로 코드부터 치고, 테스트도 안 짜고, 커밋은 하루치를 한 방에 몰아서 하는 거예요. 실력이 없는 게 아니라 프로세스가 없는 거죠. 지금의 AI 에이전트가 딱 이 상태인데요.

이 문제를 정면으로 겨냥한 프로젝트가 나왔어요. Google Chrome 팀의 엔지니어링 리더이자 'Learning JavaScript Design Patterns'의 저자로 유명한 Addy Osmani가 공개한 agent-skills예요. 한 줄로 요약하면, "시니어 엔지니어들이 소프트웨어를 만들 때 쓰는 워크플로우, 품질 기준, 베스트 프랙티스를 AI 에이전트가 따라 하도록 패키징한 것"이에요. 작년 말 Anthropic이 Agent Skills라는 개념과 스펙을 공개한 이후 에이전트에게 '지식'을 심어주는 생태계가 빠르게 크고 있는데, 이 프로젝트는 그 흐름의 대표 사례라고 볼 수 있어요.

agent-skills가 뭐냐면: AI를 위한 '사수의 업무 매뉴얼'

먼저 '스킬(Skill)'이라는 개념부터 짚고 갈게요. 스킬이 뭐냐면, 쉽게 말해서 AI가 필요할 때 꺼내 읽는 업무 매뉴얼이에요. 마크다운 문서 형태로 '이런 작업을 할 때는 이런 순서로, 이런 기준을 지키면서 해라'라고 적어둔 거죠. 회사 온보딩 때 받는 사내 위키 문서를 떠올리시면 돼요. 다만 읽는 대상이 신입 사원이 아니라 AI 에이전트인 거예요.

agent-skills는 이런 스킬들을 개발 라이프사이클 전체에 맞춰 구성했어요. 저장소가 제시하는 흐름은 이렇거든요.

아이디어 → 스펙 → 구현 → 테스트 → 리뷰 → 배포

그리고 이 각 단계에 대응하는 8개의 슬래시 커맨드를 제공해요.

• /spec — 뭘 만들지 정의하기. 원칙은 '코드보다 스펙이 먼저'
• /plan — 어떻게 만들지 계획하기. 원칙은 '작고 원자적인 태스크로 쪼개기'
• /build — 한 번에 한 조각씩 점진적으로 구현하기
• /test — '테스트가 곧 증거'라는 원칙으로 동작 증명하기
• /review — 머지 전에 코드 건강성 높이기
• /webperf — '측정 먼저, 최적화는 그다음' 원칙으로 웹 성능 감사하기
• /code-simplify — '영리함보다 명료함'을 기준으로 코드 단순화하기
• /ship — '빠른 배포가 더 안전하다'는 철학으로 프로덕션에 내보내기

특히 재미있는 게 /build의 자율 모드인데요. 스펙만 있으면 계획 생성부터 태스크 구현까지 한 번의 승인으로 쭉 진행돼요. 여기서 중요한 포인트가 있어요. 저장소 설명을 그대로 옮기면, '태스크 사이에 끼어드는 사람을 없앤 것이지, 검증을 없앤 게 아니다'라는 거예요. 모든 태스크는 여전히 테스트 주도로 진행되고, 각각 개별 커밋되고, 실패하거나 위험한 단계에서는 멈춰서 사람을 불러요. 자율성과 안전장치를 어떻게 공존시킬지에 대한 꽤 균형 잡힌 답이라고 봐요.

또 하나, 스킬은 자동으로 활성화돼요. API를 설계하고 있으면 api-and-interface-design 스킬이, UI를 만들고 있으면 frontend-ui-engineering 스킬이 알아서 켜지는 식이에요. 사용자가 '이 매뉴얼 읽어'라고 일일이 지시하지 않아도, 맥락을 보고 알맞은 매뉴얼을 펼치는 거죠.

설치도 간단해요. npx skills add 한 줄이면 되고, Claude Code, Cursor, Codex, Copilot, Cline을 포함해 70개 이상의 에이전트에 설치할 수 있어요. 특정 도구에 묶이지 않는다는 게 큰 장점인데요, 이 얘기는 아래에서 더 할게요.

설계 철학: 왜 '항상 주입'이 아니라 '필요할 때 로드'인가

'그냥 시스템 프롬프트에 규칙을 왕창 넣으면 되는 거 아니야?' 싶으실 수 있는데요. 여기에 중요한 차이가 있어요.

AI 모델에게는 한 번에 읽을 수 있는 분량, 즉 컨텍스트라는 한계가 있어요. 컨텍스트가 뭐냐면, AI의 '작업 기억'이라고 생각하시면 돼요. 여기에 모든 규칙을 다 밀어 넣으면, 백과사전 전질을 매일 가방에 넣고 다니는 것과 같아요. 무겁기만 하고, 정작 필요한 페이지를 찾는 데 방해가 되거든요.

스킬 방식은 다르게 접근해요. 평소에는 각 스킬의 제목과 한 줄 요약만 알고 있다가, 실제로 그 작업을 하게 되면 그때 본문을 펼쳐 읽는 거예요. 이걸 점진적 공개(progressive disclosure)라고 부르는데, 쉽게 말해 필요한 페이지만 그때그때 꺼내 보는 방식이에요. 덕분에 작업 기억을 아끼면서도 깊이 있는 지침을 따를 수 있는 거죠.

업계 맥락: 기존 방식들과 뭐가 다른가

비슷해 보이는 것들이 이미 있죠. 하나씩 비교해 볼게요.

.cursorrules나 CLAUDE.md, AGENTS.md 같은 규칙 파일은 '모니터에 붙여둔 포스트잇'이에요. 항상 눈에 보이지만, 짧아야 하고, 깊은 절차를 담기 어려워요. 반면 스킬은 '책장에 꽂힌 매뉴얼'이에요. 평소엔 자리를 차지하지 않다가 필요할 때 펼쳐지고, 훨씬 길고 구체적인 내용을 담을 수 있어요.

MCP(Model Context Protocol)와도 자주 비교되는데요. MCP가 뭐냐면, AI가 외부 도구(데이터베이스, 브라우저, API 등)를 쓸 수 있게 연결해주는 표준이에요. 비유하자면 MCP는 AI에게 손과 발을 달아주는 거고, 스킬은 노하우가 담긴 머리를 채워주는 거예요. 망치를 쥐여주는 것과 목수 일을 가르치는 것의 차이랄까요. 둘은 경쟁 관계가 아니라 서로 보완하는 관계예요.

GitHub의 Spec Kit이나 Amazon의 Kiro 같은 스펙 주도 개발 도구들과는 철학을 공유해요. '코드보다 스펙 먼저'라는 방향이 같거든요. 다만 이런 도구들이 특정 워크플로우나 플랫폼에 사용자를 데려가는 쪽이라면, agent-skills는 지금 쓰고 있는 에이전트가 뭐든 그 위에 얹는 쪽이에요. 저장소 구조를 봐도 .claude, .codex-plugin, .gemini, .opencode 등 여러 에이전트용 디렉터리가 나란히 있어요. 도구를 갈아타도 팀의 일하는 방식은 유지된다는 게 포지셔닝의 핵심이에요.

한국 개발자에게 주는 시사점

구체적으로 어떻게 써먹을 수 있을지 볼게요.

시나리오 1: AI 결과물의 품질 편차가 고민인 팀. Cursor나 Claude Code를 팀에서 쓰는데, 사람마다 프롬프트 실력이 달라서 결과물이 들쭉날쭉하다면요. npx skills add로 이 스킬셋을 깔고 /review, /test부터 써보세요. 전 과정을 한 번에 바꾸려 하지 말고, 리뷰와 테스트처럼 효과가 바로 보이는 단계부터 도입하는 게 좋아요.

시나리오 2: 팀 컨벤션을 AI에게 물려주고 싶은 경우. 이 저장소의 진짜 가치는 '가져다 쓰기'보다 '보고 배우기'에 있다고 생각하는데요. skills 폴더의 문서들을 열어보면, 시니어의 암묵지를 어떻게 글로 구조화하는지에 대한 훌륭한 예시가 가득해요. 이 형식을 참고해서 우리 팀의 코드 리뷰 기준, 배포 절차, 네이밍 규칙을 스킬로 직접 작성해보세요. 사수가 후배에게 구두로 전수하던 노하우가, 버전 관리되는 문서 자산이 되는 거예요.

학습 로드맵을 제안하자면 이래요. 1단계, README와 스킬 문서 몇 개를 정독하면서 구조를 파악하기. 2단계, 개인 사이드 프로젝트에서 /spec부터 /ship까지 전체 사이클을 한 번 돌려보기. 3단계, 팀 고유의 스킬을 하나 작성해서 동료와 공유해보기.

주의할 점도 있어요. 스킬 문서가 영어 기반이라 한국어 커밋 컨벤션이나 국내 서비스 특유의 규칙은 직접 작성해야 하고요. 스킬이 로드되는 만큼 토큰 사용량이 늘어날 수 있다는 점, 그리고 70개 이상 에이전트를 지원한다지만 자동 활성화 같은 기능의 지원 수준은 에이전트마다 다를 수 있다는 점은 감안하셔야 해요.

마무리: 프롬프트 엔지니어링에서 프로세스 엔지니어링으로

이 프로젝트가 보여주는 방향은 분명해요. AI 활용의 무게중심이 '한 번의 좋은 프롬프트를 쓰는 기술'에서 '좋은 개발 프로세스를 문서로 설계하는 기술'로 옮겨가고 있다는 거예요. 그리고 그 프로세스 설계에 필요한 건 결국 시니어 엔지니어의 경험이거든요. AI 시대에 연차 많은 개발자의 가치가 줄어드는 게 아니라, 그 노하우를 명문화할 수 있는 사람의 가치가 오히려 커지는 셈이죠.

여러분 팀에는 문서화되지 않은 채 구전으로만 내려오는 '일하는 방식'이 있나요? 그중 하나를 스킬로 옮긴다면 뭐부터 시작하시겠어요? 댓글로 여러분의 생각을 들려주세요.