@kood/claude-code 0.1.9 → 0.1.11

package/templates/hono/docs/skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable zip file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a zip file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the zip file (defaults to current directory)
+
+    Returns:
+        Path to the created zip file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    zip_filename = output_path / f"{skill_name}.zip"
+
+    # Create the zip file
+    try:
+        with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {zip_filename}")
+        return zip_filename
+
+    except Exception as e:
+        print(f"❌ Error creating zip file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/hono/docs/skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+from pathlib import Path
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+    
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+    
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+    
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+    
+    frontmatter = match.group(1)
+    
+    # Check required fields
+    if 'name:' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description:' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+    
+    # Extract name for validation
+    name_match = re.search(r'name:\s*(.+)', frontmatter)
+    if name_match:
+        name = name_match.group(1).strip()
+        # Check naming convention (hyphen-case: lowercase with hyphens)
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+
+    # Extract and validate description
+    desc_match = re.search(r'description:\s*(.+)', frontmatter)
+    if desc_match:
+        description = desc_match.group(1).strip()
+        # Check for angle brackets
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+
+    return True, "Skill is valid!"
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+    
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

package/templates/npx/docs/commands/docs-creator.md

@@ -0,0 +1,239 @@
+---
+description: Claude Code 문서 작성 가이드. CLAUDE.md, SKILL.md 등 효과적인 문서 작성 시 사용.
+---
+
+# Docs Creator
+
+Claude Code 문서 작성 베스트 프랙티스 가이드.
+
+## 핵심 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| **간결함** | 컨텍스트 윈도우는 공공재. 모든 토큰이 비용 |
+| **점진적 공개** | 핵심만 메인 파일에, 상세는 참조 파일로 분리 |
+| **보편적 적용** | 모든 세션에 필요한 정보만 포함 |
+
+## 문서 유형별 가이드
+
+| 문서 | 권장 길이 | 용도 |
+|------|----------|------|
+| CLAUDE.md | 60-200줄 | 프로젝트 전역 설정, 컨벤션 |
+| SKILL.md | 500줄 이하 | 특화 워크플로우, 도구 사용법 |
+| references/ | 무제한 | 상세 API 문서, 스키마 등 |
+
+**지침 개수 한계**: 150-200개 (Claude Code 자체 ~50개 사용)
+
+## 구조 템플릿
+
+### CLAUDE.md
+
+```markdown
+# 프로젝트명
+
+## 개요
+프로젝트 목적 (1-2문장)
+
+## 기술 스택
+- 프레임워크: X
+- 언어: Y
+- DB: Z
+
+## 명령어
+| 명령 | 설명 |
+|------|------|
+| `yarn dev` | 개발 서버 |
+| `yarn test` | 테스트 실행 |
+
+## 컨벤션
+- 파일명: kebab-case
+- 함수: const 화살표 함수
+- 타입: interface (객체), type (유니온)
+
+## 워크플로우
+기능 추가 → 테스트 → 린트 → 커밋
+```
+
+### SKILL.md
+
+```markdown
+---
+name: skill-name
+description: 무엇을 하는지 + 언제 사용하는지. (scope)
+---
+
+# Skill Name
+
+스킬 목적 (2-3문장)
+
+## 사용 시점
+- 조건 1
+- 조건 2
+
+## 사용 방법
+
+### 기본 워크플로우
+1. 단계 1
+2. 단계 2
+
+### 참조
+- 상세 API: [references/api.md](references/api.md)
+- 스키마: [references/schema.md](references/schema.md)
+```
+
+## Progressive Disclosure
+
+```
+project/
+├── CLAUDE.md           # 핵심만 (60-200줄)
+├── docs/
+│   ├── api.md          # API 상세
+│   └── architecture.md # 아키텍처
+└── .claude/skills/
+    └── my-skill/
+        ├── SKILL.md        # 개요 (<500줄)
+        └── references/     # 상세 정보
+```
+
+**토큰 로드 단계:**
+
+| 단계 | 내용 | 크기 |
+|------|------|------|
+| 1. 메타데이터 | name + description | 30-50 토큰 |
+| 2. 활성화 | SKILL.md 본문 | <5k 단어 |
+| 3. 참조 | 번들 리소스 | 필요 시만 |
+
+## 작성 규칙
+
+### DO
+
+- 불릿 포인트 + 짧은 문장
+- 코드 예시 중심
+- 표로 정보 구조화
+- 강조: `IMPORTANT:`, `YOU MUST:`
+- 1단계 깊이 참조 (A→B ✅, A→B→C ❌)
+
+### DON'T
+
+- 긴 서술형 문단
+- Claude가 아는 것 설명
+- 린터 역할 강요 (도구 사용)
+- 시간 의존적 정보
+- /init 자동 생성 의존
+
+## Description 작성
+
+SKILL.md의 description은 스킬 발견에 핵심.
+
+```yaml
+# Good - 구체적 + 트리거 포함
+description: PDF에서 텍스트/표 추출, 폼 작성. PDF 작업 시 사용.
+
+# Bad - 모호함
+description: 문서 처리
+```
+
+**규칙:**
+- 3인칭 작성 (시스템 프롬프트에 주입됨)
+- 무엇을 하는지 + 언제 사용하는지
+- 구체적 키워드 포함
+
+## Context 관리
+
+| 명령어 | 용도 | 시점 |
+|--------|------|------|
+| `/compact` | 컨텍스트 요약 | 70% 도달 |
+| `/clear` | 세션 초기화 | 새 기능 시작 |
+| `/resume` | 세션 복원 | 작업 재개 |
+
+**주의:** 마지막 20%는 복잡한 작업 피할 것
+
+## Subagent 활용
+
+문서 작성 시 subagent를 적극 활용하여 메인 컨텍스트 보호.
+
+### Subagent 종류
+
+| 타입 | 용도 | 문서 작성 활용 |
+|------|------|---------------|
+| `Explore` | 코드베이스 탐색 | 프로젝트 구조 파악, 패턴 분석 |
+| `Plan` | 구현 계획 수립 | 문서 구조 설계, 섹션 계획 |
+| `general-purpose` | 범용 조사 | 베스트 프랙티스 조사, 예시 수집 |
+
+### 활용 시점
+
+**CLAUDE.md 작성 시:**
+```
+1. Explore agent → 프로젝트 구조/기술 스택 파악
+2. Explore agent → 기존 컨벤션/패턴 분석
+3. 메인 에이전트 → 요약 기반 문서 작성
+```
+
+**SKILL.md 작성 시:**
+```
+1. Explore agent → 관련 코드/워크플로우 분석
+2. Plan agent → 스킬 구조 설계
+3. 메인 에이전트 → 설계 기반 작성
+```
+
+### 효과
+
+| 방식 | 컨텍스트 사용 |
+|------|--------------|
+| 직접 탐색 | 전체 파일 내용 로드 |
+| Subagent | 요약만 반환 → 90%+ 절약 |
+
+### 프롬프트 예시
+
+```
+Explore agent에게:
+"프로젝트 구조와 기술 스택을 분석하고,
+CLAUDE.md에 포함할 핵심 정보만 요약해줘.
+- 디렉토리 구조
+- 주요 의존성
+- 빌드/테스트 명령어
+- 코드 컨벤션"
+```
+
+```
+Plan agent에게:
+"이 스킬의 SKILL.md 구조를 설계해줘.
+- 스킬 목적
+- 주요 섹션
+- 참조 파일 분리 계획
+- 워크플로우 단계"
+```
+
+## 체크리스트
+
+### CLAUDE.md
+
+- [ ] 60-200줄 이내
+- [ ] 기술 스택 명시
+- [ ] 주요 명령어 포함
+- [ ] 컨벤션 정리
+- [ ] 민감 정보 제외
+
+### SKILL.md
+
+- [ ] 500줄 이하
+- [ ] description 구체적 (무엇 + 언제)
+- [ ] 3인칭 작성
+- [ ] 참조 1단계 깊이
+- [ ] 100줄+ 파일은 목차 포함
+- [ ] 워크플로우에 체크리스트
+
+### 공통
+
+- [ ] 간결한 작성
+- [ ] 코드 예시 포함
+- [ ] 표로 구조화
+- [ ] 시간 의존 정보 없음
+- [ ] Subagent로 사전 조사 완료
+- [ ] 테스트 완료
+
+## 참조
+
+- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [Using CLAUDE.MD files](https://claude.com/blog/using-claude-md-files)
+- [Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

package/templates/npx/docs/commands/docs-refactor.md

@@ -0,0 +1,168 @@
+---
+description: Claude Code 문서 리팩토링 가이드. 기존 CLAUDE.md, SKILL.md 개선 시 사용.
+---
+
+# Docs Refactor
+
+기존 Claude Code 문서를 베스트 프랙티스에 맞게 개선하는 가이드.
+
+## 리팩토링 필요 신호
+
+| 신호 | 문제 | 우선순위 |
+|------|------|---------|
+| 200줄+ CLAUDE.md | 컨텍스트 과부하 | 높음 |
+| 500줄+ SKILL.md | 로딩 지연, 품질 저하 | 높음 |
+| Claude가 지침 무시 | 과도한 지침 (150+개) | 높음 |
+| 중첩 참조 (A→B→C) | 불완전한 파일 읽기 | 중간 |
+| 코드 스타일 지침 | 린터 역할 강요 | 중간 |
+| 시간 의존 정보 | 오래된 지침 | 낮음 |
+
+## 분석 워크플로우
+
+### 1단계: Subagent로 현황 분석
+
+```
+Explore agent에게:
+"현재 CLAUDE.md/SKILL.md를 분석하고 보고해줘:
+- 총 줄 수
+- 섹션별 줄 수
+- 지침 개수 (명령형 문장)
+- 중첩 참조 깊이
+- 린터 역할 지침 여부
+- 시간 의존 정보 여부"
+```
+
+### 2단계: 개선 계획 수립
+
+```
+Plan agent에게:
+"분석 결과를 바탕으로 리팩토링 계획 수립:
+- 삭제할 내용
+- 분리할 내용 (references/)
+- 병합할 섹션
+- 추가할 내용"
+```
+
+### 3단계: 리팩토링 실행
+
+메인 에이전트가 계획 기반으로 문서 수정.
+
+## 안티패턴 → 개선 패턴
+
+### 길이 문제
+
+| Before | After |
+|--------|-------|
+| 300줄 CLAUDE.md | 60-200줄 + docs/ 분리 |
+| 800줄 SKILL.md | 500줄 이하 + references/ 분리 |
+
+**분리 기준:**
+- 모든 세션에 필요 → 메인 파일
+- 특정 작업에만 필요 → 참조 파일
+
+### 구조 문제
+
+| Before | After |
+|--------|-------|
+| 긴 서술형 문단 | 불릿 포인트 + 짧은 문장 |
+| 중첩 참조 (A→B→C) | 1단계 깊이 (A→B) |
+| 목차 없는 100줄+ 파일 | 상단에 목차 추가 |
+
+### 내용 문제
+
+| Before | After |
+|--------|-------|
+| 코드 스타일 가이드 | 삭제 (Biome/ESLint 사용) |
+| Claude가 아는 설명 | 삭제 |
+| 시간 의존 정보 | "old patterns" 섹션으로 이동 |
+| 너무 많은 옵션 | 기본값 + 대안 1개 |
+
+**삭제 예시:**
+```markdown
+# Before - 불필요한 설명
+PDF (Portable Document Format)는 Adobe에서 개발한
+문서 형식으로, 텍스트와 이미지를 포함할 수 있습니다...
+
+# After - 핵심만
+PDF 텍스트 추출: `pdfplumber.open("file.pdf")`
+```
+
+### Description 문제
+
+| Before | After |
+|--------|-------|
+| `description: 문서 처리` | `description: PDF 텍스트/표 추출. PDF 작업 시 사용.` |
+| 1인칭/2인칭 | 3인칭 작성 |
+| 트리거 없음 | 구체적 트리거 포함 |
+
+## 분리 전략
+
+### 참조 파일로 분리할 내용
+
+| 내용 | 분리 위치 |
+|------|----------|
+| API 상세 문서 | `references/api.md` |
+| 스키마 정의 | `references/schema.md` |
+| 예시 모음 | `references/examples.md` |
+| 도메인별 가이드 | `references/{domain}.md` |
+
+### 분리 후 메인 파일 참조
+
+```markdown
+## API 사용
+
+기본 호출: `api.call(params)`
+
+**상세 API 문서**: [references/api.md](references/api.md)
+```
+
+## Subagent 활용
+
+| 단계 | Agent | 작업 |
+|------|-------|------|
+| 분석 | Explore | 현황 파악, 문제점 식별 |
+| 계획 | Plan | 리팩토링 전략 수립 |
+| 검증 | Explore | 개선 결과 확인 |
+
+### 검증 프롬프트
+
+```
+Explore agent에게:
+"리팩토링된 문서 검증:
+- 줄 수 목표 달성?
+- 지침 개수 150개 이하?
+- 중첩 참조 1단계?
+- 필수 정보 누락 없음?"
+```
+
+## 체크리스트
+
+### 분석 단계
+
+- [ ] Subagent로 현황 분석 완료
+- [ ] 문제점 목록 작성
+- [ ] 개선 우선순위 결정
+
+### 리팩토링 단계
+
+- [ ] 불필요한 설명 삭제
+- [ ] 코드 스타일 지침 삭제
+- [ ] 긴 내용 참조 파일로 분리
+- [ ] 중첩 참조 1단계로 평탄화
+- [ ] 100줄+ 파일에 목차 추가
+- [ ] Description 개선 (3인칭, 트리거)
+
+### 검증 단계
+
+- [ ] CLAUDE.md 60-200줄
+- [ ] SKILL.md 500줄 이하
+- [ ] 지침 개수 150개 이하
+- [ ] 참조 1단계 깊이
+- [ ] 필수 정보 유지 확인
+- [ ] 테스트 완료
+
+## 참조
+
+- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [Using CLAUDE.MD files](https://claude.com/blog/using-claude-md-files)
+- [Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

package/templates/npx/docs/commands/git-all.md

@@ -0,0 +1,83 @@
+---
+description: 모든 변경사항 커밋 후 푸시
+allowed-tools: Bash(git:*)
+---
+
+모든 변경사항을 논리적 단위로 분리하여 전부 커밋 후 푸시.
+
+## 실행 흐름
+
+```
+1. git status + git diff (병렬 실행)
+2. 논리적 단위로 분리하여 git add + git commit (반복)
+3. git status (완료 확인 - 남은 변경 없어야 함)
+4. git push
+```
+
+## 병렬 실행
+
+**초기 분석 단계에서 병렬 실행 필수:**
+
+```bash
+# 동시에 실행 (두 Bash 호출을 하나의 응답에서)
+git status
+git diff
+```
+
+## CRITICAL: 절대 금지
+
+| 금지 항목 |
+|----------|
+| "Generated with Claude Code" 포함 |
+| "🤖" 또는 AI 관련 이모지 |
+| "Co-Authored-By:" 헤더 |
+| AI/봇 작성 표시 일체 |
+| 여러 줄 커밋 메시지 |
+| 커밋 메시지에 마침표(.) |
+| 여러 작업 하나로 퉁치기 |
+| 변경사항 남겨두기 |
+
+## 커밋 규칙
+
+**형식**: `<prefix>: <설명>` (한 줄, 본문/푸터 없음)
+
+**핵심 원칙**: 하나의 커밋 = 하나의 논리적 변경
+
+### Prefix
+
+| Prefix | 용도 |
+|--------|------|
+| feat | 새 기능 |
+| fix | 버그 수정 |
+| refactor | 리팩토링 |
+| style | 코드 스타일 |
+| docs | 문서 수정 |
+| test | 테스트 |
+| chore | 빌드/설정 |
+| perf | 성능 개선 |
+| ci | CI/CD |
+
+### 분리 기준
+
+| 분리 필요 | 묶어도 됨 |
+|----------|----------|
+| 서로 다른 기능 | 동일 기능의 관련 파일들 |
+| 버그 수정 + 새 기능 | 동일 기능의 타입 + 구현 |
+| 코드 변경 + 문서 변경 | |
+| 리팩토링 + 기능 추가 | |
+
+## 예시
+
+```bash
+# ✅ 올바른
+feat: 사용자 로그인 기능 추가
+fix: 세션 만료 오류 수정
+refactor: 서비스 클래스 구조 개선
+
+# ❌ 잘못된
+사용자 인증 기능 추가함     # prefix 없음
+feat: 사용자 인증 추가.     # 마침표
+FEAT: 사용자 인증 추가      # 대문자
+feat(auth): 인증 추가       # scope 불필요
+feat: 로그인, 회원가입, 프로필  # 여러 작업 퉁침
+```