엔터프라이즈를 위한 Skills

이 가이드는 조직 전체에서 Agent Skills를 관리해야 하는 엔터프라이즈 관리자와 아키텍트를 위한 것입니다. Skills를 대규모로 검증, 평가, 배포 및 관리하는 방법을 다룹니다. 작성 가이드는 모범 사례를 참조하세요. 아키텍처 세부 사항은 Skills 개요를 참조하세요.

보안 검토 및 검증

엔터프라이즈에서 Skills를 배포하려면 두 가지 별개의 질문에 답해야 합니다:

1. Skills는 일반적으로 안전한가? 플랫폼 수준의 보안 세부 사항은 개요의 보안 고려 사항 섹션을 참조하세요.
2. 특정 Skill을 어떻게 검증하는가? 아래의 위험 평가 및 검토 체크리스트를 사용하세요.

위험 등급 평가

배포를 승인하기 전에 각 Skill을 다음 위험 지표에 대해 평가하세요:

검토 체크리스트

서드파티 또는 내부 기여자의 Skill을 배포하기 전에 다음 단계를 완료하세요:

1. 모든 Skill 디렉토리 콘텐츠를 읽으세요. SKILL.md, 참조된 모든 마크다운 파일, 번들된 스크립트 또는 리소스를 검토하세요.
2. 스크립트 동작이 명시된 목적과 일치하는지 확인하세요. 샌드박스 환경에서 스크립트를 실행하고 출력이 Skill의 설명과 일치하는지 확인하세요.
3. 적대적 지시문을 확인하세요. Claude에게 안전 규칙을 무시하거나, 사용자로부터 작업을 숨기거나, 응답을 통해 데이터를 유출하거나, 특정 입력에 따라 동작을 변경하도록 지시하는 내용을 찾으세요.
4. 외부 URL 가져오기 또는 네트워크 호출을 확인하세요. 스크립트와 지시문에서 네트워크 접근 패턴(http, requests.get, urllib, curl, fetch)을 검색하세요.
5. 하드코딩된 자격 증명이 없는지 확인하세요. Skill 파일에서 API 키, 토큰 또는 비밀번호를 확인하세요. 자격 증명은 환경 변수나 보안 자격 증명 저장소를 사용해야 하며, Skill 콘텐츠에 절대 나타나서는 안 됩니다.
6. Skill이 Claude에게 호출하도록 지시하는 도구와 명령을 식별하세요. 모든 bash 명령, 파일 작업 및 도구 참조를 나열하세요. Skill이 파일 읽기와 네트워크 도구를 함께 사용할 때의 결합된 위험을 고려하세요.
7. 리디렉션 대상을 확인하세요. Skill이 외부 URL을 참조하는 경우, 예상되는 도메인을 가리키는지 확인하세요.
8. 데이터 유출 패턴이 없는지 확인하세요. 민감한 데이터를 읽은 다음 외부 전송을 위해 쓰거나, 보내거나, 인코딩하는 지시문을 찾으세요. Claude의 대화 응답을 통한 유출도 포함됩니다.

배포 전 Skills 평가

Skills가 잘못 트리거되거나, 다른 Skills와 충돌하거나, 부적절한 지시를 제공하면 에이전트 성능이 저하될 수 있습니다. 프로덕션 배포 전에 평가를 필수로 요구하세요.

평가 항목

Skill을 배포하기 전에 다음 차원에 대한 승인 게이트를 설정하세요:

평가 요구 사항

Skill 작성자에게 Skill당 3-5개의 대표 쿼리가 포함된 평가 스위트를 제출하도록 요구하세요. Skill이 트리거되어야 하는 경우, 트리거되지 않아야 하는 경우, 모호한 엣지 케이스를 포함해야 합니다. Skill 효과는 모델에 따라 다르므로, 조직에서 사용하는 모델(Haiku, Sonnet, Opus) 전반에 걸친 테스트를 요구하세요.

평가 구축에 대한 자세한 가이드는 모범 사례의 평가 및 반복을 참조하세요. 일반적인 평가 방법론은 테스트 케이스 개발을 참조하세요.

라이프사이클 결정을 위한 평가 활용

평가 결과는 조치가 필요한 시점을 알려줍니다:

• 트리거 정확도 하락: Skill의 설명이나 지시를 업데이트하세요
• 공존성 충돌: 겹치는 Skills를 통합하거나 설명을 좁히세요
• 지속적으로 낮은 출력 품질: 지시를 다시 작성하거나 검증 단계를 추가하세요
• 업데이트 후에도 지속되는 실패: Skill을 폐기하세요

Skill 라이프사이클 관리

대규모 Skills 구성

리콜 한계

일반적인 가이드라인으로, 안정적인 리콜 정확도를 유지하기 위해 동시에 로드되는 Skills 수를 제한하세요. 각 Skill의 메타데이터(이름과 설명)는 시스템 프롬프트에서 주의를 두고 경쟁합니다. 너무 많은 Skills가 활성화되면 Claude가 올바른 Skill을 선택하지 못하거나 관련 Skill을 완전히 놓칠 수 있습니다. Skills를 추가하면서 평가 스위트를 사용하여 리콜 정확도를 측정하고, 성능이 저하되면 추가를 중단하세요.

API 요청은 요청당 최대 8개의 Skills를 지원합니다(API로 Skills 사용하기 참조). 역할에 단일 요청이 지원하는 것보다 더 많은 Skills가 필요한 경우, 좁은 Skills를 더 넓은 것으로 통합하거나 작업 유형에 따라 요청을 다른 Skill 세트로 라우팅하는 것을 고려하세요.

구체적으로 시작하고 나중에 통합

팀이 광범위한 다목적 Skills보다 좁고 워크플로에 특화된 Skills로 시작하도록 권장하세요. 조직 전반에서 패턴이 나타나면 관련 Skills를 역할 기반 번들로 통합하세요.

진행 예시:

• 시작: formatting-sales-reports, querying-pipeline-data, updating-crm-records
• 통합: sales-operations (평가가 동등한 성능을 확인한 경우)

명명 및 카탈로그 관리

조직 전체에서 일관된 명명 규칙을 사용하세요. 모범 사례의 명명 규칙 섹션에서 서식 가이드를 제공합니다.

각 Skill에 대해 내부 레지스트리를 유지하세요:

• 목적: Skill이 지원하는 워크플로
• 소유자: 유지 관리를 담당하는 팀 또는 개인
• 버전: 현재 배포된 버전
• 종속성: 필요한 MCP 서버, 패키지 또는 외부 서비스
• 평가 상태: 마지막 평가 날짜 및 결과

역할 기반 번들

각 사용자의 활성 Skill 세트를 집중시키기 위해 조직 역할별로 Skills를 그룹화하세요:

• 영업팀: CRM 운영, 파이프라인 보고, 제안서 생성
• 엔지니어링: 코드 리뷰, 배포 워크플로, 인시던트 대응
• 재무: 보고서 생성, 데이터 검증, 감사 준비

각 역할 기반 번들에는 해당 역할의 일상 워크플로와 관련된 Skills만 포함되어야 합니다.

배포 및 버전 관리

소스 관리

히스토리 추적, 풀 리퀘스트를 통한 코드 리뷰, 롤백 기능을 위해 Skill 디렉토리를 Git에 저장하세요. 각 Skill 디렉토리(SKILL.md 및 번들된 파일 포함)는 자연스럽게 Git 추적 폴더에 매핑됩니다.

API 기반 배포

Skills API는 워크스페이스 범위의 배포를 제공합니다. API를 통해 업로드된 Skills는 모든 워크스페이스 멤버가 사용할 수 있습니다. 업로드, 버전 관리 및 관리 엔드포인트는 API로 Skills 사용하기를 참조하세요.

버전 관리 전략

• 프로덕션: Skills를 특정 버전에 고정하세요. 새 버전을 프로모션하기 전에 전체 평가 스위트를 실행하세요. 모든 업데이트를 전체 보안 검토가 필요한 새 배포로 취급하세요.
• 개발 및 테스트: 프로덕션 프로모션 전에 변경 사항을 검증하기 위해 최신 버전을 사용하세요.
• 롤백 계획: 이전 버전을 대체 수단으로 유지하세요. 새 버전이 프로덕션에서 평가에 실패하면 즉시 마지막으로 알려진 정상 버전으로 되돌리세요.
• 무결성 검증: 검토된 Skills의 체크섬을 계산하고 배포 시 이를 확인하세요. Skill 저장소에서 서명된 커밋을 사용하여 출처를 보장하세요.

크로스 서피스 고려 사항

Git에 Skill 소스 파일을 단일 진실 소스로 유지하세요. 조직이 여러 서피스에 Skills를 배포하는 경우, 일관성을 유지하기 위해 자체 동기화 프로세스를 구현하세요. 전체 세부 사항은 크로스 서피스 가용성을 참조하세요.

다음 단계