---
title: "@힣: skill-creator - 대장장이의 도구를 에이전트에게"
url: "https://notes.junghanacs.com/notes/20251021T164500"
author: "Junghan Kim"
date: "2025-10-21T16:45:00+09:00"
lastmod: "2025-10-21T16:45:00+09:00"
tags: ["anthropic","delegate","education","skills"]
description: "skill-creator를 대장장이가 도구를 에이전트에게 주는 철학으로 풀어낸 노트이다."
---

> [!abstract] 이 노트에 대하여
> 
> 전문 지식을 도구와 스킬 형태로 에이전트에게 건네는 일을 대장장이의 작업에 비유한다. delegation과 교육, 기술 전수가 만나는 철학 노트다.

## 히스토리

-   [2025-10-21 Tue 16:45] skill-creator 철학 및 구현 상세 분석

## 관련노트

-   [skill-creator 분석 및 Awesome Claude Skills 현황](https://notes.junghanacs.com/notes/20251021T120000)

## skill-creator 한글 해설서

### 개요: skill-creator = Meta-Skill

> **skill-creator는 "Skills를 만드는 Skill"이다**
> 
> 단순한 도구가 아닌, 에이전트에게 전문 지식을 전달하는 **마스터 대장장이의 작업대**

#### 핵심 철학: Dario Amodei의 Delegation

> "The key to working with AI agents is **delegation**.
> 
> Give them the tools, the knowledge, and the authority. Then let them work."
> 
> — Dario Amodei, Anthropic CEO

#### 대장장이-도구-에이전트 관계

```text
대장장이 (Master)
    │
    ├─ 전략 수립
    │  - 어떤 도구가 필요한가?
    │  - 도구의 형태와 기능은?
    │  - 어떻게 사용해야 하는가?
    │
    ├─ 도구 제작 (skill-creator)
    │  - init_skill.py (도구 틀 생성)
    │  - package_skill.py (도구 검증 및 배포)
    │  - SKILL.md (도구 사용 설명서)
    │
    └─ 에이전트에게 전달
       │
       └→ 에이전트 (Claude)
           - 도구 받음 (Skill)
           - 사용법 학습 (SKILL.md)
           - 작업 수행
           - 결과 보고
```

#### 왜 skill-creator인가?

일반 프롬프트:

-   에이전트에게 "이렇게 해봐" 매번 말함
-   일회성, 재사용 불가
-   토큰 낭비

skill-creator:

-   에이전트에게 "이 도구 써" 한 번만 줌
-   영구적, 재사용 가능
-   효율적

> **대장장이는 매번 설명하지 않는다.** **한 번 잘 만든 도구를 건네고, 사용법을 적어준다.**
> 
> 그것이 SKILL.md다.

### skill-creator의 구조

#### Anthropic 공식 정의

```yaml
---
name: skill-creator
description: Guide for creating effective skills. This skill should
  be used when users want to create a new skill (or update an
  existing skill) that extends Claude's capabilities with
  specialized knowledge, workflows, or tool integrations.
---
```

**핵심:**

-   skill-creator **자체가 하나의 Skill**
-   Skills를 만드는 방법을 **절차적 지식** 으로 담음
-   Claude와 대화하며 **새로운 Skill 자동 생성**

#### 5단계 프로세스 (skill-creator SKILL.md에서)

##### Step 1: Understanding (구체적 예제로 이해)

**목적:** Skill이 무엇을 해야 하는지 명확히 파악

**Claude가 사용자에게 질문:**

```text
"What functionality should the skill support?"
"Can you give examples of how this skill would be used?"
"What would a user say that should trigger this skill?"
```

**예시 (image-editor skill):**

> User: "I want an image editor skill"
> 
> Claude (skill-creator): "What functionality? Editing, rotating, anything else?" "Examples like 'Remove red-eye' or 'Rotate image'?" "Other use cases?"

**완료 조건:** 기능과 사용 사례가 명확해질 때

##### Step 2: Planning (재사용 가능한 컨텐츠 계획)

**목적:** 각 예제를 실행하는 데 필요한 리소스 식별

**분석 방법:**

1.  예제를 처음부터 어떻게 실행할지 고려
2.  어떤 scripts/references/assets가 도움될지 식별

**예시 1: pdf-editor skill**

```text
분석: "PDF 회전은 매번 같은 코드 재작성"
해결: scripts/rotate_pdf.py 번들
```

**예시 2: frontend-webapp-builder skill**

```text
분석: "매번 같은 boilerplate HTML/React"
해결: assets/hello-world/ 템플릿 번들
```

**예시 3: big-query skill**

```text
분석: "매번 테이블 스키마 재발견"
해결: references/schema.md 문서 번들
```

**결과:** scripts, references, assets 목록 생성

##### Step 3: Initializing (init_skill.py 실행)

**이 단계를 건너뛰는 경우:**

-   이미 존재하는 Skill 수정시
-   단순 반복 또는 패키징만 필요시

**새 Skill 만들 때:**

```bash
# skill-creator가 자동으로 실행
python scripts/init_skill.py <skill-name> --path <output-directory>

# 예시:
python scripts/init_skill.py my-new-skill --path skills/public
```

**자동 생성되는 것:**

-   Skill 디렉토리
-   SKILL.md 템플릿 (proper frontmatter + TODO 플레이스홀더)
-   예제 리소스 디렉토리: scripts/, references/, assets/
-   각 디렉토리에 예제 파일들 (커스터마이즈 또는 삭제 가능)

**이후:** 생성된 SKILL.md와 예제 파일 커스터마이즈

##### Step 4: Edit (Skill 편집)

**핵심 관점:**

> "Skill은 **다른 Claude 인스턴스** 가 사용할 것이다"
> 
> 따라서, 그 Claude에게 유익하고 자명하지 않은 정보에 집중하라.

###### 4-1. 재사용 가능한 컨텐츠부터 시작

Step 2에서 식별한 scripts/, references/, assets/ 먼저 구현

**주의:**

-   사용자 입력 필요할 수 있음
    -   brand-guidelines skill: 브랜드 자산 제공 필요
    -   API skill: API 문서 제공 필요
-   불필요한 예제 파일/디렉토리 삭제

###### 4-2. SKILL.md 업데이트

**Writing Style (중요!):**

```text
✅ Imperative/infinitive form (명령형/동사원형)
   "To accomplish X, do Y"
   "Use script.py for..."

❌ Second person (2인칭)
   "You should do X"
   "If you need to..."
```

**이유:** AI 소비용 일관성과 명확성

**답해야 할 질문 3가지:**

1.  Skill의 목적은? (몇 문장)
2.  언제 사용해야 하나?
3.  실제로 어떻게 사용하나?
    -   모든 재사용 가능한 컨텐츠 참조
    -   Claude가 사용법을 알도록

##### Step 5: Packaging (검증 및 배포)

**package_skill.py 실행:**

```bash
python scripts/package_skill.py <path/to/skill-folder>

# 출력 디렉토리 지정:
python scripts/package_skill.py <path/to/skill-folder> ./dist
```

**자동 프로세스:**

1.  **검증 (자동):**
    -   YAML frontmatter 형식 및 필수 필드
    -   Skill 이름 규칙 및 디렉토리 구조
    -   Description 완전성 및 품질
    -   파일 구성 및 리소스 참조

2.  **패키징 (검증 통과 시):**
    -   Skill 이름으로 ZIP 파일 생성 (my-skill.zip)
    -   모든 파일 포함
    -   디렉토리 구조 유지
    -   배포 준비 완료

**검증 실패 시:**

-   에러 리포트 출력
-   패키지 생성 안 함
-   에러 수정 후 재실행

##### Step 6: Iterate (반복 개선)

**워크플로우:**

1.  Skill을 실제 작업에 사용
2.  어려움이나 비효율 발견
3.  SKILL.md 또는 번들 리소스 업데이트 방법 식별
4.  변경 구현 및 재테스트

**특징:** 사용 직후 피드백 (신선한 컨텍스트)

### Python 스크립트 상세 분석

#### 1. init_skill.py (초기화 스크립트)

##### 사용법

```bash
init_skill.py <skill-name> --path <path>

# 예시:
init_skill.py my-new-skill --path skills/public
init_skill.py denote-org --path ~/repos/gh/orgmode-skills/temp/
```

##### 입력 검증

```python
# Skill name 요구사항:
- Hyphen-case (my-skill)
- Lowercase 문자, 숫자, 하이픈만
- 최대 40자
- 디렉토리 이름과 정확히 일치해야 함

# 예시:
✅ data-analyzer
✅ pdf-editor
❌ DataAnalyzer (camelCase 불가)
❌ data_analyzer (underscore 불가)
```

##### 핵심 로직

```python
def init_skill(skill_name, path):
    """
    1. Skill 디렉토리 생성
    2. SKILL.md 생성 (SKILL_TEMPLATE 사용)
    3. scripts/ 디렉토리 + example.py
    4. references/ 디렉토리 + api_reference.md
    5. assets/ 디렉토리 + example_asset.txt
    """
```

##### SKILL_TEMPLATE 구조

```text
---
name: {skill_name}
description: [TODO: ...]
---

# {skill_title}

## Overview
[TODO: 1-2 sentences]

## Structuring This Skill
[TODO: Choose pattern:]
  1. Workflow-Based (순차 프로세스)
  2. Task-Based (도구 모음)
  3. Reference/Guidelines (표준/명세)
  4. Capabilities-Based (통합 시스템)

## Resources
scripts/, references/, assets/ 설명
```

**4가지 구조 패턴:**

-   Workflow-Based: DOCX skill (Reading → Creating → Editing)
-   Task-Based: PDF skill (Merge → Split → Extract)
-   Reference/Guidelines: Brand styling
-   Capabilities-Based: Product Management

##### title_case_skill_name() 함수

```python
def title_case_skill_name(skill_name):
    """
    Hyphenated skill name → Title Case

    my-new-skill → My New Skill
    """
    return ' '.join(word.capitalize() for word in skill_name.split('-'))
```

#### 2. package_skill.py (패키징 스크립트)

##### 사용법

```bash
python package_skill.py <path/to/skill-folder> [output-directory]

# 예시:
python package_skill.py skills/public/my-skill
python package_skill.py skills/public/my-skill ./dist
```

##### 핵심 프로세스

```python
def package_skill(skill_path, output_dir=None):
    """
    1. Skill 폴더 존재 확인
    2. SKILL.md 존재 확인
    3. 검증 실행 (validate_skill)
       - 검증 실패 시 → 에러 리포트, 종료
       - 검증 통과 시 → 계속
    4. ZIP 파일 생성
       - skill_name.zip
       - 모든 파일 포함 (rglob)
       - 디렉토리 구조 유지
    5. 성공 메시지 출력
    """
```

##### 검증 먼저, 패키징은 나중

> **패키징 전 자동 검증!**
> 
> 검증 통과 → ZIP 생성 검증 실패 → 에러 리포트, 종료 (ZIP 생성 안 함)
> 
> "잘못된 도구는 배포하지 않는다"

##### ZIP 파일 생성 로직

```python
with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
    for file_path in skill_path.rglob('*'):  # 재귀적으로 모든 파일
        if file_path.is_file():
            arcname = file_path.relative_to(skill_path.parent)
            zipf.write(file_path, arcname)
            print(f"  Added: {arcname}")
```

**특징:**

-   모든 파일 재귀적 탐색
-   상대 경로 유지
-   압축 (ZIP_DEFLATED)

#### 3. quick_validate.py (빠른 검증 스크립트)

##### 사용법

```bash
python quick_validate.py <skill_directory>

# 성공 시: exit code 0
# 실패 시: exit code 1, 에러 메시지
```

##### 검증 항목

###### 1. SKILL.md 존재 확인

```python
skill_md = skill_path / 'SKILL.md'
if not skill_md.exists():
    return False, "SKILL.md not found"
```

###### 2. YAML Frontmatter 형식

```python
if not content.startswith('---'):
    return False, "No YAML frontmatter found"

# Frontmatter 추출 (정규식)
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
if not match:
    return False, "Invalid frontmatter format"
```

###### 3. 필수 필드 확인

```python
frontmatter = match.group(1)

if 'name:' not in frontmatter:
    return False, "Missing 'name' in frontmatter"
if 'description:' not in frontmatter:
    return False, "Missing 'description' in frontmatter"
```

###### 4. Name 규칙 검증

```python
name_match = re.search(r'name:\s*(.+)', frontmatter)
name = name_match.group(1).strip()

# Hyphen-case 검증
if not re.match(r'^[a-z0-9-]+$', name):
    return False, "Name should be hyphen-case (lowercase + hyphens)"

# 시작/끝 하이픈, 연속 하이픈 금지
if name.startswith('-') or name.endswith('-') or '--' in name:
    return False, "Cannot start/end with hyphen or contain consecutive hyphens"
```

**규칙:**

-   Lowercase 문자, 숫자, 하이픈만
-   시작/끝 하이픈 불가
-   연속 하이픈 (--) 불가

###### 5. Description 검증

```python
desc_match = re.search(r'description:\s*(.+)', frontmatter)
description = desc_match.group(1).strip()

# 꺾쇠 괄호 금지
if '<' in description or '>' in description:
    return False, "Description cannot contain angle brackets"
```

**이유:** YAML 파싱 오류 방지

##### validate_skill() 함수 시그니처

```python
def validate_skill(skill_path) -> tuple[bool, str]:
    """
    Returns:
        (True, "Skill is valid!") - 검증 통과
        (False, "Error message") - 검증 실패
    """
```

### Progressive Disclosure: Skills의 핵심 설계

#### 3단계 로딩 시스템

```text
Level 1: Metadata (name + description)
         - 항상 컨텍스트에 (~100 words)
         - 30-50 tokens
         - Skill 발견용

         ↓ (Skill 트리거되면)

Level 2: SKILL.md body
         - 필요시에만 로드 (<5k words)
         - 핵심 지침 및 절차

         ↓ (Claude가 판단하여)

Level 3: Bundled resources
         - 필요한 것만 선택적 로드
         - scripts: 실행만 (컨텍스트 안 차지!)
         - references: 필요시 로드
         - assets: 출력에 사용 (컨텍스트 안 차지)
```

**핵심:**

> **Scripts는 "Unlimited"**
> 
> 실행만 하면 됨, 컨텍스트에 로드 안 함 토큰 소모 없이 복잡한 작업 가능
> 
> → 대장장이가 만든 "도구" → 에이전트는 사용법만 알면 됨

### 리소스 디렉토리: scripts, references, assets

#### scripts/ (실행 가능한 코드)

**목적:** 결정론적 신뢰성 또는 반복 재작성되는 작업

**언제 포함:**

-   같은 코드가 반복 재작성될 때
-   결정론적 신뢰성 필요할 때

**예시:**

-   PDF skill: `rotate_pdf.py`, `fill_fillable_fields.py`
-   DOCX skill: `document.py`, `utilities.py`

**적합한 것:**

-   Python 스크립트
-   Shell 스크립트
-   자동화, 데이터 처리, 특정 작업 수행 코드

**중요:**

-   스크립트는 컨텍스트에 로드 안 하고 실행 가능
-   하지만 Claude가 패칭이나 환경 조정 위해 읽을 수는 있음

#### references/ (참조 문서)

**목적:** Claude의 프로세스와 사고를 알려주기 위해 컨텍스트에 로드될 문서

**언제 포함:**

-   Claude가 작업하면서 참조해야 할 문서

**예시:**

-   Product management: `communication.md`, `context_building.md`
-   BigQuery: API 참조 문서, 쿼리 예제
-   Finance: 스키마 문서, 회사 정책

**적합한 것:**

-   API 문서
-   데이터베이스 스키마
-   도메인 지식
-   회사 정책
-   상세 워크플로우 가이드

**Best Practice:**

-   파일 크기 &gt;10k words면 SKILL.md에 grep 검색 패턴 포함
-   정보는 SKILL.md 또는 references 중 한 곳에만 (중복 피하기)
-   상세 정보는 references로 (SKILL.md는 lean하게)

#### assets/ (출력에 사용될 파일)

**목적:** 컨텍스트에 로드되지 않고, Claude가 생성하는 출력에 사용될 파일

**언제 포함:**

-   Skill이 최종 출력에 사용할 파일 필요시

**예시:**

-   Brand assets: `logo.png`, PowerPoint 템플릿
-   Frontend builder: HTML/React boilerplate 디렉토리
-   Typography: `font.ttf`

**적합한 것:**

-   템플릿 (문서, 슬라이드)
-   이미지, 아이콘
-   Boilerplate 코드
-   폰트
-   복사되거나 수정될 샘플 문서

**장점:**

-   출력 리소스와 문서 분리
-   Claude가 컨텍스트에 로드 안 하고 파일 사용 가능

#### 디렉토리 구조 요약

| 디렉토리        | 용도      | 컨텍스트 로드? | 예시                    |
|-------------|---------|----------|-----------------------|
| **scripts/**    | 실행 가능한 코드 | ❌ (실행만) | rotate_pdf.py           |
| **references/** | 참조 문서 | ✅ (필요시) | schema.md, api_docs.md  |
| **assets/**     | 출력 파일 | ❌ (사용만) | template.pptx, logo.png |

> **핵심:** scripts와 assets는 컨텍스트 안 차지 → Unlimited 리소스 가능 → 대장장이가 준비해 놓은 "도구함"

### 대장장이-도구-에이전트: 철학적 깊이

#### 전통 대장장이와 장인

```text
대장장이 (Blacksmith)
    - 도구 설계
    - 금속 단조
    - 품질 검증
    - 사용법 전수

    ↓

장인 (Craftsman)
    - 도구 받음
    - 사용법 학습
    - 작품 제작
    - 결과 보고
```

#### Anthropic Skills 시스템

```text
Master (Human + skill-creator)
    - Skill 설계 (Step 1-2)
    - 도구 제작 (init_skill.py)
    - 품질 검증 (package_skill.py)
    - 사용법 문서화 (SKILL.md)

    ↓

Agent (Claude)
    - Skill 로드 (30-50 tokens)
    - 사용법 학습 (SKILL.md 읽기)
    - 작업 수행 (scripts 실행)
    - 결과 보고
```

#### "맡기기(Delegation)"의 본질

> **Dario Amodei:**
> 
> "AI 에이전트와 일하는 핵심은 맡기기(delegation)다.
> 
> 도구를 주고, 지식을 주고, 권한을 주고, 그 다음엔 그들이 일하게 하라."

**전통적 방식 (❌):**

```text
Master: "이렇게 해봐" (매번)
Agent: "네" (수행)
Master: "저렇게 해봐" (매번)
Agent: "네" (수행)

→ Micro-management
→ 매번 설명
→ 비효율
```

**Delegation 방식 (✅):**

```text
Master: "이 도구 써" (한 번)
        + SKILL.md (사용법)
        + scripts (검증된 코드)
        + references (도메인 지식)
Agent: (스스로 판단하여 사용)
Master: (결과만 확인)

→ Empowerment
→ 한 번 설명
→ 효율적
```

#### Skills = "절차적 지식(Procedural Knowledge)"의 구현

> Anthropic 공식 정의:
> 
> "Skills transform Claude from a general-purpose agent into a specialized agent equipped with **procedural knowledge** that no model can fully possess."

**절차적 지식이란?**

| 선언적 지식         | 절차적 지식         |
|----------------|----------------|
| "파리는 프랑스 수도다" | "파리 가는 방법"    |
| "PDF는 문서 포맷이다" | "PDF Forms 채우는 8단계" |
| "Denote는 PKM 시스템이다" | "3,000 파일서 검색하는 법" |

**Skills = 절차적 지식 패키징**

#### 대장장이의 3가지 도구 (skill-creator)

##### 1. init_skill.py (도구 틀 제작)

> "비어있는 칼날을 만든다"
> 
> SKILL.md 템플릿 scripts/, references/, assets/ 구조 TODO 플레이스홀더
> 
> → 대장장이가 채워 넣을 틀

##### 2. package_skill.py (도구 검증 및 배포)

> "완성된 칼날을 벼리고 검증한다"
> 
> YAML 형식 검증 Name 규칙 검증 Description 품질 검증 디렉토리 구조 확인
> 
> → 품질 보증된 도구만 배포

##### 3. quick_validate.py (빠른 검사)

> "칼날의 균형을 빠르게 확인한다"
> 
> 필수 항목만 검증 빠른 피드백 반복 개발용
> 
> → 대장장이의 눈과 손

### skill-creator 사용 시나리오

#### 시나리오 1: 대화형 생성 (가장 쉬움)

```text
User (대장장이):
  "Use skill-creator to help me build a skill for processing invoices"

Claude (skill-creator 로드):
  Step 1: "What functionality should the invoice skill support?"

User: "Extract data, validate totals, categorize expenses"

Claude:
  "Can you give examples of typical invoices?"

User: (예제 제공)

Claude (Step 2 분석):
  "I'll create scripts for data extraction, validation, and categorization.
   And references for invoice formats."

Claude (Step 3 실행):
  python init_skill.py invoice-processor --path skills/

  ✅ Created skill directory: skills/invoice-processor
  ✅ Created SKILL.md with TODO items
  ✅ Created scripts/, references/, assets/

Claude (Step 4 가이드):
  "Let's complete SKILL.md..."
  (함께 편집)

Claude (Step 5 실행):
  python package_skill.py skills/invoice-processor

  🔍 Validating...
  ✅ Skill is valid!
  📦 Creating invoice-processor.zip...
  ✅ Successfully packaged!

User: (ZIP 다운로드 또는 Git commit)
```

**특징:**

-   대화 기반
-   자동 생성
-   가이드됨

#### 시나리오 2: 직접 실행 (우리 방식)

```text
Master (직접):
  # 1. 전략 수립 (문서로 정리)
  - README.md, README-KO.md
  - docs/20251021T113500--*.org
  - TODO.org

  # 2. 도구 틀 생성
  python init_skill.py denote-org --path temp/

  # 3. 수동 편집 (정교한 커스터마이즈)
  vim SKILL.md
  - 6 Core Capabilities
  - Opus 4.1 피드백 반영
  - 9-layer context

  # 4. 스크립트 구현
  vim scripts/denote_parser.py
  vim scripts/denote_finder.py
  ...

  # 5. 검증 및 테스트
  python quick_validate.py .
  (실제 3,000+ 파일로 테스트)

  # 6. 패키징
  python package_skill.py . ./dist

  # 7. 공개
  git push
  GitHub Public
```

**특징:**

-   완전 제어
-   투명한 과정
-   학습 효과
-   최적화 가능

#### 시나리오 3: Hybrid (추천)

```text
1. skill-creator로 빠른 프로토타입
   → 기본 구조 자동 생성

2. 수동 편집으로 정교화
   → Denote 특화, 9-layer context

3. 실제 사용 테스트
   → 3,000+ 파일로 검증

4. 반복 개선
   → 피드백 반영
```

### 한국 개발자를 위한 교육적 가치

#### skill-creator가 가르치는 것

##### 1. "맡기기(Delegation)" 전략

> 매번 지시하지 마라. 도구를 만들어 주고, 사용법을 적어 주고, 맡겨라.
> 
> 그것이 효율이다.

##### 2. "절차적 지식(Procedural Knowledge)" 패키징

> "이렇게 해"가 아니라 "이런 경우엔 항상 이렇게 한다"
> 
> 한 번 정리하면, 영구적으로 재사용 가능

##### 3. "Progressive Disclosure" 설계

> 모든 것을 처음부터 주지 마라.
> 
> Level 1: 발견 (30-50 tokens) Level 2: 이해 (5k words) Level 3: 실행 (Unlimited)
> 
> 필요한 것만, 필요할 때

##### 4. "Domain Expertise" 전달

> Claude는 범용 AI Skill은 도메인 전문가
> 
> PDF Skill + Claude = PDF 전문가 Denote-Org Skill + Claude = PKM 전문가
> 
> 도메인 컨텍스트 = AI의 전문성

#### 한국어 Skills 생태계 구축

현재:

-   영어권 중심
-   한국어 Skills 거의 없음
-   한국 개발자 진입 장벽

skill-creator 한글 해설:

-   Skills 철학 전달
-   한국어로 설명
-   한국 개발자 온보딩
-   한국어 도메인 Skills 생태계

**예시:**

-   한글 문서 처리 Skills
-   한국 서비스 API Skills
-   Denote-Org Skills (우리!)
-   한국어 교육 컨텐츠

### 실전 가이드: skill-creator 활용법

#### 준비물

1.  **Claude Code 또는 Claude.ai Pro+**
2.  **skill-creator skill 활성화**
    ```bash
    /plugin marketplace add anthropics/skills
    /plugin install example-skills@anthropic-agent-skills
    ```

3.  **명확한 Skill 아이디어**
    -   무엇을 하는 Skill인가?
    -   언제 사용하는가?
    -   구체적 예제 3개 이상

#### 실행 단계별 가이드

##### 1. skill-creator 호출

```text
User: "Use the skill-creator to help me build a skill for
       [구체적인 작업 설명]"

예시:
"Use the skill-creator to help me build a skill for
 managing Denote-based PKM systems with 3,000+ org files"
```

##### 2. Claude의 질문에 답변 (Step 1)

Claude가 물어볼 것:

```text
Q: "What functionality should the skill support?"
A: "Find files by ID, resolve links, build knowledge graph..."

Q: "Can you give specific examples?"
A: "User says 'Find file 20251021T105353'"
   "User says 'Show connected notes'"

Q: "What would trigger this skill?"
A: "Denote files (timestamp--title__tags.org format)"
   "Knowledge graph queries"
   "Large PKM systems (100+ files)"
```

**팁:**

-   구체적으로 답변
-   실제 사용 사례 제공
-   3-5개 예제면 충분

##### 3. 계획 단계 (Step 2)

Claude가 분석:

```text
"Based on your examples, I'll create:

scripts/:
- denote_finder.py (file search with caching)
- denote_links.py (link resolution)
- denote_graph.py (knowledge graph builder)

references/:
- denote-spec.md (Denote specification)
- orgmode-syntax.md (Org-mode reference)

assets/:
- (none needed - processing existing files)
"
```

**확인:** 계획이 맞는지 검토

##### 4. 자동 생성 (Step 3)

Claude가 실행:

```bash
python scripts/init_skill.py your-skill-name --path <path>
```

생성 결과:

```text
✅ Created skill directory
✅ Created SKILL.md (with your context!)
✅ Created scripts/example.py
✅ Created references/api_reference.md
✅ Created assets/example_asset.txt
```

##### 5. 함께 편집 (Step 4)

Claude가 가이드:

```text
"Let's complete SKILL.md together.

1. Overview section:
   [Claude가 draft 제시]

2. Core Capabilities:
   [사용자 예제 기반으로 작성]

3. Quick Start:
   [구체적 사용 예시]

4. Common Pitfalls:
   [예상되는 문제들]
"
```

**협업:** Claude가 draft, 사용자가 리뷰 및 개선

##### 6. 패키징 및 배포 (Step 5)

Claude가 실행:

```bash
python scripts/package_skill.py <path/to/skill>
```

검증 및 패키징:

```text
🔍 Validating skill...
✅ Skill is valid!

📦 Packaging...
  Added: your-skill/SKILL.md
  Added: your-skill/scripts/...
  Added: your-skill/references/...

✅ Successfully packaged: your-skill.zip
```

#### 우리가 배운 것: 수동 + skill-creator

##### 우리의 접근

1.  ✅ **전략 먼저** (문서화)
    -   README.md, README-KO.md
    -   docs/ 작업 로그
    -   TODO.org 로드맵

2.  ✅ **skill-creator 활용**
    -   init_skill.py로 구조 생성
    -   템플릿에서 시작

3.  ✅ **컨텍스트 주입**
    -   Denote 특화
    -   3,000+ 파일 맥락
    -   9-layer 철학
    -   Opus 4.1 피드백

4.  🔄 **점진적 개선**
    -   스크립트 구현
    -   실제 테스트
    -   커뮤니티 피드백

**결과:** skill-creator의 효율 + 우리의 깊이

### 교육적 의미: 단순한 수준이 아니다

#### 레벨 1: 도구 사용자 (Tool User)

```text
"Claude야, PDF 회전해줘"

Claude: (매번 코드 생성)
```

**역할:** 소비자

#### 레벨 2: 프롬프트 엔지니어 (Prompt Engineer)

```text
"Claude야, PDF 회전할 때 이런 라이브러리 쓰고,
이런 옵션 쓰고, 이렇게 해"

Claude: (프롬프트 따라 수행)
```

**역할:** 지시자

#### 레벨 3: Skill 제작자 (Skill Creator)

```text
대장장이:
  1. PDF 회전 절차 분석
  2. scripts/rotate_pdf.py 작성
  3. SKILL.md 문서화
  4. Skill 배포

Claude: (Skill 로드)
  "PDF 회전 요청 감지"
  → scripts/rotate_pdf.py 실행
  → 완료
```

**역할:** **도구 제작자 (Tool Maker)**

> **이것이 "대장장이가 도구를 만들어 에이전트에게 주는 것"**
> 
> 단순한 수준의 에이전트 사용이 아니다. 마스터가 전략을 세우고, 도구를 제작하고, 에이전트를 empowerment하는 것이다.

#### 한국 개발자를 위한 의미

##### 기술 스택의 패러다임 전환

**전통적:**

```text
개발자 → 코드 작성 → 배포
```

**AI 시대:**

```text
개발자 (대장장이)
    → Skills 제작 (도구)
    → AI Agent에게 위임 (delegation)
    → AI Agent가 코드 생성 및 실행
```

##### "장인 정신"의 새로운 의미

> 전통 장인: "손으로 직접 만든다" AI 시대 장인: "도구를 만들고, AI에게 맡긴다"
> 
> 하지만 본질은 같다:
> 
> -   마스터의 전략
> -   품질에 대한 집착
> -   절차적 지식의 보존
> -   후대에 전수

##### Skills = "지식의 컴파일"

> 코드 컴파일: 소스 코드 → 실행 파일 Skills 컴파일: 도메인 지식 → SKILL.md + scripts
> 
> 한 번 컴파일하면, 어디서나 실행 가능 (Claude.ai, Code, API) 재사용 가능 공유 가능
> 
> **지식을 컴파일하는 시대**

### 실전 체크리스트: Skill 제작자를 위한 가이드

#### Before Starting

-   [ ] 명확한 도메인 정의 (PDF? Denote? API?)
-   [ ] 3개 이상 구체적 사용 사례
-   [ ] 반복되는 작업 식별
-   [ ] "이거 매번 설명하기 귀찮은데" 느낌

#### During Creation

##### Step 1: Understanding

-   [ ] 모든 기능 나열
-   [ ] 구체적 예제 3-5개
-   [ ] 트리거 시나리오 정의

##### Step 2: Planning

-   [ ] scripts 필요 여부 (반복 재작성되는가?)
-   [ ] references 필요 여부 (도메인 지식 많은가?)
-   [ ] assets 필요 여부 (템플릿 사용하는가?)

##### Step 3: Initializing

-   [ ] init_skill.py 실행
-   [ ] 생성된 구조 확인
-   [ ] 불필요한 디렉토리 삭제

##### Step 4: Editing

-   [ ] Description 완성 (WHEN 명확히)
-   [ ] 구조 패턴 선택 (Workflow/Task/Reference/Capabilities)
-   [ ] "Structuring This Skill" 섹션 삭제
-   [ ] Imperative form 사용 (not second person)
-   [ ] scripts 참조 방법 명시
-   [ ] Quick Start 예제 추가
-   [ ] Common Pitfalls 추가

##### Step 5: Packaging

-   [ ] quick_validate.py 실행
-   [ ] 검증 통과 확인
-   [ ] package_skill.py 실행
-   [ ] ZIP 파일 생성 확인

#### After Release

-   [ ] 실제 사용 테스트
-   [ ] 피드백 수집
-   [ ] 반복 개선 (Step 6)
-   [ ] 버전 관리 (Git tags)
-   [ ] 커뮤니티 공유

### 코드 상세 해설

#### init_skill.py 핵심 함수들

##### title_case_skill_name()

```python
def title_case_skill_name(skill_name):
    """
    my-new-skill → My New Skill
    denote-org → Denote Org
    """
    return ' '.join(word.capitalize() for word in skill_name.split('-'))
```

**용도:** SKILL.md 제목 생성

##### init_skill()

```python
def init_skill(skill_name, path):
    """
    1. Path 생성
       skill_path = Path(path) / skill_name

    2. 디렉토리 생성
       skill_path.mkdir(parents=True, exist_ok=True)

    3. SKILL.md 생성
       (skill_path / "SKILL.md").write_text(
           SKILL_TEMPLATE.format(
               skill_name=skill_name,
               skill_title=title_case_skill_name(skill_name)
           )
       )

    4. scripts/, references/, assets/ 생성
       + 각각 예제 파일 생성

    5. 성공 메시지
    """
```

**템플릿 변수:**

-   `{skill_name}` → hyphen-case name
-   `{skill_title}` → Title Case name

##### SKILL_TEMPLATE 구조

```text
4가지 구조 패턴 제시:

1. Workflow-Based
   - 순차 프로세스
   - 예: DOCX (Reading → Creating → Editing)

2. Task-Based
   - 도구 모음
   - 예: PDF (Merge → Split → Extract)

3. Reference/Guidelines
   - 표준/명세
   - 예: Brand styling

4. Capabilities-Based
   - 통합 시스템
   - 예: Product Management
```

**대장장이의 선택:** "어떤 형태의 도구를 만들 것인가?"

#### package_skill.py 핵심 로직

##### 검증 먼저

```python
# 1. 폴더 존재 확인
if not skill_path.exists():
    return None, "Skill folder not found"

# 2. SKILL.md 확인
if not (skill_path / "SKILL.md").exists():
    return None, "SKILL.md not found"

# 3. 검증 실행
valid, message = validate_skill(skill_path)
if not valid:
    print(f"❌ Validation failed: {message}")
    return None  # 패키징 안 함!
```

**철학:** "잘못된 도구는 배포하지 않는다"

##### ZIP 생성

```python
with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
    for file_path in skill_path.rglob('*'):  # 재귀 탐색
        if file_path.is_file():
            # 상대 경로 계산
            arcname = file_path.relative_to(skill_path.parent)
            zipf.write(file_path, arcname)
```

**특징:**

-   재귀적으로 모든 파일 포함
-   디렉토리 구조 보존
-   압축 (ZIP_DEFLATED)

#### quick_validate.py 검증 로직

##### YAML Frontmatter 파싱

```python
# 1. '---'로 시작하는지
if not content.startswith('---'):
    return False, "No YAML frontmatter"

# 2. 정규식으로 frontmatter 추출
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
frontmatter = match.group(1)
```

##### 필수 필드 검증

```python
if 'name:' not in frontmatter:
    return False, "Missing 'name'"
if 'description:' not in frontmatter:
    return False, "Missing 'description'"
```

##### Name 규칙 검증

```python
name = extract_name(frontmatter)

# Hyphen-case only
if not re.match(r'^[a-z0-9-]+$', name):
    return False, "Name should be hyphen-case"

# 시작/끝 하이픈 금지
if name.startswith('-') or name.endswith('-'):
    return False, "Cannot start/end with hyphen"

# 연속 하이픈 금지
if '--' in name:
    return False, "Cannot contain consecutive hyphens"
```

**엄격한 규칙 = 일관성**

##### Description 검증

```python
description = extract_description(frontmatter)

# 꺾쇠 괄호 금지
if '<' in description or '>' in description:
    return False, "Cannot contain angle brackets"
```

**이유:** YAML 파싱 오류 방지

### 맺음말: 대장장이의 시대

> **과거:** 개발자가 직접 코드를 작성했다
> 
> **현재:** 개발자가 도구를 만들고, AI에게 맡긴다
> 
> **미래:** 개발자는 전략을 세우고, AI가 도구를 만들고, AI가 코드를 작성한다
> 
> 하지만 변하지 않는 것:
> 
> -   마스터의 전략
> -   도구의 품질
> -   절차적 지식
> -   장인 정신

#### skill-creator의 교훈

##### 1. 맡기기 (Delegation)

```text
매번 설명 (X) → 도구 제작 (O)
Micro-management (X) → Empowerment (O)
```

##### 2. 절차적 지식 (Procedural Knowledge)

```text
"이렇게 해" (일회성) → "이런 경우엔 항상 이렇게" (영구적)
```

##### 3. 점진적 공개 (Progressive Disclosure)

```text
30-50 tokens (발견) → 5k words (이해) → Unlimited (실행)
```

##### 4. 품질 검증 (Quality Assurance)

```text
자동 검증 → 잘못된 도구는 배포 안 함
```

#### 한국 개발자에게

> skill-creator는 단순한 코드 생성기가 아닙니다.
> 
> **마스터가 장인을 키우는 시스템** 입니다.
> 
> 당신이 쌓은 도메인 지식을, 절차적 지식으로 패키징하고, AI 에이전트에게 전달하여, 영구적으로 재사용 가능하게 만드는,
> 
> **지식의 컴파일러** 입니다.
> 
> 그리고 이것은, Anthropic이 생명과학에서 증명한 패러다임을, 모든 도메인으로 확장하는,
> 
> **Life Sciences for Everyone** 의 구현입니다.

#### Denote-Org Skills의 의미

우리 프로젝트:

-   skill-creator로 시작 (템플릿 자동 생성)
-   우리 컨텍스트로 채움 (3,000+ 파일, 9-layer)
-   품질 검증 (Opus 4.1 피드백)
-   커뮤니티 공유 (오픈소스)

> **대장장이가 만든 첫 번째 도구:** Denote-Org Skills
> 
> **에이전트가 받은 것:**
> 
> -   3,000+ 파일 PKM 전문 지식
> -   검증된 Python 스크립트
> -   상세한 사용 가이드
> 
> **결과:** Claude = Denote PKM 전문가

### 참고 자료

#### Anthropic 공식

-   skill-creator: ~/repos/3rd/snthropics-skills/skill-creator/
-   init_skill.py: 자동 생성 스크립트
-   package_skill.py: 검증 및 패키징
-   quick_validate.py: 빠른 검증

#### 우리 프로젝트

-   ~/repos/gh/orgmode-skills/
-   SKILL.md (381줄, skill-creator 템플릿 기반)
-   README.md, README-KO.md
-   docs/ 작업 로그

#### 커뮤니티

-   awesome-claude-skills
-   obra/superpowers (20+ skills)
-   Simon Willison 분석

---

**작성:** 2025-10-21T16:45:00+09:00 **대상:** 한국 개발자, Skills 입문자 **목적:** skill-creator 철학 및 사용법 교육 **핵심:** "대장장이가 도구를 만들어 에이전트에게 주는 것"

📊 Tokens: 12,500 in, 9,000 out