DEV Community

Cover image for 자동 스킬 크리에이터로 Claude 코드 스킬 자동 생성 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

자동 스킬 크리에이터로 Claude 코드 스킬 자동 생성 방법

#ai #automation #llm #tutorial

요약

Claude 코드 스킬은 특정 워크플로를 위해 Claude의 기능을 확장하는 사용자 정의 기능입니다. 스킬 생성기 시스템은 구조화된 프로세스를 통해 스킬을 자동화 및 반복적으로 개선합니다. 즉, 목표 정의, SKILL.md 초안, 테스트 케이스 작성, 정량적 벤치마크 평가, 피드백 기반 개선을 체계적으로 실행합니다.

지금 Apidog을 사용해보세요

💡 API 관련 스킬을 구축한다면 Apidog와의 통합이 자연스럽게 이뤄집니다. 단일 스킬 워크플로 내에서 API 엔드포인트 테스트/응답 검증/문서화를 모두 처리할 수 있습니다.

Claude 코드 스킬이란?

Claude 코드 스킬은 특정 도메인 또는 워크플로에 맞춰 Claude의 기능을 확장하는 마크다운 기반 사용자 정의 플러그인입니다.

스킬 시스템 아키텍처

스킬은 3단계 로딩 구조를 가집니다.

  1. 메타데이터: 이름/설명(항상 컨텍스트에 포함)
  2. SKILL.md 본문: 핵심 지시사항(트리거 시 로드)
  3. 번들 리소스: 스크립트, 참조, 자산(필요할 때 로드) 
skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter (이름, 설명)
│   └── 마크다운 지시사항
└── 번들 리소스 (선택)
    ├── scripts/
    ├── references/
    └── assets/
Enter fullscreen mode Exit fullscreen mode

스킬 트리거 시점

스킬은 available_skills 목록에 이름/설명과 함께 등록됩니다. Claude는 설명을 기반으로 트리거 여부를 결정합니다.

  • 복잡한 워크플로: 설명이 정확히 맞는 경우 트리거됨
  • 간단한 작업: Claude가 직접 할 수 있으면 트리거되지 않음

Anthropic 저장소 예시

스킬 목적 주요 기능
skill-creator 새로운 스킬 생성 테스트 케이스 생성, 벤치마크 평가, 설명 최적화
mcp-builder MCP 서버 구축 Python/Node 템플릿, 평가 프레임워크, 모범 사례
docx Word 문서 생성 python-docx, 템플릿, 스타일 가이드
pdf PDF 추출/조작 양식 처리, 텍스트 추출, 참조 문서
frontend-design 웹 인터페이스 구축 컴포넌트 라이브러리, Tailwind, 접근성 검사

스킬 생성 워크플로

스킬 자동화는 다음 절차를 따릅니다.

  1. 의도 포착 – 스킬의 목표 정의
  2. SKILL.md 초안 – 핵심 지시사항 작성
  3. 테스트 케이스 생성 – 현실적 프롬프트 설계
  4. 평가 실행 – 스킬/비스킬 병렬 실행
  5. 결과 검토 – 피드백 + 벤치마크 집계
  6. 반복 – 개선 및 재평가
  7. 설명 최적화 – 트리거 정확도 향상
  8. 패키징 – .skill 파일로 배포

각 단계별로 실무 적용법을 살펴봅니다.

1단계: 의도 포착

이미 하고 있는 워크플로(대화 기록 포함)에서 패턴을 추출하고 아래 질문으로 정의합니다.

  • 무엇을 할 수 있어야 하는가? (결과를 구체적으로)
  • 언제 트리거되어야 하는가? (사용자 문구/컨텍스트)
  • 예상 출력 형식은? (파일, 코드, 리포트 등)
  • 테스트 케이스 필요? (객관적 출력이라면 필수)

예시: API 테스트 스킬

의도: 개발자가 REST API를 체계적으로 테스트
트리거: API 테스트, 엔드포인트, REST, GraphQL 언급 시
출력: 통과/실패 상태, curl 명령, 응답 비교가 포함된 보고서
테스트 케이스: 필요 (객관적 검증 가능)
Enter fullscreen mode Exit fullscreen mode

2단계: SKILL.md 파일 작성

모든 스킬은 YAML frontmatter + 마크다운 지시사항으로 구성된 SKILL.md로 시작합니다.

구성 예시:

---
name: api-tester
description: REST API를 체계적으로 테스트하는 방법. 사용자가 API 테스트, 엔드포인트, REST, GraphQL을 언급하거나 API 응답을 검증하고자 할 때 사용합니다. 테스트가 관련될 때마다 이 스킬을 제안해야 합니다.
compatibility: curl 또는 HTTP 클라이언트 도구 필요
---

# API 테스터 스킬

## 핵심 워크플로

API를 테스트할 때는 다음 단계를 따릅니다:
1. **엔드포인트 이해** – 사양 확인
2. **테스트 케이스 설계** – 해피 패스/엣지/오류
3. **테스트 실행** – curl 또는 Apidog 사용
4. **응답 검증** – 코드/헤더/본문 구조 체크
5. **결과 보고** – 통과/실패 요약

## 출력 형식

# API 테스트 보고서

## 요약
- 실행된 테스트: X
- 통과: Y
- 실패: Z

## 실패한 테스트
### 테스트 이름
**예상:** 200 OK
**실제:** 400 Bad Request
**응답:** {...}
Enter fullscreen mode Exit fullscreen mode

모범 사례

  • SKILL.md는 500줄 이하로 유지
  • 규칙의 이유 설명 추가
  • 명령형 문장 활용
  • 예시 포함

3단계: 테스트 케이스 생성

evals/evals.json에 2~3개의 현실적인 테스트 프롬프트를 작성합니다.

예시:

{
  "skill_name": "api-tester",
  "evals": [
    {
      "id": 1,
      "prompt": "api.example.com의 /users 엔드포인트를 테스트합니다 - Bearer 토큰이 필요하며 id, name, email 필드를 가진 사용자 목록을 반환합니다",
      "expected_output": "인증 실패, 성공, 페이지네이션 테스트를 포함한 최소 5개의 테스트 케이스가 있는 테스트 보고서",
      "files": []
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

좋은 테스트 프롬프트의 조건

  • 구체적 URL/시나리오/예상 동작/실제 컨텍스트 포함

4단계: 평가 실행

각 테스트 케이스를 스킬 사용/미사용 두 가지로 병렬 실행합니다.

  • 결과는 <skill-name>-workspace/iteration-1/에 저장
  • 실행별로 outputs/, timing.json 등 산출

타이밍 데이터 예시

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
Enter fullscreen mode Exit fullscreen mode

5단계: 실행 완료 중 어설션 초안 작성

실행 대기 중 정량적 어설션을 만듭니다.

예시:

{
  "assertions": [
    {
      "name": "includes_auth_failure_test",
      "description": "테스트 보고서에 최소 하나의 인증 실패 테스트 케이스가 포함되어 있습니다",
      "type": "contains",
      "value": "401"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

작성 후 eval_metadata.json, evals/evals.json에 반영

6단계: 채점 및 집계

  • 채점 서브 에이전트가 grading.json에 assert별 통과여부 저장
  • 집계 스크립트로 pass_rate, 시간, 토큰 사용량 포함 benchmark.json/benchmark.md 생성

벤치마크 집계

python -m scripts.aggregate_benchmark api-tester-workspace/iteration-1 --skill-name api-tester
Enter fullscreen mode Exit fullscreen mode

7단계: 평가 뷰어 실행

  • 브라우저 UI에서 프롬프트/출력/피드백/벤치마크를 한눈에 확인
  • 협업/헤드리스 환경에서는 --static 옵션으로 독립형 HTML 생성

실행 예시

nohup python /path/to/skill-creator/eval-viewer/generate_review.py \
  api-tester-workspace/iteration-1 \
  --skill-name "api-tester" \
  --benchmark api-tester-workspace/iteration-1/benchmark.json \
  > /dev/null 2>&1 &
Enter fullscreen mode Exit fullscreen mode

8단계: 피드백 읽기 및 반복

피드백(feedback.json)을 읽고, 빈 피드백은 문제없음을 의미. 반복 개선.

개선 포인트

  • 개별 테스트 케이스에 과적합하지 말 것
  • 프롬프트 및 스크립트 간결화
  • 이유 중심 설명
  • 반복되는 코드/스크립트는 번들링

반복 루프

  1. 개선 반영
  2. iteration-N+1로 재실행
  3. 새 피드백 수집/반영
  4. 만족할 때까지 반복

9단계: 스킬 설명 최적화

  • SKILL.md의 description이 트리거 정확도에 결정적
  • 20개 트리거/비트리거 평가 쿼리 작성 → 최적화 루프 실행

트리거 평가/최적화 예시

python -m scripts.run_loop \
  --eval-set /path/to/trigger-eval.json \
  --skill-path /path/to/api-tester \
  --model claude-sonnet-4-6 \
  --max-iterations 5 \
  --verbose
Enter fullscreen mode Exit fullscreen mode
  • best_description을 frontmatter에 반영

10단계: 패키징 및 배포

패키징

python -m scripts.package_skill /path/to/api-tester
Enter fullscreen mode Exit fullscreen mode
  • .skill 파일 생성 후 안내

설치

  • .skill 파일을 스킬 디렉토리에 배치 또는 설치 명령 사용

일반적인 스킬 생성 오류

오류 1: 모호한 설명 

# 나쁜 예시
description: API 작업을 위한 스킬
# 좋은 예시
description: REST API를 체계적으로 테스트하는 방법. 사용자가 API 테스트, 엔드포인트, REST, GraphQL을 언급하거나 API 응답을 검증하고자 할 때 사용합니다. '테스트'를 명시적으로 언급하지 않더라도 테스트가 관련될 때마다 이 스킬을 제안해야 합니다.
Enter fullscreen mode Exit fullscreen mode

오류 2: 지나치게 제한적인 지시사항 

# 나쁜 예시
항상 이 정확한 형식을 사용하십시오. 절대로 벗어나지 마십시오.
# 좋은 예시
이 형식을 사용하면 이해 관계자들이 필요한 정보를 신속하게 찾을 수 있습니다. 청중의 요구 사항이 다를 경우 구조를 조정하십시오.
Enter fullscreen mode Exit fullscreen mode

오류 3: 테스트 케이스 생략

  • 주관적 스킬이라도 2~3개 예시로 품질 검증

오류 4: 타이밍 데이터 무시

  • 품질뿐 아니라 실행 효율성 필수 체크

오류 5: 반복 스크립트 번들링 안 함

  • 반복 스크립트는 /scripts/에 묶어 재사용

실제 스킬 예시

MCP 빌더 스킬

  • 용도: MCP 서버 구축 자동화

  • 구성

    mcp-builder/
├── SKILL.md
├── reference/
│   ├── mcp_best_practices.md
│   ├── python_mcp_server.md
│   └── node_mcp_server.md
└── evaluation/
    └── evaluation.md

Docx 스킬

  • 용도: Word 문서 자동 생성
  • 워크플로
    1. 요구사항 파악
    2. 템플릿 선택/생성
    3. python-docx로 생성
    4. 출력 검증

프론트엔드 디자인 스킬

  • 용도: 웹 UI 현대화
  • 구성: 핵심 워크플로는 SKILL.md, 컴포넌트 문서는 references/

Apidog로 스킬 테스트

API 관련 스킬에는 Apidog 통합이 효과적입니다.

API 테스트

예시: API 테스트 스킬 통합

## API 테스트 실행

체계적인 테스트를 위해 Apidog를 사용합니다:

1. OpenAPI 사양을 Apidog로 가져오기
2. 사양에서 테스트 케이스 생성
3. 테스트 실행 및 결과를 JSON으로 내보내기
4. 예상 스키마에 대해 응답 검증

사용자 정의 어설션의 경우 Apidog의 스크립팅 기능을 사용합니다.
Enter fullscreen mode Exit fullscreen mode

스크립트 번들링 예시

api-tester/
├── SKILL.md
└── scripts/
    ├── run-apidog-tests.py
    └── generate-report.py
Enter fullscreen mode Exit fullscreen mode

결론

Claude 코드 스킬은 개발자의 반복 워크플로를 자동화하는 강력한 도구입니다. 다음 절차를 참고하여 스킬을 체계적이고 반복적으로 개선하세요.

  1. 의도 포착
  2. SKILL.md 초안 작성
  3. 테스트 케이스 작성
  4. 병렬 평가 실행
  5. 피드백 및 벤치마크 분석
  6. 반복 개선
  7. 설명 최적화
  8. 패키징 및 배포

FAQ

스킬을 만드는 데 얼마나 걸리나요?

간단한 스킬: 15~30분, 복잡한 스킬 및 평가 반복: 2~3시간

모든 스킬에 테스트 케이스가 필요하나요?

객관적 출력(코드, 파일, 데이터 변환) 스킬: 필수

주관적 출력(글쓰기, 디자인): 정성 평가 권장

스킬이 안정적으로 트리거되지 않는다면?

설명 필드를 구체적으로 최적화하고, 트리거/비트리거 평가 쿼리 20개로 반복 개선

팀과 스킬을 어떻게 공유하나요?

.skill 파일 배포 → 팀원은 스킬 디렉토리에 복사

스킬이 외부 API를 호출할 수 있나요?

가능. API 호출 스크립트를 번들로 포함하고, 키는 환경변수에 저장

파일 크기 제한은?

SKILL.md는 500줄 이하 권장. 참조/스크립트/자산 파일은 별도 관리(줄 수 제한 없음)

기존 스킬 업데이트 방법은?

설치 경로에 복사 후 편집/재패키징. 이름은 유지, 변형시만 버전 추가

실무 자동화와 API 테스트를 빠르게 시작하려면 Apidog도 함께 활용해보세요.

Top comments (0)