스킬 작성 가이드

SKILL.md 기본 구조

스킬 파일 템플릿

모든 스킬은 SKILL.md 파일을 기반으로 동작합니다. Frontmatter와 Markdown 본문으로 구성됩니다.

---
name: my-skill
description: 이 스킬이 무엇을 하는지 설명
---

# My Skill

## 사용 시점
이 스킬은 ... 할 때 사용합니다.

## 단계별 가이드
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

## 예시
구체적인 사용 예시를 여기에 작성합니다.
      

핵심 원칙

SKILL.md는 간결하게 유지하세요. Claude가 스킬을 로드할 때 토큰을 소비하므로, 상세 참조 문서는 references/ 디렉토리에 분리하는 것이 좋습니다.

핵심 패턴 3가지

1

Progressive Disclosure

SKILL.md에는 핵심 워크플로우만 담고, 세부 참조 자료는 별도 파일로 분리합니다.

Claude가 필요할 때만 references/ 파일을 읽어 토큰을 절약합니다.

# 디렉토리 구조
my-skill/
  SKILL.md              # 간결한 핵심
  references/
    detailed-guide.md   # 상세 참조
    templates.md        # 템플릿
  scripts/
    validate.sh         # 자동화
        

2

Persona 정의

Claude에게 전문가 역할을 부여하면 응답 품질이 크게 향상됩니다.

SKILL.md 상단에 역할을 명시하세요.

# Deploy Automation

You are a **Senior Infrastructure
Engineer** specializing in Docker,
Nginx, and cloud-native deployments.

## 사용 시점
...
        

3

$ARGUMENTS 전달

슬래시 커맨드에서 사용자 입력을 스킬에 전달합니다.

커맨드 파일(commands/*.md)에서 $ARGUMENTS를 참조합니다.

# commands/deploy.md
---
argument-hint: 서비스명
---

대상 서비스: $ARGUMENTS
배포를 시작합니다.

# 사용: /deploy gitea
# → $ARGUMENTS = "gitea"
        

Frontmatter 옵션

SKILL.md Frontmatter 필드

Frontmatter는 YAML 형식으로 스킬의 메타데이터를 정의합니다.

필드	설명	비고
`description`	스킬의 기능을 설명하는 키워드. Claude가 자동 매칭에 사용합니다.	필수
`argument-hint`	슬래시 커맨드에서 인자의 힌트를 표시합니다.	선택
`allowed-tools`	스킬 실행 시 사용할 수 있는 도구를 제한합니다.	선택
`disable-model-invocation`	`true`로 설정하면 자동 매칭을 비활성화하고 명시적 호출만 허용합니다.	선택

---
name: deploy
description: Docker 서비스 배포 자동화, Nginx, SSL, OpenBAO
argument-hint: 서비스명
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---
      

PR 절차

스킬 기여 워크플로우

새로운 스킬을 만들거나 기존 스킬을 수정할 때 아래 절차를 따릅니다.

1

idea 브랜치에서 작업

idea 브랜치를 생성하거나 체크아웃하여 작업을 시작합니다.

2

SKILL.md 작성 + 테스트

SKILL.md와 관련 파일을 작성하고 Claude Code에서 실제로 테스트합니다.

3

Merge Request 제출

GitLab에서 idea → main Merge Request를 생성합니다.

4

리뷰 후 main 병합

코드 리뷰를 거쳐 main 브랜치에 병합합니다.

참고 자료

example/ 디렉토리 참고

저장소의 example/ 디렉토리에 있는 deploy와 upgrade 스킬은 실제 운영 환경에서 사용되는 패턴의 예시입니다. 새로운 스킬을 작성할 때 구조와 패턴을 참고하세요.