@힣: skill-creator - 대장장이의 도구를 에이전트에게

히스토리

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

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

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

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

왜 skill-creator인가?

일반 프롬프트:

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

skill-creator:

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

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

그것이 SKILL.md다.

skill-creator의 구조

Anthropic 공식 정의

---
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가 사용자에게 질문:

"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 (재사용 가능한 컨텐츠 계획)

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

분석 방법:

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

예시 1: pdf-editor skill

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

예시 2: frontend-webapp-builder skill

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

예시 3: big-query skill

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

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

Step 3: Initializing (init_skill.py 실행)

이 단계를 건너뛰는 경우:

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

새 Skill 만들 때:

# 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 (중요!):

✅ 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가지:

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

Step 5: Packaging (검증 및 배포)

package_skill.py 실행:

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

자동 프로세스:

검증 (자동):
- YAML frontmatter 형식 및 필수 필드
- Skill 이름 규칙 및 디렉토리 구조
- Description 완전성 및 품질
- 파일 구성 및 리소스 참조
패키징 (검증 통과 시):
- Skill 이름으로 ZIP 파일 생성 (my-skill.zip)
- 모든 파일 포함
- 디렉토리 구조 유지
- 배포 준비 완료

검증 실패 시:

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

Step 6: Iterate (반복 개선)

워크플로우:

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

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

Python 스크립트 상세 분석

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

사용법

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/

입력 검증

# Skill name 요구사항:
- Hyphen-case (my-skill)
- Lowercase 문자, 숫자, 하이픈만
- 최대 40자
- 디렉토리 이름과 정확히 일치해야 함
 
# 예시:
✅ data-analyzer
✅ pdf-editor
❌ DataAnalyzer (camelCase 불가)
❌ data_analyzer (underscore 불가)

핵심 로직

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 구조

---
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() 함수

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 (패키징 스크립트)

사용법

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

핵심 프로세스

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 파일 생성 로직

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 (빠른 검증 스크립트)

사용법

python quick_validate.py <skill_directory>
 
# 성공 시: exit code 0
# 실패 시: exit code 1, 에러 메시지

검증 항목

1. SKILL.md 존재 확인

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

2. YAML Frontmatter 형식

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. 필수 필드 확인

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 규칙 검증

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 검증

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() 함수 시그니처

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

Progressive Disclosure: Skills의 핵심 설계

3단계 로딩 시스템

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:

파일 크기 >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 리소스 가능 → 대장장이가 준비해 놓은 “도구함”

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

전통 대장장이와 장인

대장장이 (Blacksmith)
    - 도구 설계
    - 금속 단조
    - 품질 검증
    - 사용법 전수
 
    ↓
 
장인 (Craftsman)
    - 도구 받음
    - 사용법 학습
    - 작품 제작
    - 결과 보고

Anthropic Skills 시스템

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)다.

도구를 주고, 지식을 주고, 권한을 주고, 그 다음엔 그들이 일하게 하라.”

전통적 방식 (❌):

Master: "이렇게 해봐" (매번)
Agent: "네" (수행)
Master: "저렇게 해봐" (매번)
Agent: "네" (수행)
 
→ Micro-management
→ 매번 설명
→ 비효율

Delegation 방식 (✅):

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: 대화형 생성 (가장 쉬움)

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: 직접 실행 (우리 방식)

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 (추천)

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 활용법

준비물

Claude Code 또는 Claude.ai Pro+

skill-creator skill 활성화

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

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

실행 단계별 가이드

1. skill-creator 호출

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가 물어볼 것:

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가 분석:

"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가 실행:

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

생성 결과:

✅ 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가 가이드:

"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가 실행:

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

검증 및 패키징:

🔍 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

우리의 접근

✅ 전략 먼저 (문서화)
- README.md, README-KO.md
- docs/ 작업 로그
- TODO.org 로드맵
✅ skill-creator 활용
- init_skill.py로 구조 생성
- 템플릿에서 시작
✅ 컨텍스트 주입
- Denote 특화
- 3,000+ 파일 맥락
- 9-layer 철학
- Opus 4.1 피드백
🔄 점진적 개선
- 스크립트 구현
- 실제 테스트
- 커뮤니티 피드백

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

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

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

"Claude야, PDF 회전해줘"
 
Claude: (매번 코드 생성)

역할: 소비자

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

"Claude야, PDF 회전할 때 이런 라이브러리 쓰고,
이런 옵션 쓰고, 이렇게 해"
 
Claude: (프롬프트 따라 수행)

역할: 지시자

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

대장장이:
  1. PDF 회전 절차 분석
  2. scripts/rotate_pdf.py 작성
  3. SKILL.md 문서화
  4. Skill 배포
 
Claude: (Skill 로드)
  "PDF 회전 요청 감지"
  → scripts/rotate_pdf.py 실행
  → 완료

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

이것이 “대장장이가 도구를 만들어 에이전트에게 주는 것”

단순한 수준의 에이전트 사용이 아니다. 마스터가 전략을 세우고, 도구를 제작하고, 에이전트를 empowerment하는 것이다.

한국 개발자를 위한 의미

기술 스택의 패러다임 전환

전통적:

개발자 → 코드 작성 → 배포

AI 시대:

개발자 (대장장이)
    → 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

코드 상세 해설

init_skill.py 핵심 함수들

title_case_skill_name()

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()

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 구조

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 핵심 로직

검증 먼저

# 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 생성

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 파싱

# 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)

필수 필드 검증

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

Name 규칙 검증

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 검증

description = extract_description(frontmatter)
 
# 꺾쇠 괄호 금지
if '<' in description or '>' in description:
    return False, "Cannot contain angle brackets"

이유: YAML 파싱 오류 방지

맺음말: 대장장이의 시대

과거: 개발자가 직접 코드를 작성했다

현재: 개발자가 도구를 만들고, AI에게 맡긴다

미래: 개발자는 전략을 세우고, AI가 도구를 만들고, AI가 코드를 작성한다

하지만 변하지 않는 것:

마스터의 전략

도구의 품질

절차적 지식

장인 정신

skill-creator의 교훈

1. 맡기기 (Delegation)

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

2. 절차적 지식 (Procedural Knowledge)

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

3. 점진적 공개 (Progressive Disclosure)

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

4. 품질 검증 (Quality Assurance)

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

한국 개발자에게

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

junghanacs🧠

Table of Contents

Backlinks

@힣: skill-creator - 대장장이의 도구를 에이전트에게

히스토리

관련노트

skill-creator 한글 해설서

개요: skill-creator = Meta-Skill

핵심 철학: Dario Amodei의 Delegation

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

왜 skill-creator인가?

skill-creator의 구조

Anthropic 공식 정의

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

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

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

Step 3: Initializing (init_skill.py 실행)

Step 4: Edit (Skill 편집)

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

4-2. SKILL.md 업데이트

Step 5: Packaging (검증 및 배포)

Step 6: Iterate (반복 개선)

Python 스크립트 상세 분석

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

사용법

입력 검증

핵심 로직

SKILL_TEMPLATE 구조

title_case_skill_name() 함수

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

사용법

핵심 프로세스

검증 먼저, 패키징은 나중

ZIP 파일 생성 로직

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

사용법

검증 항목

1. SKILL.md 존재 확인

2. YAML Frontmatter 형식

3. 필수 필드 확인

4. Name 규칙 검증

5. Description 검증

validate_skill() 함수 시그니처

Progressive Disclosure: Skills의 핵심 설계

3단계 로딩 시스템

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

scripts/ (실행 가능한 코드)

references/ (참조 문서)

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

디렉토리 구조 요약

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

전통 대장장이와 장인

Anthropic Skills 시스템

”맡기기(Delegation)“의 본질

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

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

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

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

3. quick_validate.py (빠른 검사)

skill-creator 사용 시나리오

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

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

시나리오 3: Hybrid (추천)

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

skill-creator가 가르치는 것

1. “맡기기(Delegation)” 전략

2. “절차적 지식(Procedural Knowledge)” 패키징

3. “Progressive Disclosure” 설계

4. “Domain Expertise” 전달

한국어 Skills 생태계 구축

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

준비물

실행 단계별 가이드

1. skill-creator 호출

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

3. 계획 단계 (Step 2)

4. 자동 생성 (Step 3)

5. 함께 편집 (Step 4)

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

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