mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-04-13 22:42:37 +00:00
accae5ca43
* docs: add Agent Capabilities overview page and improve Skills docs - New 'Agent Capabilities' page explaining all 5 extension types (Tools, MCPs, Apps, Skills, Knowledge) with comparison table and decision guide - Rewrite Skills page with practical examples showing Skills + Tools patterns, common FAQ, and Skills vs Knowledge comparison - Add cross-reference callout on Tools page linking to the capabilities overview - Add agent-capabilities to Core Concepts navigation (after agents) * docs: add pt-BR and ko translations for agent-capabilities and updated skills/tools * docs: add Arabic (ar) translations for agent-capabilities and updated skills/tools
307 lines
12 KiB
Plaintext
307 lines
12 KiB
Plaintext
---
|
||
title: 스킬
|
||
description: 에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지.
|
||
icon: bolt
|
||
mode: "wide"
|
||
---
|
||
|
||
## 개요
|
||
|
||
스킬은 에이전트에게 **도메인별 지침, 가이드라인 및 참조 자료**를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다.
|
||
|
||
활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다.
|
||
|
||
<Note type="info" title="스킬 vs 도구 — 핵심 구분">
|
||
**스킬은 도구가 아닙니다.** 이것이 가장 흔한 혼동 포인트입니다.
|
||
|
||
- **스킬**은 에이전트의 프롬프트에 *지침과 컨텍스트*를 주입합니다. 에이전트에게 문제에 대해 *어떻게 생각할지*를 알려줍니다.
|
||
- **도구**는 에이전트에게 행동을 취할 수 있는 *호출 가능한 함수*를 제공합니다 (검색, 파일 읽기, API 호출).
|
||
|
||
흔히 **둘 다** 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다.
|
||
</Note>
|
||
|
||
---
|
||
|
||
## 빠른 시작
|
||
|
||
### 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]` |
|
||
|
||
**경험 법칙:** 에이전트가 *프로세스*를 따라야 하면 스킬을 사용하세요. 에이전트가 *데이터*를 참조해야 하면 지식을 사용하세요.
|
||
|
||
---
|
||
|
||
## 자주 묻는 질문
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="스킬과 도구를 모두 설정해야 하나요?">
|
||
사용 사례에 따라 다릅니다. 스킬과 도구는 **독립적**입니다 — 둘 중 하나, 둘 다, 또는 아무것도 사용하지 않을 수 있습니다.
|
||
|
||
- **스킬만**: 에이전트가 전문성은 필요하지만 외부 액션이 필요 없을 때 (예: 스타일 가이드라인으로 작성)
|
||
- **도구만**: 에이전트가 액션은 필요하지만 특별한 방법론이 필요 없을 때 (예: 간단한 웹 검색)
|
||
- **둘 다**: 에이전트가 전문성 AND 액션이 필요할 때 (예: 특정 체크리스트로 보안 감사 AND 코드 스캔 기능)
|
||
</Accordion>
|
||
|
||
<Accordion title="스킬이 자동으로 도구를 제공하나요?">
|
||
**아니요.** SKILL.md의 `allowed-tools` 필드는 실험적 메타데이터일 뿐 — 도구를 프로비저닝하거나 주입하지 않습니다. 항상 `tools=[]`, `mcps=[]` 또는 `apps=[]`를 통해 별도로 도구를 설정해야 합니다.
|
||
</Accordion>
|
||
|
||
<Accordion title="에이전트와 크루 모두에 같은 스킬을 설정하면 어떻게 되나요?">
|
||
에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다.
|
||
</Accordion>
|
||
|
||
<Accordion title="SKILL.md 본문의 최대 크기는 얼마인가요?">
|
||
50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다.
|
||
</Accordion>
|
||
</AccordionGroup>
|