Agent Skills

• Agent Skills는 AI 코딩 에이전트가 명세, 테스트, 리뷰 가능한 PR, 신뢰 경계 검토 같은 시니어 엔지니어링 절차를 건너뛰지 못하도록 워크플로로 강제하는 스캐폴딩임
• 스킬(skill) 은 frontmatter가 있는 Markdown 파일로, 참조 문서라기보다 단계 순서, 체크포인트 증거, 종료 기준을 가진 워크플로에 가까움
• 저장소의 20개 스킬은 Define, Plan, Build, Verify, Review, Ship의 6개 생명주기 단계와 /spec, /plan, /build, /test, /review, /ship, /code-simplify 7개 slash command로 구성됨
• 핵심 원칙은 산문보다 프로세스, 반합리화 표, 검증을 종료 기준으로 삼기, 점진적 공개, 범위 규율이며, using-agent-skills가 작업에 맞는 스킬만 활성화함
• Claude Code marketplace 설치, Cursor .cursor/rules/, Gemini CLI, Codex, Aider, Windsurf, OpenCode 같은 도구에 Markdown을 넣는 방식으로 사용할 수 있으며, MIT 라이선스로 공개됨

목적과 문제의식

• Agent Skills는 AI 코딩 에이전트가 기본적으로 건너뛰는 시니어 엔지니어링 절차를 워크플로로 강제하기 위한 스캐폴딩임
• AI 코딩 에이전트는 기능을 요청받으면 보통 가장 짧은 경로로 구현을 끝내며, 명세 작성, 테스트 선행, 신뢰 경계 검토, 리뷰 가능한 PR 구성 같은 절차를 기본적으로 수행하지 않음
• 시니어 엔지니어의 작업에는 diff에 드러나지 않는 부분이 많음
  • 가정 드러내기
  • 명세 작성
  • 리뷰 가능한 단위로 작업 나누기
  • 지루하지만 안전한 설계 선택하기
  • 결과가 맞다는 증거 남기기
  • 사람이 실제로 리뷰할 수 있는 크기로 변경 제한하기
• 에이전트가 이런 단계를 건너뛰는 이유는 주니어 엔지니어와 비슷하게, 보상 신호가 “작업 완료”에 맞춰져 있고 “명세 문서까지 존재하는 작업 완료”에는 맞춰져 있지 않기 때문임
• Agent Skills 저장소는 26K stars를 넘었으며, README를 넘어 설계 선택의 이유, 표준 SDLC와 Google의 공개 엔지니어링 관행과의 대응, 설치하지 않아도 가져갈 수 있는 패턴까지 다룸

스킬의 실제 의미

• 스킬(skill) 은 상황에 따라 에이전트 컨텍스트에 주입되는 frontmatter 포함 Markdown 파일이며, 시스템 프롬프트 조각과 런북 사이에 가까운 형태임
• 스킬은 참조 문서가 아니며, “테스트에 대해 알아야 할 모든 것” 같은 지식 모음도 아님
• 유용한 스킬은 에이전트가 따르는 워크플로임
  • 단계의 순서가 있음
  • 체크포인트에서 증거를 생성함
  • 명확한 종료 기준으로 끝남
• 테스트 모범 사례에 대한 2,000단어 에세이를 컨텍스트에 넣으면 에이전트는 그럴듯한 문장을 생성하고 실제 테스트를 건너뛸 수 있음
• 반대로 실패하는 테스트를 먼저 작성하고, 실행해서 실패를 확인하고, 통과에 필요한 최소 구현을 작성하고, 통과를 확인하고, 리팩터링하는 워크플로를 넣으면 에이전트가 수행할 일이 생기고 사람이 검증할 수 있음
• 핵심 구분은 산문보다 프로세스, 참조보다 워크플로, 종료 기준 없는 에세이보다 종료 기준 있는 단계임
• 많은 “AI rules” 저장소가 실제로 효과를 내지 못하는 이유는 규칙이 워크플로가 아니라 에세이에 머물기 때문임

SDLC와 slash command 구조

• 저장소의 20개 스킬은 6개 생명주기 단계로 구성되고, 그 위에 7개 slash command가 놓임

• 단계와 명령

  • /spec: 무엇을 만들지 결정하는 Define 단계임
  • /plan: 작업을 분해하는 Plan 단계임
  • /build: 수직 슬라이스로 구현하는 Build 단계임
  • /test: 동작을 증명하는 Verify 단계임
  • /review: 빠져나간 문제를 잡는 Review 단계임
  • /ship: 사용자에게 안전하게 전달하는 Ship 단계임
  • /code-simplify: 전체 흐름 아래에 걸쳐 적용되는 단순화 명령임
  • 이 구조는 정상적으로 작동하는 엔지니어링 조직의 SDLC와 같은 흐름이며, 조직마다 어휘만 다름
  • Google에서는 design doc → review → implementation → readability review → launch checklist 흐름으로, Amazon에서는 working-backwards memo와 bar raiser 같은 방식으로 나타남
  • AI 코딩 에이전트의 새로운 문제는 대부분의 에이전트가 이런 단계 대부분을 기본적으로 건너뛴다는 데 있음
  • 기능을 요청하면 구현만 나오고, 명세, 계획, 테스트, 리뷰, 출시 체크리스트는 수행되지 않음
  • 스킬은 시니어 엔지니어가 스스로 강제하는 단계를 에이전트에도 통과시키며, 그런 절차 없이 코드를 배포하면 장애로 이어짐
  • 복잡한 기능은 11개 스킬이 순차적으로 활성화될 수 있고, 작은 버그 수정은 3개만 사용할 수 있음
  • using-agent-skills 라우터가 현재 작업에 어떤 스킬이 적용되는지 결정하며, 워크플로는 가정된 범위가 아니라 실제 범위에 맞춰 확장됨

작동을 지탱하는 원칙

• 1. 산문보다 프로세스

  • 워크플로는 에이전트가 행동으로 옮길 수 있지만, 에세이는 그렇지 않음
  • 사람 팀에도 같은 원리가 적용됨
  • 팀 핸드북이 200페이지라면 압박 상황에서 읽히지 않지만, 체크포인트가 있는 작은 워크플로라면 실제로 실행될 가능성이 커짐

• 2. 반합리화 표

  • Agent Skills에서 가장 독특하고 다른 팀이 가져가야 할 설계 선택은 반합리화 표(anti-rationalization tables) 임
  • 각 스킬에는 에이전트나 지친 엔지니어가 워크플로를 건너뛰기 위해 사용할 법한 흔한 변명과, 그에 대한 미리 작성된 반박이 함께 들어감
  • 예시는 다음과 같음
    • “이 작업은 너무 단순해서 명세가 필요 없다” → 수용 기준은 여전히 적용됨. 5줄은 괜찮지만 0줄은 안 됨
    • “테스트는 나중에 작성하겠다” → “나중”이 핵심 문제임. 나중은 없음. 실패하는 테스트를 먼저 작성해야 함
    • “테스트가 통과했으니 배포하자” → 통과한 테스트는 증거이지 증명이 아님. 런타임을 확인했는지, 사용자에게 보이는 동작을 검증했는지, 사람이 diff를 읽었는지 확인해야 함
  • LLM은 합리화에 능하며, 특정 작업은 명세가 필요 없다거나 특정 변경은 리뷰 없이 병합해도 된다는 그럴듯한 문단을 만들 수 있음
  • 반합리화 표는 에이전트가 아직 말하지 않은 거짓말에 대한 미리 작성된 반박임
  • 이 패턴은 사람 팀에도 유효함
  • 엔지니어링 품질 저하는 대개 누군가가 나쁜 일을 하기로 결정해서가 아니라, 하기 싫은 절차를 건너뛰는 그럴듯한 정당화를 받아들이면서 생김

• 3. 검증은 협상 불가

  • 모든 스킬은 구체적인 증거로 끝남
  • 테스트 통과, 깨끗한 빌드 출력, 기대한 동작을 보여주는 런타임 trace, 리뷰어 승인 같은 것이 종료 기준이 됨
  • “그럴듯해 보임”은 충분하지 않음
  • 이는 Anthropic의 하네스(harness)가 실패에서 회복하고, Cursor의 planner/worker/judge 분리가 실제로 버그를 잡고, long-running agent가 회복 가능해지는 원리와 같음
  • 에이전트는 생성기이므로, 작업 완료를 판단할 별도 신호가 필요하고 스킬은 그 신호를 각 워크플로에 내장함

• 4. 점진적 공개

  • 세션 시작 시 20개 스킬을 모두 컨텍스트에 넣지 않음
  • 현재 단계에 따라 필요한 스킬만 활성화함
  • 작은 메타 스킬인 using-agent-skills가 현재 작업에 맞는 스킬을 결정하는 라우터 역할을 함
  • 이는 harness engineering의 교훈을 스킬 단위에 적용한 것임
  • 컨텍스트에 로드되는 모든 토큰은 어딘가에서 성능을 떨어뜨리므로, 관련된 것만 로드하고 나머지는 디스크에 남겨야 함
  • 점진적 공개는 20개 스킬 라이브러리를 5K-token 슬롯에 넣으면서 전체 컨텍스트를 오염시키지 않는 방식임

• 5. 범위 규율

  • 메타 스킬은 “요청받은 것만 건드려라”라는 협상 불가능한 원칙을 인코딩함
  • 인접 시스템을 리팩터링하지 말고, 완전히 이해하지 못한 코드를 제거하지 말고, TODO를 보고 파일 전체를 다시 쓰기로 결정하지 않아야 함
  • 에이전트는 버그 하나를 고치려다가 관련 없는 파일 3개를 현대화하려 할 수 있음
  • 범위 규율은 에이전트의 PR이 병합 가능한지, 아니면 되돌려야 하는지를 가르는 가장 큰 결정 요인임
  • 이는 한 PR이 하나 이상의 일을 하면 리뷰어가 막을 수 있는 Google 코드 리뷰 규범과도 잘 맞음

Google 엔지니어링 관행과의 연결

• Agent Skills에는 _Software Engineering at Google_과 Google의 공개 엔지니어링 문화에서 나온 관행이 많이 반영되어 있음
• Google 규모의 소프트웨어가 작동하게 만드는 많은 요소는 공개적으로 문서화되어 있으며, 바로 그 부분을 에이전트가 가장 자주 건너뜀

• 스킬과 관행의 대응

  • api-and-interface-design: Hyrum’s Law를 반영함. API의 관찰 가능한 모든 동작은 결국 누군가가 의존하게 되므로 이를 고려해 설계해야 함
  • test-driven-development: 테스트 피라미드 ~80/15/5와 Beyoncé Rule을 반영함. “좋아했다면 테스트를 붙였어야 한다”는 원칙이며, 인프라 변경이 아니라 테스트가 버그를 잡음
  • 테스트의 DAMP over DRY: Google의 테스트 철학은 테스트 코드가 중복을 조금 감수하더라도 명세처럼 읽혀야 한다고 봄. 과도하게 추상화된 테스트는 알려진 안티패턴임
  • code-review-and-quality: ~100-line PR 크기와 Critical / Nit / Optional / FYI 심각도 레이블을 반영함. 큰 PR은 실제로 리뷰되지 않고 고무도장처럼 승인되기 쉬움
  • code-simplification: Chesterton’s Fence를 반영함. 어떤 것이 왜 놓였는지 이해하기 전에는 제거하지 않아야 함
  • git-workflow-and-versioning: trunk-based development와 atomic commits를 반영함
  • ci-cd-and-automation: Shift Left와 feature flags를 반영함. 문제를 가능한 한 빨리 잡고, 배포와 릴리스를 분리해야 함
  • deprecation-and-migration: code-as-liability를 반영함. 유지하는 모든 줄은 영원히 관리해야 하므로 더 작은 표면을 선호해야 함
  • 이런 개념들은 새로운 것이 아니지만, 에이전트에 기본 탑재되어 있지 않음
  • frontier model이 “Hyrum’s Law”라는 문구를 학습 데이터에서 읽었더라도, 새벽 3시에 API를 설계할 때 자동으로 적용하지는 않음
  • 스킬은 이런 관행을 에이전트가 실제 작업 중 적용하게 만듦

실제 사용 방식

• 방식 1: marketplace로 설치

  • Claude Code를 사용한다면 다음 명령으로 설치함
  /plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills
  • 설치하면 /spec, /plan, /build, /test, /review, /ship, /code-simplify slash command를 사용할 수 있음
  • 에이전트가 컨텍스트에 따라 관련 스킬을 자동으로 활성화함
  • 대부분의 사용자는 이 방식으로 시작하는 것이 권장됨

• 방식 2: 원하는 도구에 Markdown 넣기

  • 스킬은 frontmatter가 있는 일반 Markdown 파일임
  • Cursor 사용자는 .cursor/rules/에 넣을 수 있음
  • Gemini CLI는 자체 설치 경로가 있음
  • Codex, Aider, Windsurf, OpenCode, 시스템 프롬프트를 받을 수 있는 다른 도구도 읽을 수 있음
  • 중요한 것은 도구 자체보다 그 아래의 워크플로임

• 방식 3: 명세처럼 읽기

  • 아무것도 설치하지 않더라도 스킬은 AI 에이전트와 함께 좋은 엔지니어링을 수행하는 방식에 대한 문서화된 설명임
  • code-review-and-quality.md를 읽고 5축 프레임워크를 팀 리뷰 프로세스에 적용할 수 있음
  • test-driven-development.md를 읽고 “테스트를 먼저 작성해야 하는가” 같은 논쟁에 활용할 수 있음
  • 메타 스킬을 읽고 5가지 협상 불가능 원칙을 자신의 AGENTS.md에 가져갈 수 있음
  • 현재 가장 아픈 문제에 가까운 스킬 4~5개를 고르고, 강제하고 싶은 워크플로를 정한 뒤, 런타임을 설치하거나 직접 만들어 강제하는 흐름이 출발점이 될 수 있음

설치하지 않아도 가져갈 패턴

• 반합리화를 팀 관행으로 만들기

  • 팀이 스스로에게 하는 거짓말을 적어야 함
  • 예시는 “출시 후 테스트를 고치겠다”, “이 변경은 너무 작아서 설계 문서가 필요 없다”, “모니터링이 있으니 괜찮다” 같은 문장임
  • 각 문장에 반박을 붙이고 AGENTS.md나 엔지니어링 위키에 넣으면 논쟁을 줄이고 금요일 오후의 지친 지름길을 잡을 수 있음

• 내부 문서는 산문보다 프로세스로 쓰기

  • “우리는 X에 어떻게 접근하는가”라는 2,000단어 문서를 쓰고 있다면 참조 자료를 쓰는 것임
  • 이를 체크포인트가 있는 워크플로로 바꾸면 문서는 400단어로 줄고 실제로 실행될 가능성이 커짐
  • 이 원칙은 온보딩 가이드, 런북, 에이전트 스킬 모두에 적용됨

• 검증을 단단한 종료 기준으로 삼기

  • 모든 작업의 마지막 단계는 “증거 생성”이어야 함
  • 에이전트, 엔지니어, 개인 작업 모두에 적용됨
  • 증거는 녹색 테스트 실행, 스크린샷, 로그, 리뷰 승인처럼 작업이 끝났음을 입증하는 것이면 됨
  • 증거가 없으면 작업은 끝난 것이 아니며, “그럴듯해 보임”은 루프를 닫지 못함

• 모든 규칙집에 점진적 공개 적용하기

  • 50페이지 핸드북을 쓰지 말고, 상황에 맞는 작은 장으로 보내는 작은 라우터를 작성해야 함
  • 이는 AGENTS.md, 런북, 장애 대응 플레이북, 압박 상황에서 읽어야 하는 모든 문서에 적용됨

• AGENTS.md에 넣을 5가지 협상 불가능 원칙

  • 구축 전에 가정을 드러내야 함. 조용히 유지된 잘못된 가정은 가장 흔한 실패 모드임
  • 요구사항이 충돌하면 멈추고 물어야 함. 추측하지 않아야 함
  • 필요할 때는 반대해야 함. 에이전트나 엔지니어는 예스맨이 아님
  • 지루하고 명확한 해법을 선호해야 함. 영리함은 비쌈
  • 요청받은 것만 건드려야 함

하네스 안에서의 위치

• 스킬은 더 큰 관점에서 agent harness engineering의 한 계층임
• 하네스는 모델과 그 주변에 구축한 모든 것을 포함하며, 스킬은 시스템 프롬프트에 점진적으로 공개되는 재사용 가능한 워크플로 조각임
• 스킬은 AGENTS.md, hooks, tools, session log와 나란히 놓임
  • AGENTS.md: 계속 갱신되는 규칙집 역할임
  • hooks: 결정론적 강제 계층임
  • tools: 에이전트가 수행할 수 있는 행동임
  • session log: 지속되는 메모리임
  • skills: 시니어 엔지니어링 프로세스를 담당함
• 스킬은 채팅형 에이전트보다 long-running agents에서 더 중요함
• 긴 실행은 모든 지름길을 증폭함
  • 10분 세션에서 테스트를 건너뛴 에이전트는 버그 하나를 만들 수 있음
  • 30시간 세션에서 테스트를 건너뛴 에이전트는 실행 끝에 원래 의도를 아무도 기억하지 못하는 디버깅 고고학 작업을 만들 수 있음
• 실행 시간이 길수록 시니어 엔지니어링 스캐폴딩은 제안이 아니라 강제로 적용되어야 함
• 스킬 형식의 이식성도 중요함
• 같은 SKILL.md 파일은 Claude Code, rules를 쓰는 Cursor, Gemini CLI, Codex, 시스템 프롬프트 콘텐츠를 받을 수 있는 다른 하네스에서 사용할 수 있음
• 워크플로를 한 번 작성하면 런타임이 강제할 수 있으며, 이것이 bespoke prompt engineering과 달리 Markdown-with-frontmatter 형식이 주는 이점임

결론

• AI 코딩 에이전트는 diff에 드러나지 않는 업무에 대한 본능이 없는, 매우 유능한 주니어 엔지니어처럼 동작함
• 가정 드러내기, 변경 크기 조절, 명세 작성, 증거 남기기, 리뷰할 수 없는 변경 병합 거부 같은 시니어 엔지니어링 작업은 에이전트가 건너뛰지 못하게 만들지 않으면 건너뛸 가능성이 큼
• 점점 더 중요한 일은 이런 규율을 에이전트가 스스로 말로 빠져나갈 수 없는 형태로 인코딩하는 것임
• 스킬은 그 한 가지 형태이며, 반합리화 표, 점진적 공개, 산문보다 프로세스, 종료 기준으로서의 검증, 이미 작동하는 Google 관행을 이식 가능하게 만든 구조가 핵심임
• Agent Skills 저장소는 MIT 라이선스로 공개되어 있으며, 더 넓은 스캐폴딩 관점은 Agent Harness Engineering과 Long-running Agents에서 이어짐