콘텐츠로 이동

스킬 (Skills)

스킬이 뭔가요?

에이전트한테 "이번 작업은 이렇게 진행해 주세요" 같은 도메인별 지침을 넣고 싶을 때가 있어요. 크루AI(CrewAI)에서는 그 지침을 코드 안에 하드코딩하는 대신, 스킬(Skill)이라는 별도의 폴더로 만들어 관리해요.

스킬은 에이전트가 쓸 도메인 특화 지침·가이드라인·참고 자료를 담은 자기 완결적인 디렉터리예요. 각 스킬은 YAML 프런트매터(frontmatter)와 마크다운 본문으로 이루어진 SKILL.md 파일 하나로 정의돼요. 스킬이 활성화되면 그 지침이 바로 에이전트의 태스크 프롬프트에 주입되어요. 코드를 고칠 필요 없이 에이전트에게 전문성을 더해 주는 거죠.

빠르게 시작해 볼게요

세 단계로 나눠서 볼게요.

1단계: 스킬 디렉터리 만들기

스킬 하나를 담을 폴더를 만들면 돼요. SKILL.md만 있으면 동작하고, 나머지는 선택이에요:

skills/
└── code-review/
    ├── SKILL.md            # 필수 — 지침 본문
    ├── references/         # 선택 — 참고 문서
    │   └── style-guide.md
    └── scripts/            # 선택 — 실행 가능한 스크립트

code-review라는 스킬 폴더 안에 지침 파일(SKILL.md), 참고 문서(references/), 스크립트(scripts/)를 나눠 담은 구조예요.

2단계: SKILL.md 작성하기

SKILL.md는 앞부분에 메타데이터(프런트매터)를, 그다음에 지침 본문을 써요:

---
name: code-review
description: Guidelines for conducting thorough code reviews with focus on security and performance.
metadata:
  author: your-team
  version: "1.0"
---

## Code Review Guidelines

When reviewing code, follow this checklist:
1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure
2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls
3. **Readability**: Ensure clear naming, appropriate comments, and consistent style
4. **Testing**: Verify adequate test coverage for new functionality

### Severity Levels
- **Critical**: Security vulnerabilities, data loss risks → block merge
- **Major**: Performance issues, logic errors → request changes
- **Minor**: Style issues, naming suggestions → approve with comments

---로 감싼 부분이 프런트매터고, 여기 있는 name과 description이 스킬을 식별·설명해요. 그 아래 오는 마크다운 본문이 스킬이 활성화될 때 에이전트 프롬프트에 주입되는 실제 지침이에요. 위 예시에서 지침은 코드 리뷰 체크리스트와 심각도(severity)별 처리 방식을 담고 있죠.

3단계: 에이전트에 연결하기

만든 스킬을 에이전트에게 주려면 Agent를 만들 때 skills 인자에 경로를 넘겨요:

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()],  # 코드를 읽게 하는 도구
)

이렇게 하면 에이전트는 스킬 덕분에 전문성(expertise)을, 도구 덕분에 실행 능력(capabilities)을 둘 다 갖춰요. 스킬은 "어떻게 접근할지"를, 도구는 "뭘 할 수 있는지"를 담당해요.

스킬과 도구가 함께 쓰이는 패턴들

스킬과 도구는 서로를 보완해요. 자주 나오는 조합을 패턴별로 볼게요.

패턴 1: 스킬만 쓰기 (도메인 전문성만, 외부 동작 불필요)

에이전트가 구체적인 지침을 필요로 하는데 외부 서비스를 호출할 필요는 없을 때 쓰는 패턴이에요. 예를 들면 문서 작성 규칙 같은 거요:

agent = Agent(
    role="Technical Writer",
    goal="Write clear API documentation",
    backstory="Expert technical writer",
    skills=["./skills/api-docs-style"],  # 작성 규칙과 템플릿
    # 도구 없음 — 주어진 문맥만으로 글을 씀
)

패턴 2: 도구만 쓰기 (실행만, 특별한 전문성 불필요)

반대로 행동은 해야 하는데 도메인 특화 지침이 필요 없을 때는 도구만 넣으면 돼요. 일반적인 웹 검색 같은 작업이 여기 해당해요:

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: 스킬 + 도구 (전문성과 실행 모두)

가장 실무에서 자주 보이는 조합이에요. 스킬이 "작업에 어떻게 접근할지"를 정해 주고, 도구가 "에이전트가 실행할 수 있는 것"을 정해줘요:

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 서버와도 도구 때와 똑같이 협력해요. 방법론은 스킬로, 원격 데이터 접근은 MCP로 나누는 구조예요:

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: 스킬 + 앱

스킬은 플랫폼 통합 기능을 어떻게 쓸지도 안내할 수 있어요. 에이전트가 이메일을 보내거나 티켓을 업데이트할 수 있는 앱과 함께 스킬로 대응 템플릿·승격 규칙을 주는 식이에요:

agent = Agent(
    role="Customer Support Agent",
    goal="Respond to customer inquiries professionally",
    backstory="Experienced support representative",
    skills=["./skills/support-playbook"],  # 응답 템플릿·승격 규칙
    apps=["gmail", "zendesk"],             # 이메일 전송·티켓 업데이트 가능
)

크루 레벨 스킬

스킬은 에이전트뿐 아니라 크루(Crew) 레벨에도 설정할 수 있어요. 크루에 넣으면 그 크루의 모든 에이전트에 적용돼요:

from crewai import Crew

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    skills=["./skills"],   # 모든 에이전트가 이 스킬 사용
)

이때 주의할 점이 하나 있어요. 같은 스킬이 에이전트 레벨과 크루 레벨 양쪽에 있으면 에이전트 레벨의 스킬이 우선해요. 즉 에이전트가 자기만의 버전을 갖고 있으면 그게 쓰여요.

SKILL.md 형식 자세히 보기

앞서 예시로 본 형식을 프런트매터 항목까지 정리하면 이렇게 돼요:

---
name: my-skill
description: Short description of what this skill does and when to use it.
license: Apache-2.0            # 선택
compatibility: crewai>=0.1.0   # 선택
metadata:                      # 선택
  author: your-name
  version: "1.0"
allowed-tools: web-search file-read   # 선택, 실험적
---

Instructions for the agent go here.
This markdown body is injected into the agent's prompt when the skill is activated.

--- 안의 프런트매터가 스킬의 메타데이터를, --- 아래 본문이 실제로 에이전트 프롬프트에 주입되는 지침을 담아요.

프런트매터 필드

필드 필수 설명
name 예 1–64자. 소문자 영숫자와 하이픈(-)만. 디렉터리 이름과 일치해야 해요.
description 예 1–1024자. 스킬이 무엇을 하고 언제 쓰는지 설명.
license 아니요 라이선스 이름 또는 번들된 라이선스 파일 참조.
compatibility 아니요 최대 500자. 환경 요구사항(제품·패키지·네트워크).
metadata 아니요 임의의 문자열 키-값 매핑.
allowed-tools 아니요 사전 승인된 도구를 공백으로 구분한 목록. 실험적(experimental).

디렉터리 구조

스킬 디렉터리는 이렇게 SKILL.md 하나와 선택적인 하위 폴더들로 이뤄져요:

my-skill/
├── SKILL.md       # 필수 — 프런트매터 + 지침
├── scripts/       # 선택 — 실행 가능한 스크립트
├── references/    # 선택 — 참고 문서
└── assets/        # 선택 — 정적 파일 (설정·데이터)

디렉터리 이름은 SKILL.md의 name 필드와 일치해야 해요. scripts/, references/, assets/ 디렉터리는 스킬의 path 아래에 있어서, 파일을 직접 참조해야 하는 에이전트가 쓸 수 있어요.

스킬 미리 불러오기 (Pre-loading)

지금까지는 경로를 넘기면 자동으로 처리됐는데요, 더 세밀하게 제어하고 싶으면 스킬을 프로그래밍 방식으로 발견(discover)하고 활성화(activate)할 수 있어요:

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()가 스킬의 요약 정보를 잡아내고, activate_skill()이 본문까지 로드한 뒤, 그 결과물을 에이전트의 skills에 넘기는 흐름이에요.

스킬이 로드되는 방식

스킬은 점진적 공개(progressive disclosure) 방식을 써요. 즉 필요한 단계에서 필요한 것만 로드해요:

단계 로드되는 것 시점
발견 (Discovery) 이름·설명·프런트매터 필드 discover_skills()
활성화 (Activation) SKILL.md 본문 전체 activate_skill()

보통 실행에서는 skills=["./skills"]처럼 디렉터리 경로를 넘기면 스킬이 자동으로 발견·활성화되요. 이 점진적 로딩은 프로그래밍 API를 쓸 때만 의미가 있어요.

스킬 vs 지식 (Knowledge)

둘 다 에이전트의 프롬프트를 바꾸지만 역할이 달라요. 헷갈리기 쉬우니 표로 정리할게요:

측면 스킬 (Skills) 지식 (Knowledge)
제공하는 것 지침·절차·가이드라인 사실·데이터·정보
저장 방식 마크다운 파일 (SKILL.md) 벡터 스토어에 임베딩 (ChromaDB)
조회 방식 본문 전체를 프롬프트에 주입 시맨틱 검색으로 관련 청크 조회
어울리는 용도 방법론·체크리스트·스타일 가이드 회사 문서·제품 정보·참고 데이터
설정 위치 skills=["./skills"] knowledge_sources=[source]

체감 규칙 하나만 기억하면 돼요. 에이전트가 절차(process)를 따라야 한다면 스킬, 데이터(data)를 참조해야 한다면 지식을 써요.

더 알아보기