Skills 시스템

Claude Code 스킬과 100% 호환되는 재사용 가능한 AI 전문성

CrewX Skills 시스템은 Claude Code 스킬 포맷과 100% 호환됩니다. 즉, 기존 Claude Code 스킬을 수정 없이 CrewX에서 바로 사용할 수 있습니다.

Skills란?

Skills는 재사용 가능한 AI 전문성을 패키징하는 표준 방식입니다:

Claude, Gemini, Copilot, Codex 모든 AI 제공자에서 동작
에이전트 간 공유 - 한 번 만들어 여러 에이전트에서 사용
Progressive Disclosure - 메타데이터 먼저 로드, 콘텐츠는 필요할 때만
버전 관리 및 독립 배포 가능

100% Claude Code 호환

CrewX는 Claude Code와 정확히 동일한 스킬 포맷을 사용합니다:

Same file structure - SKILL.md + YAML frontmatter
Same metadata fields - name, description, version, dependencies
Same content format - Markdown 콘텐츠
Zero modification - .claude/skills/에 있는 스킬을 바로 사용

즉: ✅ Claude Code 스킬 라이브러리 사용 가능 ✅ Claude Code와 CrewX 간 스킬 공유 ✅ 양쪽 환경에서 동일하게 작동

빠른 시작

1. Skill 생성

skills/hello/SKILL.md 파일 생성:

---
name: hello
description: CrewX 스킬 파이프라인 검증용 인사 데모 스킬
version: 0.0.1
---

# Hello Skill

CrewX 스킬 로딩이 정상 작동하는지 확인하거나 친절한 인사가 필요할 때 사용하세요.

## 기능
- hello 스킬의 작동 방식과 스크립트 위치 설명 (`skills/hello/hello.js`)
- 선택적으로 스크립트를 실행하여 인사말 생성
- 응답에 CrewX hello skill이 작동했음을 명시하여 테스터가 확인 가능

## 사용법
1. 빠른 인사가 필요하면 다음을 실행:
   ```bash
   node skills/hello/hello.js <name>

name 인자는 선택사항이며 기본값은 "CrewX user" 2. 스크립트 출력을 응답에 인용하여 사용자가 결과를 볼 수 있도록 함 3. 추가 설명을 덧붙이되 짧고 친절하게 유지

응답 템플릿

이 스킬로 응답할 때 다음을 포함:

Hello, <name>! This message is generated by the CrewX hello skill script.
<name>을 대상 이름 또는 미지정 시 "CrewX user"로 대체
선택적으로 스크립트 재실행 방법 안내

이 가벼운 스킬은 검증용이므로 간결하고 친절하게 유지.

### 2. crewx.yaml에 설정

```yaml
# 프로젝트 전체 스킬 설정
skills:
  paths:
    - ./skills              # 커스텀 스킬 디렉토리
    - ./company-skills      # 팀 공유 스킬
  # 기본적으로 ALL 스킬이 자동 로드 (autoload: true가 기본값)
  # 'include' 또는 'exclude'로 로드할 스킬 제어:

  # 옵션 1: 명시적으로 특정 스킬만 포함 (autoload 무시)
  include:
    - hello
    - code-reviewer

  # 옵션 2: 이것들을 제외한 모든 스킬 자동 로드 (autoload와 함께)
  exclude:
    - deprecated-skill
    - experimental-skill

  # 옵션 3: 자동 로드 완전히 비활성화 (include에 있는 것만 로드)
  autoload: false

# 특정 에이전트에 스킬 추가
agents:
  - id: "senior_dev"
    provider: "cli/claude"
    skills:
      include:
        - code-reviewer
        - api-designer
    inline:
      prompt: |
        You are a senior developer with specialized skills.

3. Skill 테스트

# Claude로 테스트
crewx query "@senior_dev review this code"

# 여러 제공자에서 테스트
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_claude test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_gemini test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_copilot test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_codex test hello skill"

Skill 메타데이터

필수 필드

---
name: skill-name          # Kebab-case 식별자
description: Brief desc   # 10-200자 설명
version: 1.0.0           # Semantic versioning
---

선택 필드

---
name: advanced-skill
description: Advanced skill with dependencies
version: 2.1.0
dependencies:              # 이 스킬이 필요로 하는 다른 스킬들
  - base-skill
  - helper-skill
runtime:                   # 런타임 요구사항
  node: ">=18.0.0"
  python: ">=3.9"
visibility: public         # public | private | internal
---

Skills 설정

프로젝트 레벨 설정

skills:
  paths:
    - ./skills            # 주 스킬 디렉토리
    - ./team-skills       # 공유 팀 스킬
    - ../common-skills    # 조직 전체 스킬

  # 기본적으로 autoload는 TRUE - paths의 모든 스킬 로드
  # 로드할 스킬을 제어하는 3가지 옵션:

  # 옵션 1: 모든 스킬 로드 (기본 동작, 설정 불필요)
  # 그냥 paths만 지정하면 autoload가 true로 기본값

  # 옵션 2: 특정 스킬만 로드 (토큰 사용량 최소화)
  include:
    - skill-one
    - skill-two
  # 'include'가 지정되면 이 스킬들만 로드 (autoload 무시)

  # 옵션 3: 특정 스킬 제외하고 모두 로드
  exclude:
    - deprecated-skill
    - experimental-skill
  # autoload: true(기본값)와 함께 작동, 특정 스킬 제외

  # 옵션 4: 모든 자동 로딩 비활성화
  autoload: false
  # 'include'에 있는 스킬만 로드 (있는 경우)

설정 우선순위:

include 설정 → 해당 스킬만 로드 (가장 효율적)
exclude 설정 → 제외된 것 빼고 모두 로드
둘 다 없음 → 모든 스킬 로드 (기본값: autoload: true)
autoload: false이고 include 없음 → 아무것도 로드 안 함

에이전트 레벨 설정

각 에이전트는 자체 스킬 설정 가능:

agents:
  - id: "code_reviewer"
    provider: "cli/claude"
    skills:
      include:            # 에이전트 전용 스킬
        - code-review
        - security-audit
        - performance-check

Progressive Disclosure

CrewX는 성능을 위해 progressive skill loading 구현:

메타데이터 로딩 (빠름)
- YAML frontmatter만 로드
- 에이전트는 스킬 name, description, version 확인
- 에이전트 초기화 시 발생
콘텐츠 로딩 (필요할 때)
- 전체 markdown 콘텐츠는 필요할 때만 로드
- 에이전트가 사용할 때 스킬 세부사항 읽음
- 메모리 사용량 감소

// SDK 예제: Progressive loading
const skill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: false,      // 메타데이터만
  validationMode: 'lenient'
});

// skill.metadata는 사용 가능
// skill.content는 undefined (필요할 때 로드)

다중 제공자 테스트

CrewX는 모든 AI 제공자에서 스킬이 작동하는지 확인하는 전용 테스트 설정 제공:

파일: crewx.skills.yaml

skills:
  paths:
    - ./skills
  include:
    - hello

agents:
  - id: "skill_tester_claude"
    provider: "cli/claude"
    skills:
      include: [hello]

  - id: "skill_tester_gemini"
    provider: "cli/gemini"
    skills:
      include: [hello]

  - id: "skill_tester_copilot"
    provider: "cli/copilot"
    skills:
      include: [hello]

  - id: "skill_tester_codex"
    provider: "cli/codex"
    options:
      query: ["exec", "--experimental-json"]
    skills:
      include: [hello]

사용법:

# 특정 제공자로 테스트
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_claude test the hello skill"

# 모든 제공자를 병렬로 테스트
CREWX_CONFIG=crewx.skills.yaml crewx query \
  "@skill_tester_claude @skill_tester_gemini @skill_tester_copilot @skill_tester_codex \
  verify hello skill works"

Skill 디렉토리 구조

권장 구조:

project/
├── skills/                      # 프로젝트 스킬
│   ├── hello/
│   │   ├── SKILL.md            # Skill manifest
│   │   └── hello.js            # 선택: 지원 스크립트
│   ├── code-reviewer/
│   │   ├── SKILL.md
│   │   └── templates/          # 선택: 템플릿
│   │       └── review.md
│   └── api-designer/
│       └── SKILL.md
├── .claude/                     # Claude Code 스킬
│   └── skills/
│       └── crewx/
│           └── SKILL.md         # Claude Code & CrewX 양쪽에서 작동
├── crewx.yaml                   # 메인 설정
└── crewx.skills.yaml           # 스킬 테스트 설정

모범 사례

1. Skill 디자인

스킬을 집중적으로 유지:

# ✅ 좋음: 집중된 스킬
name: code-reviewer
description: 버그, 스타일, 모범 사례에 대한 코드 리뷰

# ❌ 나쁨: 너무 광범위
name: do-everything
description: 모든 개발 작업 처리

명확하게 문서화:

## 사용법
1. 먼저 코드 파일 읽기
2. 다음 분석: [구체적 기준]
3. 제공: [구체적 출력 형식]

## 응답 템플릿
[에이전트가 따라야 할 정확한 형식 표시]

2. 버전 관리

Semantic versioning 사용:

Major (1.0.0 → 2.0.0): 스킬 인터페이스의 주요 변경
Minor (1.0.0 → 1.1.0): 새 기능, 하위 호환
Patch (1.0.0 → 1.0.1): 버그 수정, 명확화

3. Skill 의존성

의존성을 명시적으로 선언:

---
name: api-tester
version: 1.0.0
dependencies:
  - api-designer    # API 디자인 패턴 필요
  - validator       # 검증 규칙 필요
---

4. 테스트 전략

배포 전 제공자 간 스킬 테스트:

# 1. 스킬 생성
vim skills/new-skill/SKILL.md

# 2. 테스트 설정에 추가
vim crewx.skills.yaml

# 3. 모든 제공자 테스트
CREWX_CONFIG=crewx.skills.yaml crewx query \
  "@skill_tester_claude @skill_tester_gemini test new-skill"

# 4. 프로덕션 설정에 배포
vim crewx.yaml

Claude Code와의 통합

환경 간 Skill 공유

시나리오: Claude Code IDE와 CrewX CLI에서 동일한 스킬 사용

# 디렉토리 구조
project/
├── .claude/skills/          # Claude Code가 여기서 읽음
│   └── shared/
│       └── SKILL.md
├── skills/                  # CrewX가 여기서 읽음
│   └── shared -> ../.claude/skills/shared  # Symlink
└── crewx.yaml

# CrewX 설정
skills:
  paths:
    - ./skills
    - ./.claude/skills       # Claude Code 스킬도 검색

결과: 하나의 스킬, Claude Code와 CrewX 양쪽에서 작동

Claude Code에서 마이그레이션

제로 노력 마이그레이션:

이미 .claude/skills/에 스킬이 있나요? 즉시 작동합니다:

# crewx.yaml
skills:
  paths:
    - ./.claude/skills       # Claude Code 스킬을 그대로 사용

분리하고 싶나요? ./skills/로 복사:

cp -r .claude/skills/* skills/

포맷 변경 불필요 - CrewX는 동일한 포맷 사용

고급: Skill Runtime (SDK)

CrewX 기반 개발자를 위한:

import {
  parseSkillManifestFromFile,
  SkillParserOptions
} from '@sowonai/crewx-sdk';

// 스킬 메타데이터만 로드 (빠름)
const skill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: false,
  validationMode: 'lenient'
});

console.log(skill.metadata.name);        // 'hello'
console.log(skill.metadata.description); // 'Simple greeting...'
console.log(skill.content);              // undefined (로드 안됨)

// 필요할 때 전체 콘텐츠 로드
const fullSkill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: true,
  validationMode: 'strict',
  resolveDependencies: true
});

console.log(fullSkill.content.raw);      // 전체 markdown 콘텐츠

문제 해결

Skill이 로드되지 않음

# 스킬을 찾았는지 확인
crewx agent info @your_agent

# 디버그 로깅 활성화
LOG_LEVEL=debug crewx query "@your_agent test"

# 스킬 파일 형식 확인
cat skills/your-skill/SKILL.md

일반적인 문제:

YAML frontmatter 누락 (--- 구분자)
잘못된 스킬 이름 (kebab-case 사용: my-skill)
설정된 경로에 파일이 없음
에이전트 설정에 스킬이 포함되지 않음

Skill 버전 충돌

여러 버전이 존재할 때:

skills:
  paths:
    - ./skills/v2        # 먼저 검색
    - ./skills/v1        # 대체

CrewX는 첫 번째 일치 사용 - 경로 순서를 적절히 정렬

제공자 간 호환성

일부 기능은 제공자마다 다르게 작동:

기능	Claude	Gemini	Copilot	Codex
파일 읽기	✅	✅	✅	✅
스크립트 실행	⚠️ 승인 필요	⚠️ 승인 필요	⚠️ 승인 필요	✅ `exec`와 함께
도구 사용	✅	✅	✅	✅

최대 호환성을 위해 읽기 전용 작업으로 스킬 디자인

예제

작동하는 예제 참고:

skills/hello/ - 기본 스킬 템플릿
.claude/skills/crewx/ - CrewX 전문가 스킬
crewx.skills.yaml - 다중 제공자 테스트 설정

스키마 참고

전체 스키마: packages/sdk/schema/skills-config.json

TypeScript 타입: packages/sdk/src/schema/skills.types.ts

질문? CLI 가이드를 확인하거나 GitHub에 이슈를 열어주세요.

Skills란?​

100% Claude Code 호환​

빠른 시작​

1. Skill 생성​

응답 템플릿​

3. Skill 테스트​

Skill 메타데이터​

필수 필드​

선택 필드​

Skills 설정​

프로젝트 레벨 설정​

에이전트 레벨 설정​

Progressive Disclosure​

다중 제공자 테스트​

Skill 디렉토리 구조​

모범 사례​

1. Skill 디자인​

2. 버전 관리​

3. Skill 의존성​

4. 테스트 전략​

Claude Code와의 통합​

환경 간 Skill 공유​

Claude Code에서 마이그레이션​

고급: Skill Runtime (SDK)​

문제 해결​

Skill이 로드되지 않음​

Skill 버전 충돌​

제공자 간 호환성​

예제​

스키마 참고​