스킬

에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지.

​

개요

스킬은 에이전트에게 도메인별 지침, 가이드라인 및 참조 자료를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 SKILL.md 파일로 정의됩니다.

활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다.

스킬은 도구가 아닙니다. 이것이 가장 흔한 혼동 포인트입니다.

• 스킬은 에이전트의 프롬프트에 지침과 컨텍스트를 주입합니다. 에이전트에게 문제에 대해 어떻게 생각할지를 알려줍니다.
• 도구는 에이전트에게 행동을 취할 수 있는 호출 가능한 함수를 제공합니다 (검색, 파일 읽기, API 호출).

흔히 둘 다 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다.

---

​

빠른 시작

​

1. 스킬 디렉터리 생성

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

​

2. 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"
---

## 코드 리뷰 가이드라인

코드를 리뷰할 때 이 체크리스트를 따르세요:

1. **보안**: 인젝션 취약점, 인증 우회, 데이터 노출 확인
2. **성능**: N+1 쿼리, 불필요한 할당, 블로킹 호출 확인
3. **가독성**: 명확한 네이밍, 적절한 주석, 일관된 스타일 보장
4. **테스트**: 새로운 기능에 대한 적절한 테스트 커버리지 확인

### 심각도 수준
- **크리티컬**: 보안 취약점, 데이터 손실 위험 → 머지 차단
- **메이저**: 성능 문제, 로직 오류 → 변경 요청
- **마이너**: 스타일 문제, 네이밍 제안 → 코멘트와 함께 승인

​

3. 에이전트에 연결

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: 스킬만 (도메인 전문성, 액션 불필요)

에이전트가 특정 지침이 필요하지만 외부 서비스를 호출할 필요가 없을 때 사용:

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: 스킬 + 도구 (전문성 AND 액션)

가장 일반적인 실제 패턴. 스킬은 작업에 어떻게 접근할지를 제공하고, 도구는 에이전트가 무엇을 할 수 있는지를 제공합니다:

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 서버와 함께 작동합니다:

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"],             # 이메일 전송 및 티켓 업데이트 가능
)

---

​

크루 레벨 스킬

스킬을 크루에 설정하여 모든 에이전트에 적용할 수 있습니다:

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: 이 스킬이 무엇을 하고 언제 사용하는지에 대한 간단한 설명.
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에서 사용할 수 있습니다.

---

​

사전 로드된 스킬

더 세밀한 제어를 위해 프로그래밍 방식으로 스킬을 검색하고 활성화할 수 있습니다:

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=[]를 통해 별도로 도구를 설정해야 합니다.

에이전트와 크루 모두에 같은 스킬을 설정하면 어떻게 되나요?

에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다.

SKILL.md 본문의 최대 크기는 얼마인가요?

50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다.