포스트

Claude Skills가 긴 프롬프트를 줄이는 방식: 파일 구조, 라우팅, 실행 한계

이 글의 Claude Skills 패턴은 모든 지침을 처음부터 넣지 않고, 짧은 메타데이터로 후보를 찾은 뒤 필요한 지침과 스크립트만 불러 컨텍스트를 아끼는 방식입니다. 다만 여기서 다루는 claude-skills 저장소의 구조를 모든 Claude 환경의 공식 규격이나 자동 보안 경계로 일반화해서는 안 됩니다.

큰 프롬프트를 작은 진입점으로 바꾼다

하나의 시스템 프롬프트에 코딩 규칙, 배포 절차, 예외 사례를 모두 넣으면 매 요청마다 토큰을 쓰고 중요한 지시가 묻힐 수 있습니다. 이 저장소의 접근은 전문 지식을 폴더로 분리하고, 각 폴더의 이름과 설명을 먼저 노출하는 것입니다. 모델은 요청과 설명이 맞는 후보를 고른 뒤 SKILL.md의 상세 지침과 필요한 참고 자료를 읽습니다.

이 흐름은 메타데이터, 지침, 실행 자료의 세 층으로 볼 수 있습니다. 앞 단계가 작아야 평소 비용이 줄고, 뒷 단계는 해당 작업에서만 컨텍스트를 차지합니다. 모든 지식을 매번 밀어 넣는 방식에서 필요할 때 가져오는 방식으로 책임을 옮긴 셈입니다.

스크립트는 컨텍스트 절약과 권한 문제를 함께 만든다

스킬 폴더에는 Markdown 지침뿐 아니라 Python 유틸리티, JSON 참고 자료, 셸 스크립트가 포함될 수 있습니다. 큰 원본을 모델이 전부 읽고 계산하게 하는 대신 스크립트가 처리하고 작은 결과만 돌려주면 컨텍스트를 아낄 수 있습니다. 반복 가능한 변환을 코드로 고정한다는 장점도 있습니다.

하지만 실행 결과만 짧게 보인다고 내부 행동까지 안전한 것은 아닙니다. 파일 접근, 네트워크, 명령 실행 권한을 별도로 제한하고 스크립트를 검토해야 합니다. 원문에 나온 disable-model-invocation, allowed-tools 같은 프런트매터 예시는 호출 방식과 도구 범위를 표현하지만, 이름만으로 런타임 격리가 자동 보장된다고 가정하면 안 됩니다.

라우팅 품질은 설명 문장에서 갈린다

메타데이터가 너무 넓으면 비슷한 스킬이 동시에 후보가 되고, 너무 좁으면 필요한 순간에 선택되지 않습니다. “코드를 돕는다”보다 입력, 결과물, 사용 조건과 제외 조건이 드러나는 설명이 낫습니다. 같은 요청 묶음을 반복해 어떤 스킬이 선택됐고 불필요한 자료를 얼마나 읽었는지 기록해야 합니다.

팀에서 적용할 때는 한 스킬에 한 책임을 두고, 공통 규칙을 여러 폴더에 복제하지 않으며, 지침과 스크립트를 함께 버전 관리하는 편이 좋습니다. 도구 이름이 겹치거나 오래된 예제가 남으면 모델이 올바른 폴더를 골라도 잘못된 행동을 할 수 있으므로 폐기 절차도 필요합니다.

프롬프트 엔지니어링이 사라지는 것은 아니다

점진적 로딩은 프롬프트를 없애지 않습니다. 어느 요청에서 어떤 지침을 선택할지, 충돌할 때 무엇을 우선할지, 도구 결과를 어떻게 검증할지를 더 작은 모듈로 옮깁니다. 초기 호출 지연과 여러 번의 도구 왕복도 비용으로 남습니다.

또한 원문 참고 링크에는 MCP 문서가 포함되지만, MCP와 이 저장소의 스킬 폴더는 같은 개념이라고 단정할 근거가 되지 않습니다. 실제 환경에 붙일 때는 지원되는 디렉터리, 메타데이터 필드, 권한 동작을 그 환경의 문서와 실행 결과로 확인해야 합니다. 이 패턴의 실질적 성과는 멋진 폴더 구조가 아니라 불필요한 컨텍스트 감소, 정확한 라우팅, 안전한 실행으로 측정해야 합니다.

점진적 로딩은 어떤 순서로 작동하나

첫 단계에는 모든 지침의 본문이 아니라 이름과 짧은 설명처럼 선택에 필요한 정보만 둡니다. 모델은 현재 요청과 이 메타데이터를 비교해 후보를 고릅니다. 두 번째 단계에서 선택한 스킬의 상세 지침을 읽고, 그 지침이 지정한 참고 자료나 스크립트가 실제로 필요할 때만 다음 자료를 불러옵니다. 각 단계가 앞 단계보다 구체적인 정보를 제공하는 구조입니다.

이 방식의 이득은 사용하지 않는 전문 지식이 매 요청의 컨텍스트를 차지하지 않는 데 있습니다. 그러나 선택 단계에서 잘못된 스킬을 고르면 뒤의 상세 지침이 아무리 좋아도 도움이 되지 않습니다. 반대로 후보를 너무 많이 열어 두면 메타데이터 자체가 커지고 비슷한 지침 사이의 충돌이 늘어납니다. 컨텍스트 절약과 라우팅 정확도를 함께 측정해야 하는 이유입니다.

자료를 늦게 읽는 횟수가 늘면 도구 왕복과 지연도 생깁니다. 짧은 작업인데 여러 파일을 차례로 열어야 한다면 처음부터 작은 공통 지침을 넣는 것보다 비효율적일 수 있습니다. 작업 빈도와 자료 크기를 기준으로 항상 필요한 규칙, 조건부로 필요한 전문 지식, 실행으로 넘길 계산을 구분해야 합니다.

설명 문장에는 무엇을 넣어야 할까

좋은 설명은 스킬이 무엇에 관한 것인지뿐 아니라 언제 선택해야 하는지를 알려 줍니다. 예상 입력, 만들어야 할 결과, 대표 요청 표현, 제외할 상황을 짧게 담을 수 있습니다. 예를 들어 “문서를 돕는다”는 범위가 너무 넓지만 “회의 메모를 결정과 후속 작업이 있는 회의록으로 변환한다”는 입력과 결과가 더 분명합니다.

비슷한 스킬이 있다면 경계를 대칭적으로 써야 합니다. 하나에는 사용 조건을 자세히 적고 다른 하나에는 주제명만 적으면 모델의 선택이 설명 품질에 치우칠 수 있습니다. 같은 요청이 두 설명에 모두 맞는다면 책임을 합치거나 우선순위를 상세 지침에 명시해야 합니다. 어느 쪽도 맞지 않는 요청에서 억지로 선택되지 않는지도 중요합니다.

라우팅 평가는 실제 요청 목록으로 합니다. 명확한 긍정 사례, 표현이 다른 긍정 사례, 비슷하지만 제외해야 할 사례, 두 스킬이 충돌하는 사례를 준비합니다. 어떤 후보가 선택됐는지, 불필요한 파일을 몇 개 읽었는지, 최종 결과가 요구 형식에 맞았는지를 기록하면 설명을 감으로 고치는 일을 줄일 수 있습니다.

공통 규칙과 작업별 규칙은 어디서 나눌까

보안, 개인정보 처리, 출력 언어처럼 모든 작업에 적용되는 규칙을 각 스킬에 복제하면 수정 시점이 달라져 충돌할 수 있습니다. 이런 규칙은 공통 계층에서 한 번 관리하는 편이 낫습니다. 반면 특정 데이터 형식, 도메인별 판단 순서, 도구 사용 예시는 해당 스킬 가까이에 두어 필요한 작업에서만 읽게 합니다.

나누는 기준은 적용 범위와 변경 주기입니다. 여러 스킬에서 항상 지켜야 하고 함께 바뀌는 규칙은 공통 후보입니다. 한 작업에서만 필요하고 자주 수정되는 절차는 개별 스킬에 가깝습니다. 공통 파일을 다시 여러 단계로 참조하면 로딩 경로가 복잡해질 수 있으므로 참조 깊이에도 상한을 두는 것이 좋습니다.

같은 용어가 서로 다른 폴더에서 다른 뜻으로 쓰이는 문제도 확인해야 합니다. 공통 입력 형식과 오류 처리 계약을 정하고, 스킬별 예외는 이유와 우선순위를 명시합니다. 오래된 지침을 삭제하지 않고 남겨 두면 모델이 최신 파일과 함께 읽을 수 있으므로 버전 관리와 폐기 절차가 필요합니다.

스크립트를 사용할 때 무엇을 검토해야 할까

큰 CSV의 집계나 정해진 형식 변환처럼 결정론적인 작업을 스크립트로 옮기면 모델이 원본 전체를 컨텍스트에 넣지 않아도 됩니다. 같은 입력에 같은 출력을 내는 코드는 반복 가능성도 높입니다. 모델은 계산 자체보다 어떤 스크립트를 어떤 인수로 실행하고 결과를 어떻게 해석할지에 집중할 수 있습니다.

그 대신 스크립트는 새로운 실행 경계가 됩니다. 읽고 쓸 수 있는 경로, 외부 연결, 실행 가능한 명령, 입력 크기를 제한해야 합니다. 사용자나 외부 문서에서 온 문자열을 셸 명령이나 파일 경로에 그대로 넣지 않도록 검증합니다. 오류가 나면 부분 출력이 정상 결과처럼 전달되지 않도록 종료 상태와 결과 형식을 확인해야 합니다.

프런트매터에 허용 도구처럼 보이는 필드가 있어도 실제 실행 환경이 그 필드를 해석하고 강제하는지 별도 확인해야 합니다. 저장소의 예시와 사용하는 제품의 지원 규격이 다를 수 있기 때문입니다. 보안 테스트는 필드가 존재하는지를 보는 데서 끝나지 않고 금지된 파일이나 네트워크에 실제로 접근할 수 없는지 검증해야 합니다.

컨텍스트 절감 효과는 어떻게 측정할까

스킬을 도입하기 전과 후에 같은 요청 세트를 실행하고 초기 지침 크기, 추가로 읽은 자료량, 도구 호출 수, 완료 지연, 결과 정확도를 기록합니다. 전체 토큰이 줄어도 잘못된 라우팅 때문에 재시도가 늘거나 결과 품질이 떨어지면 성공이라고 보기 어렵습니다. 자주 쓰는 스킬과 거의 쓰지 않는 스킬을 나눠 분포별로 보는 것이 좋습니다.

설명만 읽고 끝나는 간단한 요청, 상세 지침까지 필요한 요청, 참고 자료와 스크립트까지 필요한 요청을 따로 측정합니다. 매번 모든 단계가 열리면 점진적 로딩이 제대로 작동하지 않는 것입니다. 반대로 필요한 참고 자료를 읽지 않아 근거 없는 답을 만들면 절감이 과도합니다.

운영 중에는 스킬 수가 늘 때 선택 정확도가 떨어지는지도 추적합니다. 새 스킬 추가 전후로 기존 요청의 선택 결과를 회귀 테스트하고, 사용되지 않는 스킬과 중복 설명을 정리합니다. 목표는 파일을 많이 만드는 것이 아니라 필요한 지침만 정확히 찾아 안전하게 실행하는 것입니다.

공식 규격과 저장소 패턴은 어떻게 구분할까

이 글의 저장소는 구조를 살펴볼 수 있는 하나의 구현 사례입니다. 특정 디렉터리 이름이나 프런트매터 필드가 모든 Claude 환경에서 같은 의미로 작동한다고 일반화할 수 없습니다. 사용하는 환경의 공식 문서에서 지원 필드와 로딩 순서를 확인하고, 작은 샘플로 실제 선택과 권한 동작을 시험해야 합니다.

MCP는 모델과 외부 도구, 자료를 연결하는 맥락에서 함께 언급될 수 있지만 스킬 폴더의 점진적 지침 로딩과 같은 개념은 아닙니다. 연결 규약, 지침 선택, 런타임 권한을 각각 분리해 검토해야 합니다. 한 영역의 설정이 다른 영역의 보안을 자동 해결한다고 가정하면 통제되지 않은 틈이 생깁니다.

도입 문서에는 저장소에서 관찰한 패턴, 실제 제품이 보장하는 동작, 팀이 추가한 운영 규칙을 구분해 적는 것이 좋습니다. 그러면 버전이 바뀌거나 다른 환경으로 옮길 때 무엇을 다시 검증해야 하는지 분명해집니다.

원문과 버전 확인

함께 읽으면 이해가 이어지는 글

자주 묻는 질문

Claude Skills를 쓰면 프롬프트 엔지니어링이 필요 없어지나요?

아닙니다. 긴 지침을 메타데이터와 작업별 파일로 나눌 뿐이며, 선택 조건, 우선순위, 도구 검증을 더 정확하게 설계해야 합니다.

스킬 설명은 어떻게 써야 올바르게 선택되나요?

입력과 결과물, 사용해야 하는 조건과 사용하지 말아야 하는 조건을 구체적으로 적는 편이 좋습니다. 비슷한 스킬과 구분되는 경계도 같은 요청 세트로 시험해야 합니다.

스킬 폴더의 스크립트는 자동으로 안전한가요?

아닙니다. 파일, 네트워크, 명령 실행 권한은 별도로 제한하고 코드를 검토해야 하며, 프런트매터의 필드 이름만으로 런타임 격리가 보장된다고 가정하면 안 됩니다.

THE END / OPSOAI

여기까지 읽었습니다

핵심 장면을 한 번 더 떠올려 보세요. 이해가 남았다면 이 책은 제 역할을 다했습니다.

다른 책 고르기
표지 1 —

←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.

CONTENTS

이 책의 목차

    13개 장 22 분읽는 시간