Yinyo Skill Craft — Skill 工匠
Skill 엔지니어링 감사 및 대화형 수정 도구. Perplexity Agents Team 공식 가이드 + Karpathy CLAUDE.md 코딩 표준 + yinyo 시리즈 실전 경험을 기반으로 합니다.
새로운 기능: 자동 수정 + 사용자 확인 모드 지원.
핵심 규칙
1. Skill은 파일이 아닌 디렉토리입니다.
- 단일 파일 > 50KB → 반드시 hub-and-spoke 구조로 분할해야 함
- 표준 구조: SKILL.md + README.md + docs/ + examples/ + subskills/
- 다중 중첩: 300개 주제 → 20개 도메인 → 15개 주제/도메인
2. Description은 라우팅 트리거입니다.
- 반드시
Load when...으로 시작해야 함 - 기능 목록이 아닌 트리거 조건을 설명해야 함
- 50자 이내로 제한
3. 3단계 점진적 로딩
| 레벨 | Token 예산 | 내용 | 지불 빈도 |
|---|---|---|---|
| Index | ~100 | name + description | 세션마다 |
| Body | ~5000 | 핵심 규칙 + 빠른 참조 | 로딩 후 compaction까지 |
| Runtime | 무제한 | docs/ + examples/ + subskills/ | 사용 시점에 |
4. 모델이 이미 아는 내용은 삭제하세요.
- 기본 개념 설명 → 삭제
- 일반적인 프로그래밍 원칙 → 삭제
- "설명하기 쉬운 내용이라면 모델이 이미 알고 있습니다. 삭제하세요."
5. Karpathy 코딩 4원칙
- Think Before Coding: 확실하지 않으면 질문
- Simplicity First: 200줄로 작성 가능하면 500줄을 작성하지 않음
- Surgical Changes: 반드시 필요한 부분만 수정
- Goal-Driven Execution: 검증 가능한 목표 정의
대화형 수정 절차 (신규)
수정 원칙
- 저위험 (구조, 형식, 버전) → 자동 실행, 사후 보고
- 중위험 (설명 재작성) → 수정 전후 비교 표시, 사용자 확인
- 고위험 (내용 삭제) → 삭제 목록 나열, 항목별 확인
수정 범위
| 수정 유형 | 예시 | 위험 등급 |
|---|---|---|
| 구조 조정 | 단일 파일을 디렉토리로 분할 | 저 |
| 설명 재작성 | Load when...으로 변경 | 중 |
| 내용 삭제 | 모델이 이미 아는 내용 삭제 | 고 |
| 버전 동기화 | version/last_updated 업데이트 | 저 |
| 형식 표준화 | frontmatter 보완 | 저 |
수정 절차
감사 → 문제 나열 → 위험 분류 → 사용자 확인 → 자동 수정 → 2차 감사 → 결과 보고
수정 후 검증
- 자동 2차 감사 실행
- 수정 전후 점수 비교
- 수정 보고서 생성 (무엇을, 왜 변경했는지, 점수 변화)
감사 절차
입력
사용자 제공:
- Skill 디렉토리 경로, 또는
- SKILL.md 내용
출력
감사 보고서 생성:
## 감사 보고서: {skill-name}
### 구조 감사
- [PASS/WARN/FAIL] 디렉토리 구조
- [PASS/WARN/FAIL] 파일 크기
- [PASS/WARN/FAIL] 계층 깊이
### 내용 감사
- [PASS/WARN/FAIL] Description 작성 방식
- [PASS/WARN/FAIL] 모델이 이미 아는 내용 탐지
- [PASS/WARN/FAIL] 신호 밀도
### 버전 관리
- [PASS/WARN/FAIL] 버전 번호 형식
- [PASS/WARN/FAIL] 동기화 상태
### 총점: {X}/100
### 제안: {priority actions}
안티패턴 탐지 목록
구조 안티패턴
- 단일 파일 비대화 (> 50KB)
- Description 너무 긺 (> 100 tokens)
- 계층 없음 (> 50개 주제가 평면적으로 나열)
- 버전 관리 없음
내용 안티패턴
- 모델이 이미 아는 내용 (기본 개념 설명)
- 과도한 엔지니어링 (실제 필요보다 많은 추상화 계층)
- 절차적 실행 (완성된 제품 품질보다 규칙 준수에 집중)
- 검증 기준 없음
yinyo 특유의 문제점
- 버전 롤백 망설임 (품질 저하 시 즉시 롤백하지 않음)
- 절차가 완전할수록 품질이 낮아짐 (yinyo-writer 교훈)
- 단일 파일 277KB (yinyo-liuyao 교훈)
수정 제안 템플릿
단일 파일 비대화 → 분할
원본: SKILL.md (277KB)
변경:
├── SKILL.md (5KB: 핵심 규칙)
├── docs/
│ ├── rules.md (50KB: 120개 규칙)
│ ├── examples.md (100KB: 412개 괘 예시)
│ └── reference.md (30KB: 64괘 납갑표)
└── subskills/
├── edge-case-1.md
└── edge-case-2.md
Description 오류 → 수정
❌ "This Skill helps you write articles."
✅ "Load when the user needs to write a WeChat public account article."
빠른 참조
Skill 명명 규칙
yinyo-{domain}-{action}
파일 크기
- Index: < 1KB
- Body: < 50KB
- Runtime: 무제한
버전 관리
- SemVer: MAJOR.MINOR.PATCH
- 업데이트마다 동기화: SKILL.md + README.md + Git commit + memory
수정 트리거 단어
- "이 Skill 수정해줘" → 대화형 수정 모드 진입
- "자동 수정" → 저위험 수정 실행
- "고쳐줘" → 수정 제안 표시, 확인 대기