Agents · ARTICLE · 2026

Agent Skills

Addy Osmani · addyosmani.com ↗ · ↳ 20 links

요약

Addy Osmani가 2026년 5월 3일 개인 블로그에 올린 에세이다. AI 코딩 에이전트에게 senior 엔지니어의 작업 절차를 강제하는 장치로 Agent Skills라는 프레임을 제시한다.

출발점이 되는 진단은 에이전트의 기본 동작이다. 명시적으로 제약하지 않으면 에이전트는 최소한의 절차만 밟고 작업을 끝내려는 쪽으로 기운다. spec을 쓰지 않고, test를 만들지 않고, 리뷰를 거치지 않고, verification 없이 코드를 내놓는다. 저자는 이것이 junior 엔지니어의 실패 모드를 그대로 재현하는 상태라고 본다.

해법의 형태는 더 나은 프롬프트가 아니라 강제된 절차다. 스킬은 특정 작업 절차를 담아 에이전트에 적용하는 지침 패키지인데, 저자가 요구하는 스킬은 읽히기 위한 참고 문서가 아니라 실행되기 위한 워크플로다. 본문은 이 워크플로를 떠받치는 다섯 가지 설계 원칙, 스킬을 조직하는 6단계 SDLC, 스킬 안에 담기는 Google 엔지니어링 관행, 그리고 에이전트 도구를 쓰지 않는 조직으로의 이식 경로를 차례로 다룬다.

이 글은 정량 데이터가 없는 처방형 의견 에세이다. 도입 전후 비교나 결함률 변화 같은 측정치가 하나도 제시되지 않으므로, 스킬의 효과를 재는 근거가 아니라 절차를 설계할 때 참고할 원칙 카탈로그로 읽는 것이 적절하다. raw/에 남은 자료가 원문 전문이 아니라 3인칭으로 압축된 약 3,100자 추출본이라는 점도 함께 고려해야 한다. 저자의 논증 전개와 예시가 그대로 보존되어 있지 않다.

배경

문제의 출발점은 senior 엔지니어의 일이 어디에 있는지에 대한 저자의 관찰이다. 본문의 핵심 명제는 다음 한 문장이다.

a senior engineer's job is mostly the parts that don't show up in the diff.

시니어 엔지니어의 일은 대부분 diff에 드러나지 않는 부분이라는 뜻이다. 코드 변경분만 놓고 보면 시니어와 주니어의 산출물은 비슷해 보일 수 있지만, 그 산출물에 도달하기까지 시니어가 밟은 절차는 diff 바깥에 있다.

저자가 그 절차로 지목하는 항목은 다섯 가지다.

활동	하는 일	생략됐을 때
Spec	무엇을 만들지와 완료 조건을 먼저 적는다	무엇을 만들었는지 판정할 기준이 없다
Test	동작을 검사하는 코드를 함께 만든다	변경이 기존 동작을 깨뜨렸는지 알 수 없다
Review	다른 사람의 검토를 거친다	작성자 한 명의 판단만 남는다
Scope discipline	요청받은 범위 안에서만 수정한다	요청하지 않은 변경이 함께 들어온다
Verification	완료를 증거로 확인한다	완료 선언이 주장에 그친다

다섯 항목의 공통점은 결과물이 아니라 절차라는 것이다. 그리고 절차이기 때문에 생략해도 당장은 아무 일이 일어나지 않는다. 생략의 대가는 나중에 치러진다.

AI 코딩 에이전트는 이 절차를 기본값으로 생략한다는 것이 본문의 진단이다. 저자의 표현으로 에이전트는 최소한의 절차로 작업을 완료하는 쪽으로 자연스럽게 기울며, 이 경향은 명시적 제약이 없는 한 유지된다. 결과적으로 에이전트는 junior 엔지니어의 실패 모드를 되풀이한다.

이 진단이 해법의 형태를 결정한다. 문제가 능력 부족이 아니라 기본 동작이라면, 필요한 것은 더 똑똑한 모델이 아니라 그 기본 동작을 막는 제약이다. 스킬은 그 제약을 담는 그릇으로 제안된다.

핵심 개념

Agent Skill은 senior 엔지니어의 절차를 실행 가능한 워크플로로 적어 둔 markdown 단위다. 본문에서 스킬은 조언 모음이 아니라 순서와 종료 조건이 정해진 절차이며, 에이전트가 읽고 참고하는 대상이 아니라 따라 실행하는 대상이다.

checkpoint는 워크플로 중간에 놓여 다음 step으로 넘어가기 전에 확인을 요구하는 지점을 가리킨다. 본문은 이 용어를 정의 없이 쓰지만, 워크플로가 참고 에세이보다 나은 이유로 checkpoint의 존재를 든다는 점에서 이 읽기가 문맥에 맞는다.

exit criteria는 워크플로가 끝났다고 선언하기 위해 반드시 충족해야 하는 조건이다. 저자는 verification을 선택 사항이 아니라 필수 exit criteria로 두라고 요구하는데, 이는 verification을 워크플로 중간의 한 step이 아니라 종료 자격 요건으로 취급한다는 뜻이다.

load-bearing은 저자가 다섯 설계 원칙에 붙인 수식어다. 건축에서 하중을 받는 부재를 가리키는 말을 빌려, 빼면 구조가 성립하지 않는 필수 요소라는 의미로 쓴다.

harness는 모델을 감싸 도구와 검증과 상태를 제공하는 실행 환경을 뜻한다. 본문은 스킬을 harness의 전부가 아니라 그 안의 한 layer로 규정하며, 이 위치 규정이 마지막 절의 주제가 된다.

방법

절차 우선

첫 번째 원칙은 process over prose다. checkpoint가 있는 워크플로가 참고용 에세이보다 성과가 낫다는 것이 주장의 내용이고, 근거는 에이전트가 에세이가 아니라 step에 따라 행동한다는 관찰이다.

이 원칙이 가르는 것은 문서의 품질이 아니라 문서의 종류다. 참고 에세이는 원칙과 이유를 설명하고 판단은 읽는 쪽에 맡긴다. 워크플로는 순서를 지정하고 각 지점에서 무엇을 해야 하는지 지시한다. 앞의 문서는 잘 쓰였는지로 평가되고, 뒤의 문서는 실행 가능한지로 평가된다.

에이전트를 대상으로 삼는 순간 이 차이가 결과를 가른다. 잘 논증된 원칙 문서는 읽히고 나서 아무 동작으로도 이어지지 않을 수 있지만, 순서가 명시된 워크플로는 각 step이 곧 동작이다. 따라서 스킬을 쓸 때 저자가 요구하는 것은 좋은 글이 아니라 좋은 절차다.

변명 차단 표

두 번째 원칙은 anti-rationalization table이다. 스킬마다 흔한 변명과 그에 대한 반박을 짝지어 표로 넣어 둔다. 본문이 드는 예는 다음 한 쌍이다.

변명	미리 준비한 반박
"이건 spec을 쓰기엔 너무 단순하다"	"그래도 acceptance criteria는 적용된다"

이 장치의 전제는 절차 생략이 그냥 일어나지 않는다는 것이다. 생략에는 대개 그것을 정당화하는 문장이 앞선다. 작업이 사소하다거나, 이번만 예외라거나, 나중에 보완하겠다는 식이다.

표는 그 정당화가 나오는 자리에서 반박을 마주치게 한다. 규칙으로 shortcut을 금지하는 대신, shortcut을 부르는 논리 자체를 미리 반박해 두는 방식이다.

예시의 구조도 눈여겨볼 만하다. 반박은 작업이 단순하다는 판단을 부정하지 않는다. 단순한지 여부와 무관하게 acceptance criteria는 적용된다고 말하며 논점을 옮긴다. 판단의 문제를 규칙 적용의 문제로 바꾸는 것이 이 반박의 형태다.

증거 기반 종료

세 번째 원칙은 verification is non-negotiable이다. 모든 워크플로는 구체적 증거로 끝나야 하며, 본문이 인정하는 증거는 세 가지다.

증거	형태
Passing test	통과한 test
Clean build	오류 없이 완료된 build
Reviewer approval	reviewer의 승인

세 가지의 공통점은 에이전트 바깥에서 만들어진다는 것이다. test는 실행 결과가 판정하고, build는 빌드 시스템이 판정하며, 승인은 사람이 판정한다. 어느 것도 에이전트의 자기 평가에 의존하지 않는다.

이 원칙이 겨냥하는 실패는 증거 없는 완료 선언이다. 에이전트가 작업을 끝냈다고 말하는 것과 작업이 실제로 끝난 것은 다른 사건인데, 종료 조건을 증거로 못 박으면 둘 사이의 간극이 닫힌다.

verification을 exit criteria로 두는 것이 이 원칙의 실질이다. 워크플로 중간의 한 step으로 두면 건너뛸 수 있지만, 종료 자격 요건으로 두면 건너뛸 경우 워크플로가 끝나지 않는다.

맥락 기반 활성화

네 번째 원칙은 progressive disclosure다. 필요한 시점에만 정보를 단계적으로 노출하는 설계를 가리키며, 스킬에 적용하면 스킬 20개를 동시에 로드하지 않고 맥락에 따라 활성화하는 방식이 된다. 저자가 드는 이유는 토큰 효율이다.

이 원칙이 필요한 이유는 스킬의 이점과 비용이 같은 방향으로 늘어나기 때문이다. 스킬을 많이 갖출수록 강제되는 절차가 촘촘해지지만, 그 스킬이 모두 컨텍스트에 올라가면 정작 작업에 쓸 컨텍스트가 줄어든다.

맥락 기반 활성화는 이 상충을 로딩 시점을 옮겨 해결한다. 스킬 20개를 보유하는 것과 스킬 20개를 로드하는 것을 분리하면, 보유량은 늘리면서 로드량은 현재 작업에 필요한 만큼으로 유지할 수 있다.

다만 본문은 원칙만 제시하고 실제 로딩 비용을 수치로 밝히지 않는다. 짝 자료인 GeekNews 토론(Agent Skills (GeekNews))은 스킬 하나가 800줄을 넘기는 경우를 보고하면서, 필요 없는 스킬을 잔뜩 설치하면 토큰만 낭비된다는 실무 관찰을 덧붙인다. 원칙과 실측이 만나는 지점이라 두 자료를 함께 읽을 만하다.

범위 규율

다섯 번째 원칙은 scope discipline이다. 본문의 표현은 "touch only what you're asked to touch", 곧 요청받은 곳만 수정하라는 것이다.

저자가 금지 대상으로 지목하는 두 가지 행동이 있다. 인접 영역의 refactoring과 파일 통째 재작성이다. 둘 다 코드를 나쁘게 만들려는 행동이 아니라 개선으로 보이는 행동이라는 점이 공통점이다.

명시적 규칙이 필요한 이유도 여기에 있다. 개선으로 보이는 변경은 스스로를 정당화하기 쉽고, 그래서 요청 범위를 벗어났다는 사실이 문제로 인식되지 않는다. 규칙이 없으면 판단은 매번 에이전트에게 맡겨지고, 판단은 매번 확장 쪽으로 기운다.

이 원칙은 뒤에 나오는 Chesterton's Fence와 방향이 같다. 한쪽은 요청받지 않은 수정을 막고 다른 한쪽은 이유를 모르는 제거를 막는데, 둘 다 근거 없는 변경을 억제한다는 점에서 겹친다. 본문이 두 항목을 명시적으로 연결하지는 않지만, 같은 스킬 안에 함께 담긴다는 사실은 이 방향성을 보여 준다.

다섯 원칙의 역할 분담

다섯 원칙은 서로 다른 실패를 하나씩 맡는다.

원칙	막으려는 실패	강제 수단
Process over prose	지시가 읽히기만 하고 실행되지 않는다	checkpoint가 박힌 순서 있는 step
Anti-rationalization table	에이전트가 절차 생략을 스스로 정당화한다	변명과 반박을 짝지은 표
Verification is non-negotiable	증거 없이 완료를 선언한다	test, build, 승인 중 하나를 exit criteria로 지정
Progressive disclosure	스킬 전량 로드가 컨텍스트를 잠식한다	맥락에 따른 선택적 활성화
Scope discipline	요청 범위를 넘어선 변경이 섞여 들어온다	수정 대상을 요청 범위로 한정

저자가 이 다섯을 load-bearing이라고 부른 이유가 이 배치에서 드러난다. 각 원칙이 다른 원칙으로 대체되지 않는 고유한 실패를 담당하므로, 하나를 빼면 그 실패가 그대로 통과한다.

6단계 SDLC와 슬래시 커맨드

스킬은 개별적으로 흩어져 있지 않고 6단계 SDLC로 조직된다. 각 단계에는 슬래시 커맨드가 하나씩 대응한다.

단계	커맨드	역할
Define	`/spec`	요구사항과 acceptance criteria를 정의한다
Plan	`/plan`	작업을 분해하고 계획을 세운다
Build	`/build`	구현한다
Verify	`/test`	test와 build로 증거를 확보한다
Review	`/review`	코드를 리뷰한다
Ship	`/ship`	배포한다

저자는 이 구성이 표준 엔지니어링 조직의 워크플로를 그대로 반영한 것이라고 밝힌다. 스킬 체계를 새로 발명하지 않고 이미 조직에서 쓰이는 절차에 맞춘 것이 설계 의도다.

이 선택에는 두 가지 이점이 따른다. 사람이 이미 아는 단계 이름을 쓰므로 팀에 설명할 비용이 낮고, 각 단계의 산출물이 무엇인지도 조직 관행에서 그대로 가져올 수 있다.

앞의 다섯 원칙이 이 6단계에 결합되는 방식도 확인할 수 있다. Define이 spec 생략을 막고, Verify가 증거 기반 종료를 담당하며, Review가 작성자 한 명의 판단만 남는 상태를 막는다. 배경 절에서 열거한 diff 바깥의 활동이 단계로 배치된 셈이다.

수량 정보는 짝 자료가 보완한다. GeekNews 요약(Agent Skills (GeekNews))에 따르면 저장소는 스킬 20개를 6단계로 묶고 슬래시 커맨드 7개를 제공하며 MIT 라이선스로 공개돼 있다. 본문이 단계별로 이름을 붙인 커맨드는 6개이므로 저장소가 제공하는 커맨드 수와 한 개 차이가 난다.

Google 엔지니어링 관행의 인코딩

스킬은 새 규범을 만드는 대신 Software Engineering at Google의 기존 관행을 담아 고정한다. 본문이 지목한 관행은 다섯 가지다.

관행	본문이 지정한 적용 지점	관행의 내용
Hyrum's Law	API 설계	관찰 가능한 API 동작은 누군가 반드시 의존하게 된다는 경험칙
Test pyramid	약 80/15/5 비율	계층별 test 수량의 비율 배분
PR 크기 상한	약 100줄	리뷰 가능한 변경 크기의 한도
Chesterton's Fence	제거 판단	존재 이유를 모르는 것을 함부로 제거하지 말라는 원칙
Trunk-based development	브랜치 전략	장기 브랜치를 두지 않고 주 브랜치에 자주 통합하는 방식

표의 마지막 열은 본문이 아니라 이 wiki의 용어 정리에서 가져온 것이다. 본문은 다섯 관행의 이름과 적용 지점만 나열하고 각각이 무엇인지는 설명하지 않기 때문이다. test pyramid의 80/15/5도 비율만 제시하고 어느 계층이 어느 몫에 해당하는지 밝히지 않는다.

관행을 스킬에 인코딩한다는 발상 자체는 앞의 다섯 원칙과 같은 논리 위에 있다. 조직의 관행이 문서로만 존재하면 지켜질지 여부가 매번 판단에 달리지만, 워크플로의 step으로 들어가면 실행 대상이 된다. 100줄 PR 상한이 좋은 예다. 권고 사항으로 두면 상황마다 예외가 생기고, 워크플로의 step으로 두면 상한을 넘겼는지가 확인 지점이 된다.

활용

세 가지 활용 경로

저자는 스킬을 쓰는 방식을 세 가지로 든다.

경로	방식	실행 주체
marketplace 설치	Claude Code의 marketplace에서 설치한다	에이전트
markdown 투입	Cursor 같은 도구에 markdown 파일을 직접 넣는다	에이전트
명세 문서로 읽기	팀 관행을 정의하는 specification 문서로 읽는다	사람

앞의 두 경로는 실행 환경만 다를 뿐 에이전트가 스킬을 실행한다는 점에서 같다. 세 번째 경로는 성격이 다르다. 에이전트가 스킬을 실행하지 않아도 스킬이 값을 낸다는 뜻이며, 다음 항목의 이식 논의로 이어진다.

에이전트 도구가 없는 조직으로의 이식

저자는 에이전트 도구를 쓰지 않는 조직도 네 가지를 채택해야 한다고 본다.

항목	사람 조직에서의 형태
Anti-rationalization table	팀이 실제로 밟는 shortcut을 문서로 기록한다
절차 중심 워크플로	긴 참고 문서 대신 절차를 둔다
Verification	선택 사항이 아니라 필수 exit criteria로 둔다
Progressive disclosure	handbook과 runbook에 적용한다

이 목록은 앞의 다섯 원칙에서 scope discipline 하나만 빠진 형태다. 나머지 네 항목은 에이전트를 대상으로 하든 사람을 대상으로 하든 같은 형태로 적용된다.

여기서 저자의 관점이 드러난다. 스킬 설계 원칙의 대부분은 에이전트 고유의 것이 아니라 조직 운영 원칙이며, 에이전트가 등장하면서 새로 만들어진 것이 아니라 이미 있던 원칙이 새 대상에 적용된 것이다. 배경 절에서 문제를 junior 실패 모드로 규정한 진단과 결이 맞는 결론이다.

harness 안에서 스킬의 위치

마지막으로 저자는 스킬의 위치를 한정한다. 스킬은 agent harness engineering을 이루는 한 layer일 뿐이며, 나란히 놓이는 층위가 넷 더 있다.

층위	역할
Skills	절차
AGENTS.md	rulebook
Hooks	enforcement
Tools	action
Session log	메모리

다섯 층위는 서로 다른 기능을 맡는다. 스킬이 무엇을 어떤 순서로 할지 정한다면, rulebook은 항상 적용되는 규칙을 두고, 훅은 특정 시점에 개입해 규칙을 실제로 집행하며, tool은 에이전트가 실행할 수 있는 동작을 제공하고, session log는 실행 사이의 기록을 남긴다.

이 배치는 스킬만으로 문제가 해결되지 않는다는 뜻을 담는다. 스킬은 절차를 정의할 뿐 그 절차가 지켜지는지를 강제하지 않으므로, 강제는 훅 층위의 일이 된다. 본문이 스킬을 harness의 전부가 아니라 한 layer로 규정한 이유가 여기에 있다.

본문은 오래 실행되는 에이전트일수록 강제된 워크플로에서 얻는 이득이 크다는 관찰로 이 논의를 맺는다. 실행이 길어질수록 절차 생략이 누적될 기회도 늘어나기 때문이다.

결과

이 글에는 정량 결과가 없다. 스킬 도입 전후의 결함률, 처리량, 리뷰 소요 시간 같은 측정치가 전혀 제시되지 않으며 비교군이나 실험 설계도 없다.

검증 가능한 사실 진술로 분류할 수 있는 것은 두 가지다.

스킬을 쓰는 세 가지 경로가 존재한다는 도구 사실. Claude Code marketplace 설치, Cursor 등에 markdown 투입, 명세 문서로 읽기다.
스킬이 harness의 한 layer라는 위치 규정. AGENTS.md, 훅, tool, session log와 나란히 놓인다.

나머지는 모두 저자의 관찰을 압축한 단언이다. 다섯 원칙 목록, 6단계 매핑, 사람 조직 이식 권고에는 별도 출처가 붙어 있지 않다. 외부 문헌을 지목하는 유일한 대목인 Software Engineering at Google 인용에서도 관행 이름만 열거하고 쪽수나 장 번호를 밝히지 않는다.

이 자료의 값은 측정된 효과가 아니라 분류와 명명에 있다. 흩어져 있던 절차 강제 방법을 다섯 원칙으로 정리하고 6단계 SDLC에 배치한 것이 기여다.

한계

본문이 스스로 짚는 한계는 뚜렷하지 않고 무게 중심이 처방 쪽에 쏠려 있다. 자료 관점에서 남는 약점은 다음과 같다.

정량 데이터가 없어 스킬 도입 효과를 측정 지표로 환산하지 못한다. 어떤 조건에서 얼마나 개선되는지, 절차 강제의 비용이 얼마인지 알 수 없다.
원칙 카탈로그 수준에 머물러 경계 정의가 느슨하다. 스킬과 일반 프롬프트 템플릿이 어떻게 다른지, connector와 스킬을 무엇으로 가르는지가 다뤄지지 않는다.
verification을 강제한다고 하면서 그 verification 자체의 신뢰성은 다루지 않는다. 검증을 누가 검증하는지가 비어 있다.
Google 관행을 인용하면서 각 관행의 내용을 설명하지 않아 독자가 Software Engineering at Google을 이미 안다고 전제한다. test pyramid의 80/15/5는 비율만 남고 계층 구분이 빠져 있다.
progressive disclosure를 원칙으로 내세우지만 실제 로딩 비용을 제시하지 않는다.
수집된 raw가 3인칭으로 압축된 추출본이라 저자의 원 논증 전개와 예시가 그대로 남아 있지 않다. 인용문의 정확한 문맥은 원문 URL을 확인해야 한다.

가장 큰 빈틈인 강제의 실효성은 짝 자료가 채운다. GeekNews 토론(Agent Skills (GeekNews))은 규칙을 지킬지 말지 결정하는 주체가 LLM 자신이므로 문서로 강제하는 것이 실제로 작동하는지 의문이라는 반론을 정리한다. 문서가 복잡해질수록 우회할 여지도 함께 늘어난다는 지적도 같은 맥락이다. 본 자료가 처방이라면 짝 자료는 그 처방에 대한 실무 반응이므로 두 페이지를 함께 읽는 것이 좋다.

핵심 용어

용어	뜻
Agent Skill	senior 엔지니어의 절차를 checkpoint와 exit criteria가 있는 워크플로로 강제하는 markdown 단위
Anti-rationalization table	흔한 변명과 미리 써 둔 반박을 짝지어 놓은 표. 에이전트가 절차 생략을 스스로 정당화하는 것을 차단한다
Exit criteria	워크플로가 끝났다고 선언하기 위해 반드시 충족해야 하는 조건. 통과한 test, 오류 없는 build, reviewer 승인이 해당한다
Progressive disclosure	필요한 시점에만 정보를 단계적으로 노출하는 설계. 스킬을 전량 로드하지 않고 맥락에 따라 활성화한다
Scope discipline	요청받은 범위만 수정하고 인접 영역 refactoring이나 파일 재작성으로 번지지 않게 하는 규율
Agent harness engineering	스킬, rulebook, 훅, tool, 메모리를 조합해 에이전트 실행 환경을 구성하는 상위 작업

요약

배경