에이전트 스킬 (Agent Skills)

AI 코딩 에이전트의 기본 동작 방식은 "완료"에 이르는 가장 짧은 경로를 택하는 것이다. 기능을 요청하면 기능을 작성한다. 스펙이 있는지 묻지도 않고, 구현 전에 테스트를 먼저 작성하지도 않으며, 변경이 신뢰 경계를 넘는지 고려하지도 않고, PR이 리뷰어 눈에 어떻게 보일지 확인하지도 않는다. 그저 코드를 만들어내고, 완료를 선언한 뒤, 다음으로 넘어간다.

이것은 모든 시니어 엔지니어가 커리어 내내 피하도록 단련해온 실패 패턴과 똑같다. 어떤 태스크든 시니어 버전에는 diff에 나타나지 않는 작업들이 포함된다. 가정을 수면 위로 끌어올리는 것, 스펙 작성, 리뷰 가능한 단위로 쪼개는 것, 무난한 설계를 선택하는 것, 결과가 올바르다는 근거를 남기는 것, 사람이 실제로 검토할 수 있는 크기로 변경 범위를 조절하는 것. 이런 단계들이야말로 규모 있는 환경에서 안정적인 소프트웨어를 출시하는 엔지니어와 장애를 일으키는 코드를 푸시하는 사람을 가르는 핵심이다.

에이전트가 이런 단계들을 건너뛰는 이유는 주니어가 건너뛰는 이유와 같다. 눈에 보이지 않기 때문이다. 보상 신호는 "태스크 완료"를 가리킬 뿐, "태스크 완료 + 설계 문서 존재"를 가리키지 않는다. 그러니 시니어 엔지니어의 발판을 다시 갖다 붙여야 한다.

에이전트 스킬은 그 발판을 만들려는 시도다. 이미 26K 스타를 넘어섰으니, 이런 필요를 느끼는 사람이 나 혼자만은 아닌 것 같다. 이 글에서는 README가 충분히 다루지 못한 부분, 즉 각 설계 결정이 왜 그렇게 내려졌는지, 표준 SDLC 및 Google의 공개 엔지니어링 관행과 어떻게 연결되는지, 그리고 이 프로젝트를 설치하지 않더라도 참고할 만한 것들이 무엇인지 다룬다.

"스킬"이란 정확히 무엇인가

"스킬"이라는 단어는 Claude Code와 Anthropic의 어휘 체계에서 꽤 많은 것을 담고 있어 정확히 짚어볼 필요가 있다. 스킬이란 상황에 따라 에이전트의 컨텍스트에 주입되는 프론트매터가 달린 마크다운 파일이다. 시스템 프롬프트 조각과 런북(runbook)의 중간 어딘가에 해당한다.

스킬은 레퍼런스 문서가 아니다. "테스트에 관해 알아야 할 모든 것"을 담은 문서가 아니다. 스킬은 워크플로우다. 에이전트가 따라야 할 단계의 순서, 근거를 만들어내는 체크포인트, 그리고 명확히 정의된 완료 기준으로 이루어진다.

이 차이가 전부다. 테스트 모범 사례를 담은 2,000자짜리 에세이를 에이전트 컨텍스트에 넣으면, 에이전트는 그것을 읽고 그럴듯한 텍스트를 생성한 뒤 실제 테스트는 건너뛴다. 반면 워크플로우를 넣으면(실패하는 테스트를 먼저 작성하고, 실행하고, 실패를 확인하고, 통과에 필요한 최소한의 코드를 작성하고, 통과를 확인하고, 리팩터링) 에이전트는 실제로 할 일이 생기고, 당신은 검증할 것이 생긴다.

산문보다 프로세스. 레퍼런스보다 워크플로우. 완료 기준 없는 에세이보다 완료 기준 있는 단계들. 이 단 하나의 차이가 쓸모 있는 스킬과 예쁜 마크다운 파일을 가른다. 수많은 "AI 규칙" 저장소가 실제로는 아무 효과도 없는 이유도 여기 있다. 그 규칙들은 에세이니까.

스킬이 담아낸 SDLC

저장소의 스킬 20개는 6개의 라이프사이클 단계를 중심으로 구성되며, 7개의 슬래시 커맨드가 그 위에 놓인다. 정의(/spec)는 실제로 무엇을 만들지 결정하는 단계다. 계획(/plan)은 작업을 세분화한다. 구현(/build)은 수직 슬라이스 방식으로 실제 코딩을 진행한다. 검증(/test)은 제대로 동작함을 증명한다. 리뷰(/review)는 빠져나간 것들을 잡아낸다. 배포(/ship)는 안전하게 사용자에게 전달한다. /code-simplify은 이 전체 흐름의 하단을 가로질러 위치한다.

이것은 우연이 아니다. 제대로 돌아가는 모든 엔지니어링 조직이 각자의 용어로 실행하고 있는 동일한 SDLC다. Google은 이를 설계 문서 → 리뷰 → 구현 → 가독성 리뷰 → 런치 체크리스트라고 부른다. Amazon은 역방향 접근 메모(working-backwards memo)와 바 레이저(bar raiser)라고 부른다. 건강한 팀이라면 어디든 이 루프의 어떤 형태를 갖고 있다.

AI 코딩 에이전트에서 새로운 점은, 대부분의 에이전트가 이 단계들을 기본적으로 건너뛴다는 것이다. 기능을 요청하면 구현만 나올 뿐, 스펙, 계획, 테스트, 리뷰, 런치 체크리스트는 그냥 일어나지 않는다. 스킬은 에이전트가 시니어 엔지니어라면 스스로 거치게 되는 것과 동일한 단계들을 통과하도록 강제한다. 이 단계들 없이 코드를 배포하는 것이 곧 장애를 만드는 방식이기 때문이다.

복잡한 기능이라면 11개의 스킬이 순서대로 활성화될 수 있다. 작은 버그 수정은 세 개만 쓸 수도 있다. 라우터(using-agent-skills)가 어떤 스킬이 적용될지 결정한다. 핵심은 워크플로우가 가정된 범위가 아닌 실제 범위에 따라 확장된다는 점이다.

실질적인 역할을 하는 다섯 가지 원칙

이 프로젝트에서 핵심 하중을 지탱하는 설계 결정은 다섯 가지다. 나머지 시스템은 모두 이것들에서 파생된다.

1. 산문보다 프로세스

이미 다룬 내용이다. 워크플로우는 에이전트가 실행할 수 있지만, 에세이는 그렇지 않다. 사람으로 이루어진 팀에서도 마찬가지다. 팀 핸드북이 200페이지라면 시간 압박 상황에서 아무도 읽지 않는다. 체크포인트가 있는 소수의 워크플로우라면 사람들이 실제로 따른다.

2. 합리화 방지 표

이것이 이 프로젝트에서 가장 독특한 설계 결정이며, 다른 팀들이 가장 가져가길 바라는 부분이기도 하다.

각 스킬에는 에이전트(또는 지친 엔지니어)가 워크플로우를 건너뛰려 할 때 꺼낼 법한 흔한 핑계들과 그에 대한 반박을 짝지은 표가 들어 있다. 원문에 가까운 몇 가지 예시:

"이 태스크는 너무 단순해서 스펙이 필요 없어." → 인수 기준은 여전히 필요하다. 다섯 줄이면 충분하다. 하지만 아예 없으면 안 된다.
"테스트는 나중에 작성할게." → '나중에'가 문제의 핵심이다. 나중은 없다. 실패하는 테스트부터 먼저 작성하라.
"테스트 통과했으니 배포하자." → 테스트 통과는 증거일 뿐, 증명이 아니다. 런타임은 확인했나? 사용자가 보는 동작은 검증했나? 사람이 diff를 읽어봤나?

이게 효과가 있는 이유는 LLM이 합리화에 매우 뛰어나기 때문이다. 이 특정 태스크에는 스펙이 필요 없다거나, 이 특정 변경은 리뷰 없이 머지해도 된다는 그럴듯한 단락을 척척 만들어낸다. 합리화 방지 표는 에이전트가 아직 하지 않은 거짓말에 대한 미리 작성된 반박이다.

이 패턴은 사람으로 이루어진 팀에도 똑같이 유효하다. 대부분의 엔지니어링 퇴행은 누군가 나쁜 일을 의도적으로 선택해서 생기지 않는다. 하기 싫은 부분을 건너뛰는 그럴듯한 핑계를 사람들이 받아들이면서 생긴다. 자신들의 합리화를 기록해두는 팀은 그런 합리화가 줄어든다.

3. 검증은 타협 불가

모든 스킬은 구체적인 증거로 끝난다. 테스트가 통과한다. 빌드 출력이 깔끔하다. 런타임 트레이스가 예상된 동작을 보여준다. 리뷰어가 승인한다. "맞는 것 같은데"는 결코 충분하지 않다.

이것은 Anthropic의 하네스(harness)가 실패에서 복구하도록 만드는 원칙, Cursor의 플래너/작업자/판단자 분리가 실제로 버그를 잡아내도록 만드는 원칙, 장기 실행 에이전트를 복구 가능하게 만드는 원칙과 동일하다. 에이전트는 생성기다. 작업이 완료됐다는 별도의 신호가 필요하다. 스킬은 그 신호를 모든 워크플로우에 구워 넣는다.

4. 점진적 공개

세션 시작 시 스킬 20개를 모두 컨텍스트에 로드하지 말라. 단계에 따라 활성화하라. 소규모 메타 스킬(using-agent-skills)이 라우터 역할을 하며, 현재 태스크에 어떤 스킬이 적용될지 결정한다.

이것은 하네스 엔지니어링의 교훈을 스킬 단위로 적용한 것이다. 컨텍스트에 로드되는 토큰은 어딘가에서 반드시 성능을 갉아먹기 때문에, 관련 있는 것만 로드하고 나머지는 디스크에 남겨둔다. 점진적 공개는 스킬 20개짜리 라이브러리를 5K 토큰 슬롯 안에 독소 없이 집어넣는 방법이다.

5. 범위 관리

메타 스킬에는 가능하다면 모든 에이전트에 못 박아두고 싶은 타협 불가 원칙이 들어 있다. "요청받은 것만 건드려라." 인접한 시스템을 리팩터링하지 말라. 완전히 이해하지 못한 코드를 삭제하지 말라. TODO 하나를 발견하고 파일 전체를 재작성하겠다고 나서지 말라.

버그 하나를 고치려면 연관 없는 파일 세 개를 현대화해야 한다는 에이전트의 결론을 직접 보기 전까지는 당연한 말처럼 들린다. 범위 관리는 에이전트의 PR이 머지 가능한지, 아니면 되돌려야 하는지를 결정하는 가장 큰 단일 요인이다. PR이 한 가지 이상을 하면 블록하는 Google의 코드 리뷰 규범과도 가장 명확하게 맞닿아 있는 원칙이기도 하다.

Google의 DNA

이 스킬들은 Software Engineering at Google과 Google의 공개 엔지니어링 문화에서 비롯된 관행으로 가득 차 있다. 의도적인 결과다. Google 규모의 소프트웨어를 작동하게 만드는 것들의 대부분은 문서화되어 공개되어 있으며, 에이전트가 가장 잘 건너뛰는 바로 그 부분이기도 하다.

어떤 스킬이 어떤 관행을 담고 있는지 일부를 정리하면:

Hyrum's Law — api-and-interface-design. API의 모든 관찰 가능한 동작은 결국 누군가에게 의존될 것이므로, 그것을 염두에 두고 설계하라.
테스트 피라미드 (~80/15/5)와 비욘세 룰(Beyoncé Rule) — test-driven-development. "그게 맘에 들었다면, 테스트를 붙였어야지." 버그는 인프라 변경이 아니라 테스트가 잡는다.
테스트에서 DRY보다 DAMP. Google의 테스트 철학은 테스트 코드가 다소 중복되더라도 명세처럼 읽혀야 한다는 점을 명시한다. 지나치게 추상화된 테스트는 잘 알려진 안티패턴이다.
PR 크기 약 100줄, Critical / Nit / Optional / FYI 심각도 레이블 — code-review-and-quality. Google의 코드 리뷰 규범을 그대로 가져온 것이다. 큰 PR은 제대로 리뷰되지 않고 그냥 통과된다.
Chesterton's Fence — code-simplification. 무언가가 왜 거기 있는지 이해하기 전까지는 제거하지 말라.
트렁크 기반 개발과 원자적 커밋 — git-workflow-and-versioning.
Shift Left와 피처 플래그 — ci-cd-and-automation. 문제를 최대한 일찍 발견하고, 배포와 릴리스를 분리하라.
코드는 부채(Code-as-liability) — deprecation-and-migration. 남기는 코드 한 줄은 영원히 유지해야 할 코드이므로, 더 작은 표면을 선호하라.

이 중 새로운 아이디어는 하나도 없다. 핵심은 이것들이 에이전트에 기본으로 탑재되어 있지 않다는 것이다. 최신 프론티어 모델은 훈련 데이터에서 "Hyrum's Law"라는 표현을 접했겠지만, 새벽 3시에 당신의 API를 설계할 때 Hyrum's Law를 적용하지는 않는다. 스킬은 그것이 적용되도록 보장하는 방법이다.

실제 사용 방법

세 가지 방식이 있으며, 대략 도입 부담이 늘어나는 순서다.

방식 1: 마켓플레이스를 통한 설치. Claude Code를 사용 중이라면:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

슬래시 커맨드(/spec, /plan, /build, /test, /review, /ship, /code-simplify)를 바로 사용할 수 있으며, 에이전트가 컨텍스트에 따라 관련 스킬을 자동으로 활성화한다. 대부분의 사람에게 이 방식을 먼저 권한다.

방식 2: 사용 중인 도구에 마크다운 파일을 직접 넣기. 스킬은 프론트매터가 달린 순수한 마크다운 파일이다. Cursor 사용자는 .cursor/rules/에 넣으면 된다. Gemini CLI는 별도의 설치 경로가 있다. Codex, Aider, Windsurf, OpenCode, 시스템 프롬프트를 받을 수 있는 모든 도구에서 읽을 수 있다. 어떤 도구를 쓰느냐보다 그 아래 깔린 워크플로우가 더 중요하다.

방식 3: 명세로서 읽기. 아무것도 설치하지 않더라도, 스킬은 AI 에이전트와 함께하는 좋은 엔지니어링이 어떤 모습인지 기술한 문서다. code-review-and-quality.md을 읽고 팀의 리뷰 프로세스에 다섯 가지 축 프레임워크를 적용해보라. test-driven-development.md을 읽고 주니어와 "테스트를 먼저 작성해야 하나"를 두고 논쟁이 붙을 때 근거로 쓰라. 메타 스킬을 읽고 다섯 가지 타협 불가 원칙을 자신의 AGENTS.md에 가져가라.

사실 이 세 번째 방식부터 시작하길 권한다. 지금 가장 아픈 지점에 가장 가까운 스킬 네다섯 개를 고르라. 어떤 워크플로우를 강제할지 결정하라. 그런 다음 런타임을 설치하거나, 직접 구성해서 강제력을 부여하라.

설치하지 않아도 가져갈 수 있는 것들

AI 코딩 에이전트를 쓰든 안 쓰든, 이 프로젝트에서 가져갈 만한 패턴들이 있다.

팀 관행으로서의 합리화 방지. 팀이 스스로에게 하는 거짓말을 적어두라. "테스트는 출시 후에 고치자." "이 변경은 너무 작아서 설계 문서가 필요 없어." "괜찮아, 모니터링이 있잖아." 각각에 반박을 달아두라. AGENTS.md나 엔지니어링 위키에 올려두라. 불필요한 논쟁을 줄이고, 다음 번 지친 금요일 오후의 지름길을 잡아낼 것이다.

내부 문서에도 산문보다 프로세스를. "우리가 X를 어떻게 접근하는지"라는 제목의 2,000자짜리 문서를 쓰고 있다면, 레퍼런스 자료를 쓴 것이다. 체크포인트가 있는 워크플로우로 바꿔라. 문서는 400자로 줄어들고 사람들이 실제로 따르게 된다. 온보딩 가이드와 런북에도 에이전트 스킬만큼이나 해당하는 이야기다.

검증을 완료의 필수 기준으로. 모든 태스크의 마지막 단계를 "증거 만들기"로 삼아라. 에이전트에게도, 엔지니어에게도, 자신에게도. 증거란 작업 완료를 증명하는 것이면 무엇이든 된다. 테스트 통과 결과, 스크린샷, 로그, 리뷰 승인. 그것 없이는 태스크가 완료된 것이 아니다. "맞는 것 같은데"로는 루프가 닫히지 않는다.

어떤 규칙집에도 점진적 공개를. 50페이지짜리 핸드북을 쓰지 말라. 상황에 맞는 작은 챕터로 연결해주는 작은 라우터를 써라. AGENTS.md도, 런북도, 장애 대응 플레이북도, 시간 압박 상황에서 누군가 읽어야 하는 모든 것에 해당하는 이야기다.

메타 스킬에서 가져온, 지금 당장 어떤 AGENTS.md에도 넣을 만한 다섯 가지 타협 불가 원칙:

만들기 전에 가정을 수면 위로 꺼내라. 암묵적으로 유지되는 잘못된 가정이 가장 흔한 실패 원인이다.
요구사항이 충돌하면 멈추고 물어라. 추측하지 말라.
필요할 때는 반론을 제기하라. 에이전트도, 엔지니어도 예스머신이 아니다.
지루하고 명백한 해결책을 선호하라. 영리함은 비싸다.
요청받은 것만 건드려라.

다섯 줄로 담긴, 가져갈 만한 엔지니어링 문화다. 아무것도 설치하지 않아도 받아들일 수 있다.

하네스에서 이것이 차지하는 위치

더 넓은 그림에서 스킬은 에이전트 하네스 엔지니어링의 한 레이어다. 하네스란 모델과 그 주변에 구축하는 모든 것을 합친 것이고, 스킬은 시스템 프롬프트에 점진적으로 공개되는 재사용 가능한 워크플로우 단위다. AGENTS.md(롤링 규칙집), 훅(결정론적 강제 실행 레이어), 도구(에이전트가 취할 수 있는 액션), 세션 로그(지속적인 메모리)와 나란히 존재한다. 각 레이어는 고유한 역할이 있다. 스킬은 시니어 엔지니어 프로세스의 역할을 담당한다.

스킬은 챗 방식 에이전트보다 장기 실행 에이전트에서 더 중요하다. 긴 실행은 모든 지름길을 증폭시키기 때문이다. 10분짜리 세션에서 테스트를 건너뛴 에이전트는 버그 하나를 만든다. 30시간짜리 세션에서 테스트를 건너뛴 에이전트는 실행이 끝날 무렵 원래 의도가 무엇이었는지 아무도 기억 못 하는 디버깅 고고학 프로젝트를 남긴다. 실행이 길어질수록, 시니어 엔지니어의 발판은 제안이 아닌 강제가 되어야 한다.

스킬 포맷의 이식성도 중요하다. 동일한 SKILL.md 파일이 Claude Code, Cursor(rules 방식), Gemini CLI, Codex, 시스템 프롬프트 콘텐츠를 받을 수 있는 다른 모든 하네스에서 작동한다. 워크플로우를 한 번 작성하면, 런타임이 강제한다. 그것이 마크다운+프론트매터 포맷이 맞춤형 프롬프트 엔지니어링으로는 얻을 수 없는 것을 제공하는 이유다.

마치며

이 프로젝트에서 스킬 자체보다 더 많은 사람들이 가져갔으면 하는 것은 바로 이 프레임이다.

AI 코딩 에이전트는 극도로 유능한 주니어 엔지니어이되, diff에 드러나지 않는 부분에 대한 감각이 없다. 시니어 엔지니어링 작업, 즉 가정을 드러내고, 변경 크기를 조절하고, 스펙을 작성하고, 증거를 남기고, 리뷰할 수 없는 것은 머지를 거부하는 것, 이것이야말로 에이전트가 건너뛰지 못하도록 만들지 않으면 반드시 건너뛰는 부분들이다. 점점 더, 이 규율을 에이전트가 스스로 빠져나올 수 없는 무언가로 코드화하는 것이 우리의 일이 되고 있다.

스킬은 그 방법 중 하나의 형태다. 합리화 방지 표. 점진적 공개. 산문보다 프로세스. 핵심 완료 기준으로서의 검증. 이미 효과가 입증된 Google의 관행을 이식 가능하게 만든 것.

내 버전을 설치해도 되고, 직접 만들어도 된다. 어느 쪽이든 교훈은 같다. 엔지니어가 모델이라도, 시니어 엔지니어의 역할은 더 이상 선택 사항이 아니다.

저장소는 github.com/addyosmani/agent-skills (MIT 라이선스)에 있다. 더 넓은 발판 구조에 대해서는 Agent Harness Engineering과 Long-running Agents를 참고하라.