--- title: 스킬 description: 에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지. icon: bolt mode: "wide" --- ## 개요 스킬은 에이전트에게 **도메인별 지침, 가이드라인 및 참조 자료**를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다. 활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다. **스킬은 도구가 아닙니다.** 이것이 가장 흔한 혼동 포인트입니다. - **스킬**은 에이전트의 프롬프트에 *지침과 컨텍스트*를 주입합니다. 에이전트에게 문제에 대해 *어떻게 생각할지*를 알려줍니다. - **도구**는 에이전트에게 행동을 취할 수 있는 *호출 가능한 함수*를 제공합니다 (검색, 파일 읽기, API 호출). 흔히 **둘 다** 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다. --- ## 빠른 시작 ### 1. 스킬 디렉터리 생성 ``` skills/ └── code-review/ ├── SKILL.md # 필수 — 지침 ├── references/ # 선택 — 참조 문서 │ └── style-guide.md └── scripts/ # 선택 — 실행 가능한 스크립트 ``` ### 2. SKILL.md 작성 ```markdown --- name: code-review description: Guidelines for conducting thorough code reviews with focus on security and performance. metadata: author: your-team version: "1.0" --- ## 코드 리뷰 가이드라인 코드를 리뷰할 때 이 체크리스트를 따르세요: 1. **보안**: 인젝션 취약점, 인증 우회, 데이터 노출 확인 2. **성능**: N+1 쿼리, 불필요한 할당, 블로킹 호출 확인 3. **가독성**: 명확한 네이밍, 적절한 주석, 일관된 스타일 보장 4. **테스트**: 새로운 기능에 대한 적절한 테스트 커버리지 확인 ### 심각도 수준 - **크리티컬**: 보안 취약점, 데이터 손실 위험 → 머지 차단 - **메이저**: 성능 문제, 로직 오류 → 변경 요청 - **마이너**: 스타일 문제, 네이밍 제안 → 코멘트와 함께 승인 ``` ### 3. 에이전트에 연결 ```python from crewai import Agent from crewai_tools import GithubSearchTool, FileReadTool reviewer = Agent( role="Senior Code Reviewer", goal="Review pull requests for quality and security issues", backstory="Staff engineer with expertise in secure coding practices.", skills=["./skills"], # 리뷰 가이드라인 주입 tools=[GithubSearchTool(), FileReadTool()], # 에이전트가 코드를 읽을 수 있게 함 ) ``` 이제 에이전트는 **전문성** (스킬에서)과 **기능** (도구에서) 모두를 갖추게 됩니다. --- ## 스킬 + 도구: 함께 작동하기 스킬과 도구가 어떻게 보완하는지 보여주는 일반적인 패턴입니다: ### 패턴 1: 스킬만 (도메인 전문성, 액션 불필요) 에이전트가 특정 지침이 필요하지만 외부 서비스를 호출할 필요가 없을 때 사용: ```python agent = Agent( role="Technical Writer", goal="Write clear API documentation", backstory="Expert technical writer", skills=["./skills/api-docs-style"], # 작성 가이드라인 및 템플릿 # 도구 불필요 — 에이전트가 제공된 컨텍스트를 기반으로 작성 ) ``` ### 패턴 2: 도구만 (액션, 특별한 전문성 불필요) 에이전트가 행동을 취해야 하지만 도메인별 지침이 필요 없을 때 사용: ```python from crewai_tools import SerperDevTool, ScrapeWebsiteTool agent = Agent( role="Web Researcher", goal="Find information about a topic", backstory="Skilled at finding information online", tools=[SerperDevTool(), ScrapeWebsiteTool()], # 검색 및 스크래핑 가능 # 스킬 불필요 — 일반 연구에는 특별한 가이드라인이 필요 없음 ) ``` ### 패턴 3: 스킬 + 도구 (전문성 AND 액션) 가장 일반적인 실제 패턴. 스킬은 작업에 *어떻게* 접근할지를 제공하고, 도구는 에이전트가 *무엇을* 할 수 있는지를 제공합니다: ```python from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool analyst = Agent( role="Security Analyst", goal="Audit infrastructure for vulnerabilities", backstory="Expert in cloud security and compliance", skills=["./skills/security-audit"], # 감사 방법론 및 체크리스트 tools=[ SerperDevTool(), # 알려진 취약점 조사 FileReadTool(), # 설정 파일 읽기 CodeInterpreterTool(), # 분석 스크립트 실행 ], ) ``` ### 패턴 4: 스킬 + MCP 스킬은 도구와 마찬가지로 MCP 서버와 함께 작동합니다: ```python agent = Agent( role="Data Analyst", goal="Analyze customer data and generate reports", backstory="Expert data analyst with strong statistical background", skills=["./skills/data-analysis"], # 분석 방법론 mcps=["https://data-warehouse.example.com/sse"], # 원격 데이터 접근 ) ``` ### 패턴 5: 스킬 + 앱 스킬은 에이전트가 플랫폼 통합을 사용하는 방법을 안내할 수 있습니다: ```python agent = Agent( role="Customer Support Agent", goal="Respond to customer inquiries professionally", backstory="Experienced support representative", skills=["./skills/support-playbook"], # 응답 템플릿 및 에스컬레이션 규칙 apps=["gmail", "zendesk"], # 이메일 전송 및 티켓 업데이트 가능 ) ``` --- ## 크루 레벨 스킬 스킬을 크루에 설정하여 **모든 에이전트**에 적용할 수 있습니다: ```python from crewai import Crew crew = Crew( agents=[researcher, writer, reviewer], tasks=[research_task, write_task, review_task], skills=["./skills"], # 모든 에이전트가 이 스킬을 받음 ) ``` 에이전트 레벨 스킬이 우선합니다 — 동일한 스킬이 양쪽 레벨에서 발견되면 에이전트의 버전이 사용됩니다. --- ## SKILL.md 형식 ```markdown --- name: my-skill description: 이 스킬이 무엇을 하고 언제 사용하는지에 대한 간단한 설명. license: Apache-2.0 # 선택 compatibility: crewai>=0.1.0 # 선택 metadata: # 선택 author: your-name version: "1.0" allowed-tools: web-search file-read # 선택, 실험적 --- 에이전트를 위한 지침이 여기에 들어갑니다. 이 마크다운 본문은 스킬이 활성화되면 에이전트의 프롬프트에 주입됩니다. ``` ### 프론트매터 필드 | 필드 | 필수 | 설명 | | :-------------- | :----- | :----------------------------------------------------------------------- | | `name` | 예 | 1–64자. 소문자 영숫자와 하이픈. 디렉터리 이름과 일치 필수. | | `description` | 예 | 1–1024자. 스킬이 무엇을 하고 언제 사용하는지 설명. | | `license` | 아니오 | 라이선스 이름 또는 번들된 라이선스 파일 참조. | | `compatibility` | 아니오 | 최대 500자. 환경 요구 사항 (제품, 패키지, 네트워크). | | `metadata` | 아니오 | 임의의 문자열 키-값 매핑. | | `allowed-tools` | 아니오 | 공백으로 구분된 사전 승인 도구 목록. 실험적. | --- ## 디렉터리 구조 ``` my-skill/ ├── SKILL.md # 필수 — 프론트매터 + 지침 ├── scripts/ # 선택 — 실행 가능한 스크립트 ├── references/ # 선택 — 참조 문서 └── assets/ # 선택 — 정적 파일 (설정, 데이터) ``` 디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다. --- ## 사전 로드된 스킬 더 세밀한 제어를 위해 프로그래밍 방식으로 스킬을 검색하고 활성화할 수 있습니다: ```python from pathlib import Path from crewai.skills import discover_skills, activate_skill # 디렉터리의 모든 스킬 검색 skills = discover_skills(Path("./skills")) # 활성화 (전체 SKILL.md 본문 로드) activated = [activate_skill(s) for s in skills] # 에이전트에 전달 agent = Agent( role="Researcher", goal="Find relevant information", backstory="An expert researcher.", skills=activated, ) ``` --- ## 스킬 로드 방식 스킬은 **점진적 공개**를 사용합니다 — 각 단계에서 필요한 것만 로드합니다: | 단계 | 로드되는 내용 | 시점 | | :------- | :------------------------------------ | :------------------ | | 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` | | 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` | 일반적인 에이전트 실행 중(`skills=["./skills"]`로 디렉터리 경로 전달 시) 스킬은 자동으로 검색되고 활성화됩니다. 점진적 로딩은 프로그래밍 API를 사용할 때만 관련됩니다. --- ## 스킬 vs 지식 스킬과 지식 모두 에이전트의 프롬프트를 수정하지만, 서로 다른 목적을 가지고 있습니다: | 측면 | 스킬 | 지식 | | :--- | :--- | :--- | | **제공하는 것** | 지침, 절차, 가이드라인 | 사실, 데이터, 정보 | | **저장 방식** | 마크다운 파일 (SKILL.md) | 벡터 스토어에 임베딩 (ChromaDB) | | **검색 방식** | 전체 본문이 프롬프트에 주입 | 시맨틱 검색으로 관련 청크 찾기 | | **적합한 용도** | 방법론, 체크리스트, 스타일 가이드 | 회사 문서, 제품 정보, 참조 데이터 | | **설정 방법** | `skills=["./skills"]` | `knowledge_sources=[source]` | **경험 법칙:** 에이전트가 *프로세스*를 따라야 하면 스킬을 사용하세요. 에이전트가 *데이터*를 참조해야 하면 지식을 사용하세요. --- ## 자주 묻는 질문 사용 사례에 따라 다릅니다. 스킬과 도구는 **독립적**입니다 — 둘 중 하나, 둘 다, 또는 아무것도 사용하지 않을 수 있습니다. - **스킬만**: 에이전트가 전문성은 필요하지만 외부 액션이 필요 없을 때 (예: 스타일 가이드라인으로 작성) - **도구만**: 에이전트가 액션은 필요하지만 특별한 방법론이 필요 없을 때 (예: 간단한 웹 검색) - **둘 다**: 에이전트가 전문성 AND 액션이 필요할 때 (예: 특정 체크리스트로 보안 감사 AND 코드 스캔 기능) **아니요.** SKILL.md의 `allowed-tools` 필드는 실험적 메타데이터일 뿐 — 도구를 프로비저닝하거나 주입하지 않습니다. 항상 `tools=[]`, `mcps=[]` 또는 `apps=[]`를 통해 별도로 도구를 설정해야 합니다. 에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다. 50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다.