오늘의 AI 글: 코딩 에이전트를 잘 쓰는 팀은 프롬프트가 아니라 스킬을 축적한다

왜 이 글인가

코딩 에이전트를 처음 쓰면 대부분의 관심은 “어떤 모델이 더 똑똑한가”에 쏠린다. Claude Code가 나은지, Codex류 CLI가 나은지, Cursor의 에이전트 모드가 더 편한지 비교하게 된다. 그런데 몇 주만 지나면 더 실용적인 질문으로 이동한다. “왜 같은 일을 매번 다시 설명해야 하지?”, “지난번에 합의한 출력 형식을 왜 잊지?”, “우리 팀의 리뷰 기준을 매번 장황하게 붙여야 하나?” 같은 문제다. 모델 성능이 충분히 좋아진 뒤에는, 결국 반복 업무의 표준을 어떻게 저장하고 재사용하느냐가 생산성을 좌우한다.

오늘 고른 글은 Claude Code의 Skills 기능을 제품 관리와 개발 업무 관점에서 설명한다. 원문은 5분 정도면 읽을 수 있는 짧은 글이지만, 지금 시점에는 꽤 중요한 방향을 짚는다. AI 에이전트를 잘 쓰는 방식이 단발성 프롬프트 작성에서 “작업 운영체제”를 만드는 쪽으로 이동하고 있기 때문이다. 한 번 좋은 프롬프트를 작성해 클립보드에 저장하는 수준을 넘어, 특정 업무가 들어오면 자동으로 발동되는 규칙, 템플릿, 체크리스트, 산출물 형식을 파일로 남겨두는 방식이다. 이건 단순 편의 기능이 아니라 팀의 판단 기준을 재사용 가능한 자산으로 바꾸는 일에 가깝다.

특히 Claude Code의 Skills는 SKILL.md라는 구조화된 마크다운 파일로 표현된다. YAML front matter로 언제 이 스킬을 활성화할지 설명하고, 본문에는 에이전트가 따라야 할 절차와 품질 기준을 적는다. 프로젝트 전체에 공통으로 쓰는 스킬은 전역 위치에, 특정 저장소에만 필요한 스킬은 프로젝트 안에 둘 수 있다. 이 구조는 개발자에게 익숙하다. 린터 설정, 테스트 설정, CI 워크플로처럼 “팀이 원하는 방식”을 파일로 버전 관리하는 접근과 닮아 있다.

이 글을 오늘 추천하는 또 하나의 이유는, Claude Code 커스터마이징의 세 층위인 skills, subagents, hooks를 간단하지만 명확히 구분하기 때문이다. 많은 사용자가 이 세 가지를 “에이전트를 더 똑똑하게 만드는 기능” 정도로 뭉뚱그려 이해한다. 하지만 실제로는 역할이 다르다. Skills는 반복 업무의 playbook이고, subagents는 별도 맥락에서 병렬로 일하는 작업자이며, hooks는 특정 이벤트에 자동으로 실행되는 안전장치 또는 자동화다. 이 구분을 이해하면 코딩 에이전트를 훨씬 덜 위험하고, 훨씬 일관되게 쓸 수 있다.

원문 전문은 공개 fetch로 접근 가능했고, 글의 핵심 주장과 예시는 공개 본문 기준으로 확인했다. 아래 글은 원문을 옮긴 번역이 아니라, 한국어 독자를 위해 의미를 풀고 실무 적용 관점으로 재구성한 해설이다.

핵심 요약

• Skills는 “좋은 프롬프트 저장소”보다 조금 더 구조화된 개념이다. 사용자가 반복적으로 수행하는 업무에 대해, 언제 발동되어야 하는지와 어떤 기준으로 결과를 만들어야 하는지를 SKILL.md에 적어둔다. 에이전트는 상황에 따라 자동으로 해당 스킬을 참고하거나, 사용자가 slash command 형태로 직접 호출할 수 있다.

• 원문은 특히 PM 업무 예시를 든다. 경쟁사 분석, 이해관계자 업데이트, PRD 작성과 리뷰, 오류 분석처럼 반복되지만 매번 품질 기준을 설명해야 하는 일이 스킬의 좋은 후보가 된다. 개발 업무로 확장하면 코드 리뷰, 릴리스 노트 작성, 장애 회고, 테스트 실패 분석, 마이그레이션 검토, API 문서화도 같은 범주에 들어간다.

• Skills의 핵심 가치는 시간 절약보다 “판단 기준의 고정”에 있다. 매번 “짧고 명확하게 써줘”, “리스크를 따로 분리해줘”, “근거 없는 확신은 피하고 모르는 부분은 표시해줘”라고 말하는 대신, 그런 기준을 스킬에 적어두면 된다. 그러면 에이전트가 산출물을 만들 때마다 같은 잣대를 적용할 가능성이 높아진다.

• Skills는 개인 생산성 도구이면서 동시에 팀 지식 관리 도구다. 개인이 만든 스킬은 자신의 반복 업무를 줄여주고, 프로젝트 안에 들어간 스킬은 팀의 업무 방식을 에이전트가 읽을 수 있게 만든다. 좋은 팀은 README만 관리하는 것이 아니라, 에이전트가 따라야 할 작업 지침도 함께 관리하게 될 가능성이 크다.

• 원문은 skills, subagents, hooks의 차이를 짧게 설명한다. Skills는 현재 대화 안에서 특정 업무 수행 방식을 알려주는 재사용 가능한 지침이다. Subagents는 별도 컨텍스트에서 무거운 작업을 수행하고 결과를 돌려주는 격리된 작업자다. Hooks는 명령 실행 전후나 파일 편집 후처럼 특정 시점에 자동으로 발동되는 자동화 또는 보호 장치다.

• 이 구분은 안전과도 연결된다. 예를 들어 “오류 분석을 항상 같은 형식으로 해라”는 skill에 적합하다. “전체 코드베이스를 훑고 독립적으로 리뷰해라”는 subagent에 적합하다. “삭제 명령이 나오면 막거나 승인 요청을 하라”는 hook에 적합하다. 문제 유형에 맞지 않는 계층을 쓰면 에이전트가 불필요하게 복잡해지거나 위험해진다.

• Skills는 오픈 표준으로 확장될 가능성이 있다. 원문은 Claude Code를 중심으로 설명하지만, Agent Skills라는 공개 표준을 언급한다. 특정 도구에만 갇힌 프롬프트 모음이 아니라 여러 에이전트가 읽을 수 있는 작업 지침 형식으로 발전하면, 팀의 AI 업무 자산을 도구 간에 이전하기 쉬워진다.

• 재미있는 예시로 원문은 “humanizer” 스킬을 언급한다. AI가 쓴 티를 줄이는 전용 스킬이 존재한다는 사실 자체가 현재 AI 사용 문화의 단면을 보여준다. 사람들은 이미 AI로 글을 만들고 있고, 동시에 그 결과가 너무 AI처럼 보이지 않게 만드는 규칙도 자동화하려 한다.

• 이 글은 기술적으로 깊은 튜토리얼이라기보다, 에이전트 커스터마이징의 mental model을 잡아주는 글이다. 그래서 Claude Code를 이미 쓰는 사람에게는 바로 적용할 아이디어를 주고, 아직 쓰지 않는 사람에게는 앞으로 AI 도구를 평가할 때 무엇을 봐야 하는지 알려준다.

원문의 논지를 단계별로 풀어보기

첫 번째 단계는 “반복 업무를 매번 프롬프트로 설명하는 방식의 한계”를 인식하는 것이다. AI 도구를 업무에 붙이면 초반에는 긴 프롬프트를 잘 쓰는 사람이 이긴다. 예를 들어 PRD를 작성할 때 목적, 사용자 문제, 범위, 비범위, 성공 지표, 리스크, 롤아웃 계획을 포함하라고 자세히 지시하면 그럭저럭 쓸 만한 결과가 나온다. 하지만 같은 일을 반복할수록 문제가 생긴다. 좋은 지시문을 매번 복사해 붙여야 하고, 조금씩 수정하다 보면 품질 기준이 흐트러진다. 팀원마다 쓰는 프롬프트가 달라지면 산출물 형식도 달라진다.

두 번째 단계는 그 반복 지시를 스킬로 분리하는 것이다. Skills는 “이런 상황에서는 이런 절차를 따르라”는 작업 지침을 파일로 저장한다. 예를 들어 PRD 리뷰 스킬에는 “목표 고객이 명확한지 확인하라”, “성공 지표가 측정 가능한지 보라”, “범위 밖 항목이 별도로 정리되었는지 확인하라”, “가장 큰 리스크 세 가지와 완화책을 제시하라” 같은 기준을 적을 수 있다. 그러면 사용자는 매번 긴 지침을 쓰지 않고 “이 PRD 리뷰해줘”라고 요청해도 에이전트가 해당 스킬을 참고할 수 있다.

세 번째 단계는 스킬의 활성화 방식을 이해하는 것이다. 원문에 따르면 Claude Code에서는 스킬이 맥락에 따라 자동으로 발동될 수도 있고, 사용자가 slash command로 직접 호출할 수도 있다. 자동 발동은 편리하지만 설명이 중요하다. YAML front matter나 설명 문구가 모호하면 에이전트가 엉뚱한 상황에서 스킬을 쓰거나, 정작 필요한 상황에서 놓칠 수 있다. 그래서 좋은 스킬은 본문만 잘 쓰는 것이 아니라 “언제 써야 하는지”를 정확히 적어야 한다.

네 번째 단계는 skills와 subagents를 구분하는 것이다. Skill은 현재 대화와 작업 흐름 안에서 에이전트의 행동 방식을 조정한다. 반면 subagent는 별도 맥락에서 더 무거운 일을 맡는 작업자에 가깝다. 예를 들어 현재 세션에서 버그를 고치는 중인데, 동시에 “이 변경과 관련된 보안 리스크를 독립적으로 검토해줘”라고 맡기고 싶다면 subagent가 적합하다. 반대로 “버그 분석 결과를 항상 원인, 재현 절차, 수정 방향, 검증 방법으로 나눠서 보고해줘”는 skill에 적합하다.

다섯 번째 단계는 hooks의 역할을 이해하는 것이다. Hook은 사용자가 매번 요청하지 않아도 특정 이벤트에 자동으로 실행된다. 예를 들어 에이전트가 셸 명령을 실행하기 전 위험한 패턴을 검사하거나, 파일을 수정한 뒤 포맷터를 실행하거나, 세션 시작 시 최신 오류 로그를 불러오게 할 수 있다. 원문은 rm 같은 삭제 명령을 막는 예를 든다. 이건 skill보다 hook에 어울린다. “삭제 명령은 조심하라”는 지침을 모델에게 말하는 것보다, 실제 실행 직전에 기술적으로 가로막는 편이 안전하기 때문이다.

마지막 단계는 이 세 가지를 조합해 자신만의 작업 환경을 만드는 것이다. 반복 작업의 품질 기준은 skills에 넣고, 큰 조사나 병렬 검토는 subagents에 맡기고, 반드시 지켜야 하는 안전 규칙과 자동화는 hooks로 강제한다. 이렇게 나누면 에이전트 사용 경험이 훨씬 안정된다. 모든 것을 하나의 거대한 시스템 프롬프트에 몰아넣는 방식보다 유지보수가 쉽고, 무엇이 왜 작동하는지도 추적하기 쉽다.

일반 독자에게 중요한 포인트

• AI 업무 자동화의 다음 단계는 “한 번 답을 잘 받는 법”이 아니라 “반복 업무를 일관되게 처리하는 법”이다. 좋은 프롬프트 하나를 잘 쓰는 능력도 여전히 중요하지만, 매번 같은 품질을 얻으려면 그 프롬프트를 재사용 가능한 규칙으로 바꿔야 한다. Skills는 그 방향을 보여주는 좋은 예다.

• 에이전트에게 일을 맡긴다는 것은 단순히 명령을 내리는 것이 아니다. 사람 조직에서 신입에게 업무 매뉴얼, 템플릿, 리뷰 기준, 금지 사항을 알려주듯이, AI 에이전트에게도 작업 방식을 알려주는 문서가 필요하다. Skills는 그런 문서를 에이전트가 직접 읽고 실행할 수 있는 형태로 만든다.

• “AI가 알아서 잘하겠지”라는 기대는 반복 업무에서 특히 위험하다. 모델은 문맥에 민감하고, 같은 요청도 표현 방식에 따라 다른 산출물을 만들 수 있다. 반대로 기준을 파일로 고정하면 매번 운에 맡기는 부분이 줄어든다. AI를 더 많이 쓸수록 자유로운 대화보다 명시적인 운영 규칙이 중요해진다.

• Skills와 hooks의 차이는 일반 사용자에게도 유용한 사고방식이다. “항상 이런 형식으로 답해줘”는 skill에 가깝고, “이런 위험한 행동은 실행 전에 반드시 멈춰”는 hook에 가깝다. 즉 조언과 강제는 다르다. AI에게 말로 부탁해도 되는 규칙과 시스템이 직접 막아야 하는 규칙을 구분해야 한다.

• AI 도구 선택 기준도 바뀐다. 앞으로는 모델 성능뿐 아니라 내 업무 방식을 얼마나 잘 저장하고, 공유하고, 버전 관리하고, 안전하게 실행하는지가 중요해진다. 개인에게는 생산성 차이가 되고, 팀에게는 품질 관리와 감사 가능성의 차이가 된다.

개발자에게 중요한 포인트

개발자 입장에서 이 글의 핵심은 “에이전트 사용법도 코드처럼 관리해야 한다”는 점이다. 프로젝트에는 이미 수많은 암묵적 규칙이 있다. 어떤 테스트를 먼저 돌리는지, 어떤 디렉터리는 자동 수정하면 안 되는지, API 변경 시 어떤 문서를 함께 고쳐야 하는지, 마이그레이션은 어떤 순서로 검토해야 하는지, 릴리스 노트에는 무엇을 포함해야 하는지 같은 것들이다. 사람 개발자에게는 온보딩 문서와 코드 리뷰로 전파되지만, 에이전트에게는 명시적인 입력으로 제공되어야 한다.

가장 쉬운 출발점은 “매번 반복해서 말하는 문장”을 찾는 것이다. 예를 들어 에이전트에게 자주 “먼저 관련 파일을 읽고 계획을 세운 뒤 수정해”, “테스트 실패 원인을 추측하지 말고 로그 근거를 인용해”, “변경 후에는 build와 typecheck를 돌려”, “최종 답변에는 수정 파일과 검증 결과를 요약해”라고 말한다면, 그건 skill 후보가 된다. 반대로 “절대 홈 디렉터리의 비밀 파일을 읽지 마”, “배포 명령은 승인 없이 실행하지 마” 같은 규칙은 단순 skill에만 맡기지 말고 권한 정책이나 hook으로 강제하는 편이 낫다.

또 하나 중요한 점은 스킬을 너무 크게 만들지 않는 것이다. “우리 팀의 모든 개발 방식”을 하나의 거대한 스킬에 넣으면, 에이전트가 언제 무엇을 적용해야 할지 흐려진다. 대신 코드 리뷰 스킬, 테스트 실패 분석 스킬, 릴리스 노트 스킬, 마이그레이션 검토 스킬처럼 업무 단위로 나누는 편이 좋다. 작은 스킬은 수정하기 쉽고, 특정 상황에서만 발동시키기도 쉽다.

스킬은 개인 취향이 아니라 품질 관리 도구가 될 수도 있다. 예를 들어 코드 리뷰 스킬에 “변경 의도와 실제 diff가 일치하는지 확인”, “보안·성능·접근성 영향을 분리해서 검토”, “확실하지 않은 지적은 질문 형태로 표현”, “사소한 스타일 지적은 자동 포맷터 범위면 생략” 같은 기준을 넣으면 리뷰의 톤과 밀도를 일정하게 만들 수 있다. 이는 사람 리뷰어의 판단을 대체한다기보다, 반복적인 체크리스트를 안정화하는 데 가깝다.

적용 아이디어

• 최근 2주 동안 AI 에이전트에게 반복해서 시킨 업무를 적어본다. PRD 초안, 오류 분석, 코드 리뷰, 테스트 작성, 배포 노트, 경쟁사 분석, 회의 요약처럼 세 번 이상 반복된 업무가 첫 번째 skill 후보가 된다.

• 각 후보에 대해 “좋은 결과물의 조건”을 5~10개 문장으로 쓴다. 예를 들어 오류 분석이라면 재현 조건, 직접 원인, 근본 원인, 영향 범위, 수정안, 검증 명령, 재발 방지 항목이 포함되어야 한다고 적을 수 있다.

• 스킬 설명에는 언제 발동되어야 하는지 명확히 쓴다. “사용자가 에러 로그, 실패한 테스트, 스택트레이스, 빌드 실패를 분석해 달라고 요청할 때 사용한다”처럼 트리거 조건을 구체화하면 자동 활성화의 정확도가 올라간다.

• 전역 스킬과 프로젝트 스킬을 분리한다. 글쓰기 톤, 일반적인 오류 분석, 회의 요약처럼 어디서나 쓰는 것은 전역에 둘 수 있다. 특정 저장소의 테스트 명령, 디렉터리 구조, 릴리스 규칙처럼 프로젝트에 묶인 것은 저장소 안에서 관리하는 편이 안전하다.

• 스킬 하나를 만든 뒤 바로 완벽하게 만들려고 하지 말고, 실제 작업 3~5번에 적용해본다. 결과가 너무 길거나 짧은지, 자꾸 빠뜨리는 항목이 있는지, 필요 없는 형식이 있는지 보고 조금씩 수정한다. 스킬은 문서라기보다 작은 제품처럼 다루는 편이 좋다.

• Subagent가 필요한 작업과 skill로 충분한 작업을 구분한다. 현재 대화의 맥락 안에서 산출물 형식만 안정화하면 되는 일은 skill로 충분하다. 긴 조사, 독립 코드 리뷰, 여러 파일을 훑는 분석처럼 현재 흐름을 오염시키기 쉬운 일은 subagent가 더 적합하다.

• Hook이 필요한 안전 규칙을 따로 목록화한다. 삭제, 배포, 외부 전송, 대량 파일 수정, 데이터베이스 변경처럼 “모델이 조심하겠다고 말하는 것”만으로는 부족한 행동은 실행 전 차단이나 승인 흐름으로 강제해야 한다.

• 팀에서 쓴다면 스킬도 코드 리뷰 대상에 포함한다. 스킬은 에이전트의 행동을 바꾸는 설정이므로, 잘못 작성하면 품질 저하나 안전 문제를 만들 수 있다. 중요한 프로젝트 스킬은 PR로 변경하고, 왜 그 기준이 필요한지 기록하는 편이 좋다.

읽기 우선순위

Claude Code를 이미 쓰고 있고 매번 비슷한 지시를 반복하고 있다면 원문을 바로 읽어볼 만하다. 글 자체는 짧지만, “내가 반복하는 프롬프트 중 무엇을 스킬로 빼야 하지?”라는 질문을 시작하게 만든다. 특히 PM, 테크 리드, 개발 생산성 담당자처럼 산출물 형식과 리뷰 기준을 자주 다루는 사람에게 유용하다.

다만 깊은 구현 튜토리얼을 기대하면 조금 가볍게 느껴질 수 있다. 실제 SKILL.md를 어떻게 설계할지, front matter를 어떻게 써야 할지, hooks를 어떻게 구성할지는 원문에 연결된 공식 문서와 추가 글을 함께 봐야 한다. 이 글은 입문용 지도에 가깝고, 다음 단계는 자신이 반복하는 업무 하나를 골라 작은 스킬로 만들어보는 것이다.

오늘의 결론은 단순하다. 코딩 에이전트를 잘 쓰는 사람은 프롬프트를 잘 쓰는 데서 멈추지 않는다. 반복되는 판단 기준을 파일로 남기고, 위험한 행동은 시스템으로 막고, 무거운 작업은 별도 맥락에 분리한다. Skills는 그중 첫 번째 습관을 시작하기 좋은 도구다.