1줄 정의

에이전트가 재사용하도록 추상화한 절차·계약 단위. 프롬프트보다 단단하고 도구보다 부드럽다

전체 시스템에서 맡는 역할

스킬은 “잘 쓴 프롬프트의 저장본” 이 아니다. 반복되는 업무를 재사용 가능한 계약 (contract) 으로 압축한 운영 artifact 다.

에이전트 운영 층위를 쭉 늘어놓으면 이렇다.

• prompt: 이번 요청을 어떻게 풀지에 대한 가설
• skill: 이 종류의 요청을 반복해서 안정적으로 푸는 계약
• harness: 스킬을 포함한 주변 장치 전부 (도구·루프·권한·검증)

프롬프트는 “한 번의 시도” 에 최적화된다. 스킬은 “같은 작업을 N 번 돌려도 품질이 안 무너지는” 걸 노린다. 그래서 내용이 문장 미학이 아니라 아래 다섯이 갖춰졌는지로 판가름난다.

1. Trigger — 언제 이 스킬을 부르나 / 언제 부르면 안 되나

2. Read order — 먼저 읽어야 하는 정본 문서·템플릿·소스

3. Inputs / outputs — 필요한 입력과 성공했을 때 출력의 모양

4. Boundaries — 스킬이 대신 결정하면 안 되는 영역, 멈춰야 할 조건

5. Failure checks — 버리거나 재검토해야 하는 출력의 판정 기준

이 다섯이 있으면 같은 태스크가 다른 사람·다른 세션·다른 에이전트에서 돌아도 결과가 가까운 범위로 수렴한다. 이게 “긴 프롬프트” 와의 결정적 차이다.

Agent Skills 는 이 추상 개념을 Claude Code 가 먼저 구현한 구체 인스턴스 다. 이 페이지는 상위의 일반 개념을 다루고, Claude Code 특유 사양 (/skill-name 호출·디렉터리 배치 등) 은 별도 페이지로 나눴다.

흔한 오해

• 오해 1: 스킬 = 오래 다듬은 프롬프트, 로 여겨지기 쉽다.

– 실제로 길이는 본질이 아니고 “반복성” 과 “계약성” 이 본질. 길어도 trigger 와 failure check 가 빠져 있으면 folklore (떠도는 구전) 에 머문다.

• 오해 2: 한 번 잘 먹힌 프롬프트는 바로 SKILL.md 로 올려야 한다, 라고 생각하기 쉽다.

– 실제로 1~2 회 성공은 아직 prompt hypothesis 단계. eval surface 와 representative input 이 없는 채로 승격시키면 숨은 의존성 (hidden input dependency) 이 굳어져 나중에 무너진다. 승격에는 eval harness 통과가 필요하다.

• 오해 3: 스킬을 늘리면 에이전트가 똑똑해진다, 라고 기대하기 쉽다.

– 실제로 스킬은 “특정 태스크에서 품질을 안정시키는” 도구. 관계 없는 스킬까지 얹으면 본체 판단이 오히려 흐려진다. 솎아내기 (demotion) 도 세트로 운영한다.

이 용어가 중요한 이유

스킬을 “긴 프롬프트” 가 아니라 “운영 계약” 으로 다룰 수 있게 되면 AI 개발 논의의 수준이 한 칸 올라간다.

• 어떤 작업이 반복성을 얻었는가
• 무엇을 성공으로 정의하고 무엇을 실패로 쳐내는가
• 어디서 사람 리뷰를 끼울 것인가
• 쓰이지 않게 된 스킬을 언제 강등시킬 것인가

이걸 답할 수 있는 팀은 모델이 새로워져도 artifact 가 자산으로 남는다. 반대로 “편한 프롬프트 모음” 에서 멈춘 팀은 모델 업데이트 때마다 0 에서 다시 한다. prompt engineering 에서 harness engineering 으로 이행하는 중간 단위, 그게 스킬이다.

실무 판단 예:

• Claude Code 의 Skills 기능 (agent-skills) 도입이 망설여질 때, “이 작업은 진짜 계약화할 만큼 반복되나” 부터 묻는다
• 기존 프롬프트 모음을 솎아낼 때 “실패 판정 기준을 못 쓰는 건 skill 로 안 올린다” 로 정한다
• eval theater (비교 대상 없이 “좋아졌다” 고 주장) 함정을 피하려고 승격 때 반드시 comparator 를 둔다

이 용어가 나오는 기사

• 하네스 엔지니어링, Agent Skills, Claude Code 관련 기사

다음에 읽을 용어 3개

• Agent Skills — Claude Code 의 구체 구현. 이 일반 개념이 특정 제품에서 어떻게 내려앉는지 보여준다.
• prompt — 스킬의 앞 단계. 가설층이지 계약이 아니다.
• eval harness — 스킬 승격을 판정하는 측정 장치.