Skills 개발 가이드

스킬 개발은 사용 사례 정의에서 시작하여, 카테고리 선택, 성공 기준 정의, 명령어 작성 순으로 진행한다.

사용 사례부터 시작하기

코드를 작성하기 전에 2-3가지 구체적인 사용 사례를 파악한다:

사용 사례: 프로젝트 스프린트 계획
트리거: "이 스프린트 계획 도와줘" 또는 "스프린트 작업 생성해줘"
단계:
1. Linear(MCP)에서 현재 프로젝트 상태 가져오기
2. 팀 속도 및 용량 분석
3. 작업 우선순위 제안
4. 적절한 레이블 및 추정치로 Linear에 작업 생성
결과: 작업이 생성된 완전한 스프린트

자문 체크리스트:

• 사용자가 무엇을 달성하고 싶어하나?
• 어떤 다단계 워크플로가 필요한가?
• 어떤 도구가 필요한가 (내장 또는 MCP)?
• 어떤 도메인 지식이나 모범 사례를 내장해야 하는가?

스킬 사용 사례 3대 카테고리

카테고리 1: 문서 및 자산 생성

일관되고 고품질 출력 생성 (문서, 프레젠테이션, 앱, 디자인, 코드).

핵심 기술:

• 내장된 스타일 가이드 및 브랜드 표준
• 일관된 출력을 위한 템플릿 구조
• 최종화 전 품질 체크리스트
• 외부 도구 불필요 — Claude 내장 기능 활용

예시: frontend-design 스킬 — 프로덕션 수준의 프론트엔드 인터페이스 생성.

카테고리 2: 워크플로 자동화

일관된 방법론의 다단계 프로세스, 여러 MCP 서버 간 조율 포함.

핵심 기술:

• 검증 게이트가 있는 단계별 워크플로
• 일반적인 구조를 위한 템플릿
• 내장된 검토 및 개선 제안
• 반복적 개선 루프

예시: skill-creator 스킬 — 새 스킬 생성을 위한 인터랙티브 가이드.

카테고리 3: MCP 강화

MCP 서버가 제공하는 도구 접근을 강화하기 위한 워크플로 안내.

핵심 기술:

• 여러 MCP 호출을 순서대로 조율
• 도메인 전문 지식 내장
• 사용자가 지정해야 하는 컨텍스트 제공
• 일반적인 MCP 문제에 대한 오류 처리

예시: sentry-code-review 스킬 — Sentry MCP로 PR 버그 분석 및 수정.

성공 기준 정의

정량적 지표

정성적 지표

• 사용자가 다음 단계를 프롬프트할 필요 없음
• 사용자 수정 없이 워크플로 완료
• 세션 간 일관된 결과

효과적인 명령어 작성

권장 구조

---
name: your-skill
description: [...]
---
 
# 스킬 이름
 
## 명령어
 
### 1단계: [첫 번째 주요 단계]
무슨 일이 일어나는지에 대한 명확한 설명.
 
## 예시
 
### 예시 1: [일반적인 시나리오]
사용자 요청 → 작업 단계 → 결과
 
## 트러블슈팅
 
**오류:** [일반적인 오류]
**원인:** [이유]
**해결:** [수정 방법]

모범 사례

구체적이고 실행 가능하게:

# 좋음
`python scripts/validate.py --input {filename}`을 실행하여 데이터 형식을 확인합니다.
유효성 검사에 실패하면:
- 필수 필드 누락 → CSV에 추가
- 잘못된 날짜 형식 → YYYY-MM-DD 사용
 
# 나쁨
계속하기 전에 데이터를 유효성 검사합니다.

오류 처리를 포함:

### MCP 연결 실패
"Connection refused"가 보이면:
1. MCP 서버 실행 확인: 설정 > 확장 프로그램
2. API 키 유효성 확인
3. 재연결 시도

점진적 공개 활용: SKILL.md는 핵심 명령어에 집중. 상세 문서는 references/로 이동 후 링크.

성능 메모 추가 (모델 “게으름” 방지):

## 성능 메모
- 속도보다 품질이 더 중요합니다
- 유효성 검사 단계를 건너뛰지 마세요

고급 기술: 중요한 유효성 검사는 scripts/에 코드로 번들링하는 것을 고려. 코드는 결정론적이고 언어 해석은 그렇지 않다.

Related

• Skills 개요 — 스킬 개념, 설계 원칙, 파일 구조
• Skills 테스트 — 트리거/기능/성능 테스트
• Skills 패턴 및 트러블슈팅 — 워크플로 패턴