Agent Skills란? 긴 프롬프트를 작업별 파일로 나누는 기준

펼친 파란 공구 주머니에 놓인 도구들과 빈 카드. 이해를 돕기 위한 AI 생성 개념 이미지입니다.

매번 같은 작업 절차를 프롬프트에 붙여 넣고 있다면 Agent Skills가 도움이 될 수 있습니다. 반대로 한 번 물어볼 질문까지 스킬로 만들면 관리할 파일만 늘어납니다.

스킬을 늘리기 전에 반복할 작업과 실행 권한을 분리해 적으세요.

스킬은 새 모델이 아니라 필요할 때 읽는 작업 묶음입니다

Agent Skills 공식 설명에서 스킬의 기본 단위는 SKILL.md가 들어 있는 폴더입니다. 이름·설명과 작업 지침을 담고, 필요하면 실행 스크립트나 참고 자료를 함께 둡니다. 모델을 다시 학습시키는 기능은 아닙니다.

작동 순서는 발견, 활성화, 실행으로 나뉩니다. 처음에는 이름과 설명으로 후보를 찾고, 작업이 맞으면 전체 지침을 읽으며, 추가 자료는 필요할 때 불러옵니다. 그래서 “무슨 일을 할 때 쓰는가”가 모호하면 본문이 정교해도 선택 과정에서 어긋날 수 있습니다.

PDF 정리라는 이름보다 입력과 결과를 적습니다

가상의 개인 자료 정리 작업을 생각해 보겠습니다. 사용자는 공개 PDF에서 표를 추출해 CSV로 보관하려고 합니다. 스킬 설명이 “문서를 잘 처리합니다”라면 요약·번역·변환 가운데 무엇을 맡기는지 알기 어렵습니다.

아래는 형식을 설명하기 위한 미실행 예시입니다.

---
name: public-pdf-table
description: 공개 PDF의 표를 CSV로 옮기고 원본 페이지와 행·열을 대조할 때 사용합니다.
---

형식 검수에서는 name이 부모 폴더 이름과 일치하고 소문자·숫자·하이픈만 쓰는지, description이 무엇을 언제 쓰는지 설명하는지부터 봅니다. 공식 명세는 name을 1~64자, description을 1~1024자로 제한하고, scripts/, references/, assets/는 선택 폴더로 둡니다. 본문에는 고정된 형식보다 작업 단계·예외·중단 조건을 명확히 적는 편이 중요합니다.

본문에는 입력 PDF를 바꾸지 않는다는 조건, 병합 셀 처리 방식, 결과 CSV의 저장 위치, 숫자가 원문과 안 맞을 때 멈추는 기준을 적습니다. 변환 라이브러리 설명서 전체를 본문에 복사할 필요는 없습니다. 실제로 쓰는 옵션만 지침에 두고 상세 문서는 별도 참고 파일로 연결하면 됩니다.

공식 형식 명세는 이름과 설명을 필수 메타데이터로 두며, 스크립트·참고 자료·자산 폴더는 선택 사항으로 구분합니다. 비어 있는 폴더를 전부 미리 만들 이유도 없습니다.

프롬프트, 스킬, 도구는 서로 다른 질문에 답합니다

한 번의 요청에는 “이 PDF의 두 번째 표를 옮겨줘”가 들어갑니다. 스킬에는 같은 작업을 반복할 때 지킬 절차가 들어갑니다. 실제 파일을 읽거나 CSV를 쓰는 행동은 실행 도구가 합니다. 절차를 적었다고 실행 도구가 생기거나 파일 권한이 확대되는 것은 아닙니다.

이 구분은 가져온 스킬을 검토할 때 특히 중요합니다. 설명은 표 추출인데 동봉 스크립트가 문서를 외부 서버로 보내면, 검토 대상은 문장뿐 아니라 그 전송 경로까지입니다. 파일을 읽어보라는 지침과 스크립트를 실행해도 된다는 승인은 다르게 다뤄야 합니다. 이는 여기서 제안하는 운영 기준이지, 스킬 형식 자체의 보안 보증이 아닙니다.

추가보다 통합이 나을 때도 있습니다

같은 입력을 두고 이름만 다른 스킬 둘이 번갈아 선택된다면 경계가 겹치는지 살펴보세요. 작업 결과가 같고 예외 처리도 같으면 하나로 합칠 후보입니다. 반대로 결과가 같아도 공개 자료와 민감 자료처럼 허용된 처리 경로가 다르면 조건을 분명히 나눠야 합니다.

처음에는 반복 작업 하나에만 적용하고, 실제 요청에서 선택되는지와 결과 확인 절차가 빠지지 않는지를 봅니다. 스킬 수가 늘어난 것은 능력이 늘었다는 증거가 아닙니다.

실제 폴더를 설계한다면 무엇을 어디에 둘까

스킬 하나를 만든다고 가정하면 처음부터 거대한 설명서를 쓰기보다 실행 경계를 파일 구조로 드러내는 편이 낫습니다. 다음은 형식을 보여주는 가상 구조입니다.

public-pdf-table/
├── SKILL.md              # 언제 쓰고 언제 멈출지
├── scripts/
│   └── extract_table.js  # 반복 실행할 변환 로직
└── references/
    └── validation.md     # 병합 셀·단위 검수 기준

SKILL.md에는 작업 순서와 중단 조건을 둡니다. 스크립트에는 같은 입력에 같은 처리를 반복할 코드가 들어갑니다. 참고 파일에는 매번 본문에 넣을 필요는 없지만 판단할 때 찾아볼 기준을 둡니다. 비밀 키나 개인 문서는 이 폴더의 구성 요소가 아닙니다. 실행 시 별도의 안전한 자격 증명 경로와 입력 범위를 사용해야 합니다.

예를 들어 절차는 다음처럼 좁힐 수 있습니다.

1. 입력이 PDF이고 공개 자료인지 확인한다.
2. 사용자가 지정한 페이지의 표만 추출한다.
3. 원본의 열 이름과 결과 CSV의 열 이름을 대조한다.
4. 숫자·단위가 맞지 않거나 병합 셀 의미를 결정할 수 없으면 저장하지 않고 보고한다.
5. 결과 파일 경로와 검수하지 못한 셀을 함께 반환한다.

“표를 잘 추출한다”보다 위 절차가 유용한 이유는 실패를 숨기지 않기 때문입니다. 스킬은 결과를 항상 성공으로 만드는 장치가 아니라 반복 작업의 성공·중단 기준을 재사용하는 장치로 보는 편이 정확합니다.

새 스킬을 만들지 판단하는 표

질문	예라면	아니라면
같은 절차를 여러 번 반복하는가	스킬 후보	일회성 프롬프트로 충분할 수 있음
입력과 결과 형식이 구분되는가	계약을 문서화	먼저 작업 자체를 더 좁힘
실패 시 멈출 기준이 있는가	스킬 본문에 명시	자동 실행을 미룸
반복 가능한 코드가 있는가	scripts로 분리 검토	지침만으로 시작 가능
긴 참고 자료가 매번 필요한가	references로 분리	본문에 핵심만 유지
파일·네트워크 쓰기가 필요한가	별도 도구 권한 검토	읽기 전용으로 시작

이 표에서 중요한 것은 “스킬이 있으면 자동화된다”가 아니라 자동화할 수 있는 부분과 사람이 판단할 부분을 나누는 것입니다. 같은 PDF라도 표 좌표가 고정된 문서는 스크립트 비중이 커질 수 있고, 매번 형식이 다른 문서는 중간 검수 단계가 더 중요할 수 있습니다.

가져온 스킬을 검토할 때 보는 순서

외부에서 받은 스킬은 설명만 읽고 설치하지 않습니다. 먼저 name과 description이 실제 작업 범위를 과장하지 않는지 보고, 본문에서 실행하라는 명령과 접근 파일을 찾습니다. 다음으로 동봉 스크립트의 네트워크 요청, 환경 변수 사용, 쓰기 경로와 삭제 동작을 확인합니다. 마지막으로 작은 공개 샘플에서 결과와 중단 조건을 시험합니다.

• 설명은 읽기 작업인데 스크립트가 외부 전송을 하는가.
• 상대 경로라고 생각했지만 홈 디렉터리 전체를 훑는가.
• 실패를 0 종료 코드로 숨기거나 기존 파일을 덮어쓰는가.
• 결과 검증 없이 “완료”만 반환하는가.
• 참조 문서 안의 문장을 실행 지시로 오인할 여지가 있는가.

이 검토는 Agent Skills 형식이 악성이라는 뜻이 아닙니다. 스킬이 지침·스크립트·자료를 묶을 수 있기 때문에 각 구성 요소의 신뢰 경계도 함께 봐야 한다는 뜻입니다.

적용 범위

2026년 9월 7일 확인한 공개 형식 설명을 기준으로 썼습니다. 제품마다 발견 방식과 도구 권한 지원은 다르며, 이 예시를 특정 앱에 설치하거나 실행해 성능을 측정한 글은 아닙니다.