@p.e.c/boaz-skills 1.3.0

package/README.md

@@ -0,0 +1,41 @@
+# boaz-skills
+
+AI 코딩 도구용 스킬 모음. Claude Code에서 바로 사용 가능합니다.
+
+## 설치
+
+```bash
+npx boaz-skills
+```
+
+대화형 선택 화면에서 원하는 스킬을 골라 설치합니다.
+
+### 전체 설치
+
+```bash
+npx boaz-skills --all
+```
+
+### 스킬 목록 확인
+
+```bash
+npx boaz-skills --list
+```
+
+## 포함된 스킬
+
+| 스킬 | 설명 |
+|------|------|
+| **visualize-notion** | 노션 문서 작성 시 Mermaid, Callout, Table 등 시각화 도구 활용 가이드 |
+| **debug** | Kernighan/Pike/Feathers/Gregg 방법론 기반 체계적 디버깅 워크플로우 |
+| **read-hwp** | HWP(한글) 파일을 hwp5html로 텍스트 변환하는 파이프라인 |
+
+## 지원 도구
+
+- Claude Code (`~/.claude/skills/`)
+- Codex (예정)
+- Gemini (예정)
+
+## 라이선스
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import prompts from 'prompts';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+
+const SKILL_META = {
+  'visualize-notion': {
+    name: 'visualize-notion',
+    description: '노션 문서 작성 시 Mermaid, Callout, Table 등 시각화 도구 활용 가이드',
+  },
+  'debug': {
+    name: 'debug',
+    description: 'Kernighan/Pike/Feathers/Gregg 방법론 기반 체계적 디버깅 워크플로우',
+  },
+  'read-hwp': {
+    name: 'read-hwp',
+    description: 'HWP(한글) 파일을 hwp5html로 텍스트 변환하는 파이프라인',
+  },
+  'modify-hwpx': {
+    name: 'modify-hwpx',
+    description: 'HWPX(한글) 파일 수정 — @p.e.c/hwpx-mcp MCP 서버 기반 편집',
+  },
+};
+
+const TARGETS = {
+  'claude-code': {
+    label: 'Claude Code',
+    dir: path.join(os.homedir(), '.claude', 'skills'),
+    detect: () => fs.existsSync(path.join(os.homedir(), '.claude')),
+  },
+  'codex': {
+    label: 'Codex CLI',
+    dir: path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills'),
+    detect: () => fs.existsSync(process.env.CODEX_HOME || path.join(os.homedir(), '.codex')),
+  },
+  'gemini': {
+    label: 'Gemini CLI',
+    dir: path.join(os.homedir(), '.gemini', 'skills'),
+    detect: () => fs.existsSync(path.join(os.homedir(), '.gemini')),
+  },
+};
+
+function getAvailableSkills() {
+  return fs.readdirSync(SKILLS_DIR).filter(name => {
+    const skillPath = path.join(SKILLS_DIR, name, 'SKILL.md');
+    return fs.existsSync(skillPath);
+  });
+}
+
+function copySkill(skillName, targetDir) {
+  const src = path.join(SKILLS_DIR, skillName);
+  const dest = path.join(targetDir, skillName);
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  console.log('');
+  console.log('  ⚡ @boaz/skills');
+  console.log('  AI 코딩 도구용 스킬 설치기');
+  console.log('');
+
+  const availableSkills = getAvailableSkills();
+
+  // --list: 스킬 목록 출력
+  if (args.includes('--list')) {
+    console.log('  사용 가능한 스킬:');
+    for (const skill of availableSkills) {
+      const meta = SKILL_META[skill];
+      console.log(`    - ${skill}: ${meta?.description || ''}`);
+    }
+    console.log('');
+    process.exit(0);
+  }
+
+  // 설치 대상 감지
+  const detectedTargets = Object.entries(TARGETS)
+    .filter(([, t]) => t.detect())
+    .map(([key, t]) => ({ key, ...t }));
+
+  if (detectedTargets.length === 0) {
+    console.log('  ⚠ 지원되는 AI 코딩 도구를 찾을 수 없습니다.');
+    console.log('  지원 도구: Claude Code (~/.claude/), Codex CLI (~/.codex/), Gemini CLI (~/.gemini/)');
+    process.exit(1);
+  }
+
+  console.log(`  감지된 도구: ${detectedTargets.map(t => t.label).join(', ')}`);
+  console.log('');
+
+  // --all: 전체 설치 (대화형 건너뛰기)
+  const installAll = args.includes('--all');
+
+  // 설치 대상 도구 선택
+  let selectedTargets;
+
+  if (installAll || detectedTargets.length === 1) {
+    selectedTargets = detectedTargets;
+  } else {
+    const targetChoices = detectedTargets.map(t => ({
+      title: t.label,
+      value: t,
+      selected: true,
+    }));
+
+    const targetResponse = await prompts({
+      type: 'multiselect',
+      name: 'targets',
+      message: '설치할 도구를 선택하세요 (Space로 토글, Enter로 확인)',
+      choices: targetChoices,
+      hint: '- 방향키로 이동, Space로 선택/해제',
+      instructions: false,
+    });
+
+    if (!targetResponse.targets || targetResponse.targets.length === 0) {
+      console.log('  선택된 도구가 없습니다. 종료합니다.');
+      process.exit(0);
+    }
+
+    selectedTargets = targetResponse.targets;
+  }
+
+  let selectedSkills;
+
+  if (installAll) {
+    selectedSkills = availableSkills;
+  } else {
+    const choices = availableSkills.map(skill => ({
+      title: skill,
+      description: SKILL_META[skill]?.description || '',
+      value: skill,
+      selected: true,
+    }));
+
+    const response = await prompts({
+      type: 'multiselect',
+      name: 'skills',
+      message: '설치할 스킬을 선택하세요 (Space로 토글, Enter로 확인)',
+      choices,
+      hint: '- 방향키로 이동, Space로 선택/해제',
+      instructions: false,
+    });
+
+    if (!response.skills || response.skills.length === 0) {
+      console.log('  선택된 스킬이 없습니다. 종료합니다.');
+      process.exit(0);
+    }
+
+    selectedSkills = response.skills;
+  }
+
+  // 설치 실행
+  for (const target of selectedTargets) {
+    // 디렉토리 생성
+    fs.mkdirSync(target.dir, { recursive: true });
+
+    for (const skill of selectedSkills) {
+      const destPath = path.join(target.dir, skill);
+      const exists = fs.existsSync(destPath);
+
+      if (exists && !installAll) {
+        const { overwrite } = await prompts({
+          type: 'confirm',
+          name: 'overwrite',
+          message: `${skill}이(가) 이미 설치되어 있습니다. 덮어쓸까요?`,
+          initial: true,
+        });
+
+        if (!overwrite) {
+          console.log(`  ⏭ ${skill} 건너뜀`);
+          continue;
+        }
+      }
+
+      copySkill(skill, target.dir);
+      console.log(`  ✓ ${skill} → ${target.label}`);
+    }
+  }
+
+  console.log('');
+  console.log('  설치 완료!');
+  console.log('');
+}
+
+main().catch(err => {
+  console.error('오류:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@p.e.c/boaz-skills",
+  "version": "1.3.0",
+  "description": "AI 코딩 도구용 스킬 모음 (Claude Code, Codex, Gemini)",
+  "type": "module",
+  "bin": {
+    "boaz-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "skills",
+    "ai-coding",
+    "notion",
+    "debugging",
+    "hwp",
+    "hwpx",
+    "hwpx-mcp"
+  ],
+  "author": "Boaz",
+  "license": "MIT",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/skills/debug/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: debug
+description: 'Systematic debugging workflow based on Kernighan, Pike, Feathers, and Gregg methodologies. Activates on keywords: debug, bug, error, issue, troubleshoot, crash, fix, broken'
+---
+
+# Systematic Debugging
+
+> "Debugging is twice as hard as writing the code in the first place." — Brian Kernighan
+
+## The Two Schools of Debugging
+
+| School | Core Question | Method | Masters |
+|--------|--------------|--------|---------|
+| **Symptom Tracing** | What is broken? | Logs, tracing, observability | Pike / Gregg |
+| **Root Cause Elimination** | Why did it break? | Minimal reproduction, hypothesis, experiment | Kernighan / Feathers |
+
+**Key Insight**: Master debuggers combine both approaches.
+
+---
+
+## Universal Debugging Protocol (UDP)
+
+```
+1. STOP      → Define the problem clearly (expected vs actual)
+2. REPRODUCE → Create minimal, reliable reproduction
+3. OBSERVE   → Collect evidence (logs, state, traces)
+4. HYPOTHESIZE → Form testable hypothesis (max 3)
+5. TEST      → Change ONE thing, observe result
+6. FIX       → Apply minimal fix
+7. VERIFY    → Confirm fix, run regression tests
+8. DOCUMENT  → Record cause, solution, lessons learned
+```
+
+---
+
+## Kernighan's 9 Indispensable Rules
+
+1. **Understand the system** — Read before debug
+2. **Make it fail** — Reproducibility is everything
+3. **Quit thinking and look** — Observe, don't assume
+4. **Divide and conquer** — Binary search the problem space
+5. **Change one thing at a time** — Isolate variables
+6. **Keep an audit trail** — Log everything you try
+7. **Check the plug** — Verify the obvious first
+8. **Get a fresh view** — Rubber duck, colleague, or sleep on it
+9. **If you didn't fix it, it isn't fixed** — Verify ruthlessly
+
+---
+
+## Gregg's Observability Principles
+
+### USE Method (for resources)
+- **U**tilization: How busy is the resource?
+- **S**aturation: How much work is queued?
+- **E**rrors: Are there error events?
+
+### RED Method (for services)
+- **R**ate: Requests per second
+- **E**rrors: Failed requests
+- **D**uration: Latency distribution
+
+### Flame Graphs
+Visualize CPU/memory hotspots. Stack depth = call chain, width = time spent.
+
+---
+
+## Feathers' Legacy Code Approach
+
+When debugging unfamiliar or legacy code:
+
+1. **Seam** — Find a point to insert observation/tests
+2. **Cover** — Add characterization test (capture current behavior)
+3. **Change** — Modify with safety net
+4. **Refactor** — Clean up after fixing
+
+---
+
+## Anti-Patterns to Avoid
+
+| Don't | Do Instead |
+|-------|------------|
+| Change multiple things at once | Change ONE thing, observe |
+| Fix without understanding | Understand root cause first |
+| Skip reproduction step | Build reliable repro case |
+| Debug in production | Reproduce locally if possible |
+| Trust "works on my machine" | Check environment differences |
+| Guess without data | Observe and measure first |
+
+---
+
+## Claude Interaction Protocol
+
+When helping with debugging, follow this workflow:
+
+### Phase 1: Problem Definition
+
+```
+1. ASK: "What is the expected behavior vs actual behavior?"
+2. ASK: "When did this start? Any recent changes?"
+3. ASK: "Is it reproducible? Steps to reproduce?"
+4. CREATE: debug_notes.md to track investigation
+```
+
+### Phase 2: Reproduction
+
+```
+1. ATTEMPT: Reproduce the issue
+2. DOCUMENT: Steps to reproduce in debug_notes.md
+3. SIMPLIFY: Find minimal reproduction case
+4. IDENTIFY: Consistent vs intermittent failure
+```
+
+### Phase 3: Investigation
+
+```
+1. OBSERVE: Gather logs, errors, stack traces
+2. HYPOTHESIZE: Form at most 3 hypotheses
+3. TEST: Each hypothesis with ONE change at a time
+4. RECORD: Every attempt in debug_notes.md
+5. NARROW: Use divide-and-conquer to isolate
+```
+
+### Phase 4: Resolution
+
+```
+1. FIX: Apply minimal fix
+2. VERIFY: Confirm fix works
+3. REGRESS: Check for side effects
+4. PREVENT: Add test if appropriate
+5. SUMMARIZE: Root cause and solution in debug_notes.md
+```
+
+---
+
+## debug_notes.md Template
+
+Create this file to track debugging investigations:
+
+```markdown
+# Debug Notes: [Issue Description]
+
+## Problem Statement
+- **Expected**: [what should happen]
+- **Actual**: [what happens]
+- **Severity**: [critical/high/medium/low]
+- **First observed**: [when]
+
+## Environment
+- OS:
+- Version:
+- Dependencies:
+
+## Reproduction Steps
+1. [step]
+2. [step]
+3. [observe failure]
+
+## Hypotheses
+- [ ] H1: [hypothesis] — [how to test]
+- [ ] H2: [hypothesis] — [how to test]
+- [ ] H3: [hypothesis] — [how to test]
+
+## Investigation Log
+
+| Time | Action | Result | Next Step |
+|------|--------|--------|-----------|
+| | | | |
+
+## Root Cause
+[Explanation of why the bug occurred]
+
+## Solution
+[What was changed and why]
+
+## Prevention
+[How to prevent similar issues: tests, guards, docs]
+```
+
+---
+
+## Quick Decision Tree
+
+```
+Problem reported
+    │
+    ▼
+Can reproduce? ─No──▶ Get more info (logs, environment)
+    │
+   Yes
+    │
+    ▼
+Recent change? ─Yes──▶ Check diff, rollback test
+    │
+    No
+    │
+    ▼
+Obvious cause? ─Yes──▶ Verify with minimal test
+    │
+    No
+    │
+    ▼
+Divide and conquer
+    │
+    ▼
+Isolate component
+    │
+    ▼
+Form hypothesis (max 3)
+    │
+    ▼
+Test ONE change at a time
+    │
+    ▼
+Fix → Verify → Document
+```
+
+---
+
+## Domain-Specific Checklists
+
+See [checklists.md](checklists.md) for:
+- Streaming/Buffer Issues
+- BLE/UART Communication
+- AI Inference Bottlenecks
+- System Observability
+- Network/API Issues
+- Memory/Crash Issues
+- App Debugging
+- Web Debugging
+
+## Tool Reference
+
+See [reference.md](reference.md) for tool commands and recipes.