[한영자막] 당신은 에이전트 스킬을 제대로 사용하지 못하고 있습니다

URL: https://www.youtube.com/watch?v=3HB4GZkpw58 날짜: 2026-07-27 채널: Tech Bridge

---

📌 핵심 질문 / 이 영상이 다루는 핵심 논점

많은 사람들이 에이전트 스킬(agent skill)이 무엇인지는 알지만, ==스킬을 제대로 활용하지 못하거나 잠재력을 최대한 끌어내지 못하고 있다==. 스킬은 결국 에이전트에게 주입하는 "프롬프트"일 뿐이지만, 어떻게 구조화하고 언제 활성화되게 하며 어디에 배치하느냐에 따라 결과물의 품질이 크게 달라진다.

• 스킬은 skill.md 파일 하나만으로 끝나는 게 아니라, 참조 문서(references), 자산(assets, 블루프린트 등), 스크립트(scripts)까지 포함하는 "점진적 발견(incremental discovery)" 구조를 갖는다.
• 스킬이 존재하는 이유는 크게 두 가지다: 모델의 지식 격차(knowledge gap)를 메우거나, 모델의 실행 방식(execution gap)을 원하는 대로 통제하는 것.
• 좋은 스킬은 활성화가 잘 되도록 하는 "설명(description)"과, 프로즈(prose)가 아닌 불릿 포인트 중심의 "린(lean)하고 실행 가능한 본문"으로 구성된다.

발표자는 자신이 사용하는 create plan, code review, decomplex, generate image, use Pi sub agents, VPS setup hardening 등 실제 스킬들을 예로 들며, 스킬을 단순히 수집하지 말고 직접 만들고 지속적으로 다듬어야 한다고 강조한다. 또한 스킬을 어디에 둘지(글로벌 vs. 프로젝트 로컬), 그리고 언제 스킬 대신 agents.md/Claude.md를 써야 하는지에 대한 명확한 기준도 제시한다.

---

1. 에이전트 스킬의 본질: 다들 안다고 생각하지만 제대로 모르는 것

에이전트 스킬은 결국 에이전트에게 주입하는 추가 컨텍스트, 즉 일종의 "프롬프트"일 뿐이지만, 그 내부 구조와 활성화 방식을 제대로 이해하는 사람은 많지 않다.

1.1. skill.md 파일의 구조와 점진적 발견(Progressive Disclosure)

1. skill.md는 두 부분으로 나뉜다

   1. 설명(description) 메타데이터: 에이전트가 "적절한 순간"에 해당 스킬을 활성화하도록 돕는 부분으로, 모든 에이전트 세션에 항상 로드된다.
   2. 실제 스킬 지시사항(instructions): 코딩 에이전트나 다른 에이전트에 주입되어 원하는 방식으로 특정 작업을 수행하게 만드는 본문 콘텐츠로, 스킬이 활성화된 후에만 로드된다.

2. 스킬은 하나의 파일로 끝나지 않는다

   1. 많은 사람이 아는 사실: 일부 스킬은 skill.md 파일 하나로 충분하지만, 많은 스킬은 필요할 때만 에이전트가 불러오는 추가 참조 문서(references)와 심화 자료(deep-dive resources)를 갖는다.
   2. 적게 아는 사실: 스킬은 참조 문서 외에도 블루프린트 같은 "자산(assets)"과 "스크립트(scripts)"까지 가질 수 있다. 예: 발표자의 create plan 스킬은 에이전트가 계획을 작성할 때 따라야 할 플랜 블루프린트를 자산으로 갖고 있다.

1.2. 스킬과 스크립트의 관계: 왜 그냥 스크립트로 안 만드나?

1. 결정론적(deterministic) 부분은 스크립트로 처리한다

   1. generate image 스킬 예시: fal.ai(다양한 AI 모델을 API로 제공하는 서비스)에 요청을 보내고, 응답을 처리하고, 이미지를 추출해 저장하는 과정은 TypeScript 스크립트가 담당한다.
   2. 하드코딩된 모델 선택: 이 스킬에서는 이미지 생성 모델로 GPT image 2가 하드코딩되어 있으며, 필요하면 언제든 바꿀 수 있다.

2. 스킬은 스크립트로 대체할 수 없는 "번역" 역할을 한다

   1. 모호한 지시를 프롬프트로 변환: "비 오는 날 자전거 이미지가 필요해" 같은 모호한 지시를 스킬 안의 지침에 따라 적절한 프롬프트로 변환한 뒤 스크립트를 호출한다.
   2. 두 세계의 장점을 결합: 프롬프트를 직접 쓸 수도 있지만, 스킬이 이를 자동화해줌으로써 결정론적 실행과 유연한 해석을 동시에 얻는다.

---

2. 스킬이 필요한 두 가지 근본 이유: 지식 격차와 실행 격차

에이전트 스킬은 크게 두 가지 목적을 위해 존재한다: 모델이 모르는 것을 알게 하거나(지식), 모델이 일하는 방식을 원하는 대로 통제하는 것(실행)이다.

2.1. 지식 격차(Knowledge Gap) 해소

1. 모델 지식의 세 가지 원천

   1. 학습 데이터와 파인튜닝: 모델에 내재된(baked-in) 지식으로, 강화학습(RL)을 포함한 학습 과정에서 얻어진다.
   2. 컨텍스트로 주어지는 지식: 코드베이스, 프롬프트, 웹 리서치 등 세션 중에 추가로 제공되는 지식.
   3. 스킬로 제공하는 지식: 특정 작업이나 도메인에 대한 지식을 별도로 추가하는 세 번째 경로.

2. 덜 알려진 라이브러리를 위한 도메인 지식 스킬 만들기 (effect 라이브러리 예시)

   1. 문제 상황: effect 라이브러리는 모델 학습 데이터에 비교적 적게 반영되어 있어, 다른 유명 라이브러리만큼 모델이 잘 알지 못한다.
   2. AI를 활용한 지식 수집: AI에게 웹 리서치와 공식 문서 탐색을 시켜 effect 라이브러리에 대한 지식을 수집시키고, 반드시 방문해야 할 특정 URL을 직접 지정해 주기도 한다.
   3. create skill 스킬로 변환: 수집된 지식을 스킬로 변환할 때도 AI를 활용하는데, 이때 발표자 자신의 모범 사례(best practice)와 패턴을 인코딩한 "create skill" 스킬을 사용해 AI가 만든 결과를 자신이 다시 다듬는다.

2.2. 실행 격차(Execution Gap) 해소 — create plan 스킬 심층 사례

1. 왜 내장 Plan Mode 대신 스킬을 쓰는가

   1. 에이전트별 한계: 발표자가 주로 쓰는 파이(Pi) 코딩 에이전트에는 애초에 Plan Mode가 없다.
   2. Claude Code에서도 스킬을 선호: Claude Code처럼 Plan Mode가 내장된 도구를 쓸 때도, 최근에는 내장 기능 대신 스킬을 쓴다. 이 스킬은 "계획을 만들어 달라"는 요청의 설명(description)에 의해 암묵적으로, 그리고 매우 안정적으로 활성화된다.

2. create plan 스킬 안에 인코딩된 것들

   1. 연구와 서브 에이전트 위임 지침: 계획을 세우기 전 수행해야 할 리서치와, 그 리서치를 서브 에이전트에 위임하는 방법(서브 에이전트 활용 및 작업 분할에 대한 전용 스킬도 별도로 존재).
   2. 고정된 플랜 템플릿: 발표자가 계획을 리뷰하기 때문에, 항상 동일한 구조를 갖도록 하는 템플릿을 스킬 안에 넣어둔다.
   3. 리뷰 단계 자동 내재화: 계획이 완성되면 곧바로 리뷰까지 거치도록 리뷰 단계도 스킬 안에 인코딩해, 발표자가 보는 계획은 이미 한 차례 검토를 마친 상태다.

3. 리뷰를 위한 code review 스킬의 세부 규칙

   1. 서브 에이전트를 통한 작업 분할: 리뷰 작업도 분할되어야 하며, 메인 컨텍스트 윈도우를 깨끗하게 유지하기 위해 서브 에이전트를 활용해야 한다는 규칙을 명시한다.
   2. 발견 사항(findings) 점수화 규칙: 모든 발견 사항을 계획이나 리뷰 결과에 다 반영하지 않고, 판단(judge)을 거쳐 걸러내도록 한다.
   3. 복잡도 관리(decomplex 스킬): "과도한 복잡성"이 무엇인지 정의하고 이를 점검하는 방법을 다루는 전용 decomplex 스킬을 별도로 운용해, 계획이나 코드에 복잡성이 계속 쌓이는 것을 방지한다.
   4. 모호할 때는 사용자에게 묻기: 무언가가 너무 복잡한지, 실제 문제인지 불분명하면 사용자에게 확인을 요청하도록 모든 관련 스킬에 명시해 둔다.

4. 여러 스킬이 서로를 트리거하는 계층 구조

   1. 다층적 시스템: create plan → code review → decomplex 스킬이 서로 연결되어, 계획 요청 하나에 리뷰와 복잡도 점검까지 자동으로 이어지는 시스템을 구성한다.
   2. 결과: 대부분 그대로 실행 가능하고(executable), 이미 검토를 마친(reviewed) 양호한 상태의 계획을 얻는다.

---

3. 좋은 스킬을 만들고 유지하는 원칙

같은 지침을 프롬프트에 매번 반복해서 넣는 대신 스킬로 만들어야 하며, 스킬은 만든 뒤 방치하지 말고 계속 다듬어야 한다.

3.1. "매번 반복해서 요청하는 것"이 스킬로 만들 신호

1. 반복되는 요청이나 반복되는 실수는 스킬로 전환하라

   1. 일반 원칙: 같은 내용을 계속 프롬프트에 넣고 있거나, 같은 종류의 오류에 대해 계속 지적하고 있다면 그것을 스킬로 만들어야 한다는 신호다.
   2. 프롬프트로도 가능하지만 비효율적: create plan 관련 지침을 매번 프롬프트에 넣을 수도 있지만, 그러면 매번 반복하는 셈이 되므로 스킬로 만드는 것이 합리적이다.

2. 다른 사람의 스킬을 써도 되지만, 반드시 자신만의 스킬을 만들어라

   1. 공개 스킬 활용은 문제없다: 발표자 자신의 스킬이나 Matt Pocock 등 다른 사람의 스킬을 그대로 써도 무방하며, 좋은 시작점이 될 수 있다.
   2. 개인화가 필수적인 이유: 사람마다 일하는 방식이 다르기 때문에, 발표자에게 잘 맞는 스킬이 다른 사람에게는 맞지 않을 수 있다. 따라서 다듬고(refine), 자신의 것으로 만들고(make them yours), 자신의 워크플로우와 문제에 맞는 스킬을 직접 만들어야 한다.

3.2. 스킬 작성 스타일: 린(lean)하게, 불릿 포인트 중심으로

1. 좋은 스킬의 핵심은 두 가지뿐이다

   1. 적절한 순간에 활성화되도록 하는 좋은 설명(description): 이것이 스킬이 언제 켜질지를 결정하는 유일한 장치다.
   2. 린하고 실행 가능한 본문(lean actionable body): 발표자는 프로즈(줄글) 대신 불릿 포인트 형식을 선호한다.

2. AI로 스킬을 작성할 때 특히 주의할 점

   1. AI는 스킬을 과도하게 부풀리는 경향이 있다: 일부 AI 모델은 지나치게 상세하고(thorough) 방대한(bloated) 스킬을 만들어내는 경향이 있다.
   2. 부풀려진 스킬의 이중 비용: 그런 스킬은 토큰 비용을 늘릴 뿐만 아니라, 컨텍스트를 오염시켜(pollute) 오히려 결과 품질을 떨어뜨릴 수 있다. 따라서 AI로 스킬 초안을 만들더라도 반드시 직접 다듬어 간결한 스타일로 유도해야 한다.

3.3. 스킬은 정적인 것이 아니라 계속 진화해야 한다

1. 스킬이 낡는 이유들

   1. 모델 자체의 변화: 어떤 신모델은 이전 모델보다 훨씬 더 공격적(aggressive)이거나 장황(verbose)해질 수 있어, 예전 모델에 맞춰 만든 스킬이 새 모델에는 안 맞을 수 있다.
   2. 코딩 에이전트 하니스와 도구의 변화: 사용하는 도구 목록이나 암묵적으로 추가되는 시스템 프롬프트도 계속 바뀐다.
   3. 작업자 본인의 작업 방식 변화: 1년 전에는 지금보다 훨씬 많은 코드를 직접 작성했지만, 지금은 코드를 읽고 쓰는 방식 자체가 달라졌다. 이런 변화에 따라 스킬도 함께 진화해야 한다.

2. 스킬을 자동으로 개선하는 improve skill 스킬

   1. 자동 개선 메커니즘: 에이전트가 특정 규칙을 자주 틀리거나 사용자가 특정 부분을 자주 정정할 경우, 정의된 규칙에 따라 자동으로 스킬을 개선하도록 하는 "improve skill" 스킬을 추가로 둘 수 있다.
   2. 오래된 스킬은 버릴 수도 있다: 반년 전에 설치한 스킬이 지금도 유용하다는 보장은 없으므로, 더 이상 제 역할을 못 하면 버리는 것도 고려해야 한다. 다른 사람이 만든 스킬을 그냥 수집만 하지 말라는 원칙과 연결된다.

---

4. 에이전트 스킬의 4가지 유형

발표자는 실제로는 서로 겹치는 부분이 있지만, 크게 네 가지 유형으로 스킬을 구분한다.

4.1. 도메인 지식 스킬(Domain Knowledge Skill)과 워크플로우 스킬(Workflow Skill)

1. 도메인 지식 스킬

   1. 정의: 특정 프로젝트나 도메인에 필요한 전문 지식을 담아, 에이전트가 매번 같은 조사를 반복하지 않도록 하는 스킬.
   2. 예시: effect 라이브러리에 대한 지식을 담아 특정 프로젝트에 추가하는 스킬.

2. 워크플로우 스킬

   1. 정의: 반복적으로 수행하는 작업 흐름을 명확한 구조로 인코딩해, 매번 같은 설명을 반복하지 않도록 하는 스킬.
   2. 예시: 앞서 상세히 다룬 create plan 스킬이 대표적인 워크플로우 스킬이다.

4.2. 컴패니언 스킬(Companion Skill)과 실행형 스킬(Executable Skill)

1. 컴패니언 스킬 — 특정 도구의 사용법을 에이전트에게 설명

   1. use Pi sub agents 스킬 예시: 파이(Pi) 코딩 에이전트로 서브 에이전트를 실행하고 제어하는 스크립트를 갖고 있으며, 이 스크립트를 확장 프로그램(extension)이 아니라 스킬 형태로 제공한다.
   2. 일반화 가능성: 시스템에 설치한 다른 CLI 도구의 사용법을 에이전트에게 설명하고 싶을 때도 같은 방식의 컴패니언 스킬을 만들 수 있다.

2. 실행형 스킬 — 스크립트와 설정을 실행하는 스킬

   1. generate images 스킬: 앞서 설명한 이미지 생성 스킬이 대표적인 예다.
   2. VPS setup hardening 스킬: 여러 스크립트와 설정 템플릿을 갖고 있으며, 새 VPS를 설정할 때 이 스킬을 사용한다. 스크립트만으로도 할 수 있지만, 이런저런 판단과 점검이 필요하기 때문에 에이전트가 개입하는 것이 유용하다고 밝힌다. (다만 에이전트가 VPS에서 자유롭게 작업하도록 허용할지는 각자 판단할 문제라고 덧붙인다.)

---

5. 스킬을 어디에 둘 것인가: 배치 전략과 agents.md/Claude.md와의 구분

스킬을 다 만든 뒤에는 "어디에 설치할 것인가"와 "언제 스킬 대신 agents.md/Claude.md를 쓸 것인가"라는 두 가지 질문이 남는다.

5.1. 글로벌 스킬 vs. 프로젝트 로컬 스킬

1. 여러 프로젝트에 적용되면 글로벌로

   1. create plan 스킬: 발표자가 작업하는 거의 모든 프로젝트에 적용되므로 글로벌 스킬로 둔다.
   2. generate image 스킬: 시스템 어디서든 이미지를 생성하고 싶을 수 있으므로 글로벌 스킬로 둔다.

2. 특정 프로젝트에만 의미가 있으면 로컬로

   1. effect 라이브러리 지식 스킬: 이 라이브러리를 쓰는 프로젝트에만 가치가 있으므로 글로벌로 두면 오히려 의미가 없다.
   2. 글로벌 스킬의 숨은 비용: 글로벌 스킬은 최소한 그 메타데이터(설명)가 모든 세션에 항상 로드되기 때문에, 토큰 소모뿐 아니라 스킬(즉 도구)이 너무 많아지면 모델 성능 자체가 떨어질 수 있다. 그래서 발표자는 글로벌 스킬 수를 최대한 적게, 최대한 린하게 유지하고, 프로젝트에 넣을 수 있는 것은 다 프로젝트로 넣으려 한다.

5.2. 스킬 대신 agents.md / Claude.md에 넣어야 하는 것

1. agents.md/Claude.md는 "항상 적용되는 하드 룰"을 위한 곳

   1. 활성화가 필요 없는 규칙: "응답을 짧게 하라", "레거시나 폴백 코드를 추가하지 마라"처럼 모든 모델과 모든 에이전트에 항상 적용되어야 하는 규칙은 스킬이 아니라 agents.md/Claude.md에 넣는다.
   2. 모델들의 나쁜 습관 교정 사례: 일부 모델은 코드를 지우지 않고 계속 레이어만 쌓아 올리는 경향이 있는데, 이런 습관을 막기 위한 규칙이 agents.md에 넣을 대표적인 예다.

2. 스킬과 agents.md의 근본적 차이: "활성화" 여부

   1. 스킬은 활성화되어야 작동한다: 스킬은 설명에 따라 활성화될 수도, 안 될 수도 있는 반면, 반드시 지켜져야 하는 규칙이라면 활성화를 기대하며 기다릴 수 없다.
   2. agents.md도 글로벌/프로젝트 구분이 있다: agents.md와 Claude.md 역시 프로젝트 전용 파일뿐 아니라 글로벌 파일로도 둘 수 있으며, 글로벌로 두면 모든 세션에 항상 로드된다.
   3. 최종 기준: 스킬은 도구(tool)나 지식(knowledge) 조각처럼 "자주는 쓰이지만 항상은 아닌 것"이고, 항상 지켜져야 하는 것이라면 agents.md/Claude.md로 가야 한다.

---

주요 발언 모음

"A skill is, of course, in the end just a prompt, just some extra context you're sending to your agent to execute a certain task." (스킬은 결국 그저 프롬프트일 뿐이다. 에이전트에게 특정 작업을 실행시키기 위해 보내는 추가적인 컨텍스트에 불과하다.) "If you find yourself asking for the same stuff over and over again, or complaining about the same errors over and over again, put it in a skill." (같은 것을 계속 요청하거나, 같은 오류에 대해 계속 불평하고 있다면, 그것을 스킬로 만들어라.) "Don't just collect skills created by others. ... Write your own skills." (다른 사람이 만든 스킬을 그냥 수집만 하지 마라. 자신만의 스킬을 써라.) "A good skill really is just about having a good description so that it's getting activated in the right moments, and a lean actionable body." (좋은 스킬은 결국 적절한 순간에 활성화되게 하는 좋은 설명과, 린하고 실행 가능한 본문, 이 두 가지로 충분하다.) "Skills are like tools, like extra patterns or pieces of knowledge that matter often, but not always. If something does matter always, it goes into agents.md or Claude.md." (스킬은 도구와 같다. 자주 중요하지만 항상 중요한 것은 아닌 패턴이나 지식 조각이다. 항상 중요한 것이라면 agents.md나 Claude.md에 넣어야 한다.)

핵심 데이터 & 수치

• 스킬 구성 요소 4가지: description(메타데이터) + instructions(본문) + references(참조 문서) + assets/scripts(자산·스크립트) — 이 중 references와 assets/scripts는 필요할 때만 로드되는 "점진적 발견" 구조.
• 스킬 존재 이유 2가지: 지식 격차(knowledge gap) 해소, 실행 격차(execution gap) 해소.
• 스킬 유형 4가지: 도메인 지식 스킬, 워크플로우 스킬, 컴패니언 스킬, 실행형(executable) 스킬.
• 발표자가 실제 언급한 자신의 스킬 목록: create plan, code review, decomplex, generate image, create skill, use Pi sub agents, VPS setup hardening, improve skill.
• 배치 기준 2가지 질문: (1) 글로벌 vs. 프로젝트 로컬, (2) 스킬 vs. agents.md/Claude.md.

결론 및 시사점

1. 스킬은 단순 프롬프트 저장소가 아니라, 설명(활성화 트리거) + 본문 + 참조/자산/스크립트로 이어지는 점진적 발견 구조를 가진 시스템으로 설계해야 한다.
2. 스킬을 만드는 기준은 명확하다 — 같은 지시를 반복해서 내리고 있거나 같은 실수를 반복해서 교정하고 있다면 그것을 스킬로 전환해야 한다.
3. 스킬은 반드시 직접 다듬고 자신의 워크플로우에 맞게 커스터마이징해야 하며, 다른 사람의 스킬을 그대로 수집만 하는 것은 지양해야 한다.
4. AI로 스킬을 작성할 때는 프로즈로 부풀려지지 않도록 직접 개입해 린하고 불릿 포인트 중심의 스타일로 유지해야 한다 — 부풀려진 스킬은 토큰 비용뿐 아니라 컨텍스트 오염으로 결과 품질 저하까지 유발한다.
5. 스킬은 모델·도구·본인의 작업 방식이 바뀔 때마다 함께 진화해야 하는 대상이며, 필요하면 improve skill 같은 메타 스킬을 통해 자동 개선 루프를 만들거나, 낡은 스킬은 과감히 버려야 한다.
6. 배치는 두 가지 기준으로 결정한다 — 여러 프로젝트에 적용되면 글로벌, 특정 프로젝트에만 의미가 있으면 로컬로 두고, 예외 없이 항상 지켜져야 하는 하드 룰이라면 활성화를 기다릴 필요가 없는 agents.md/Claude.md에 넣는다.
7. 글로벌 스킬은 메타데이터가 항상 세션에 로드되므로, 그 수를 최소화하고 최대한 린하게 유지해야 전체 에이전트 성능 저하를 막을 수 있다.

---

메타데이터

• 원본 언어: 영어 (자동 생성 한국어 자막은 번역 품질이 낮아 영어 원문 자막 기반으로 정리함)
• 영상 길이: 약 18분 36초 (1116초)
• 채널: Tech Bridge
• video_id: 3HB4GZkpw58