homunculus-code 0.1.0 → 0.3.0

package/bin/night.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// homunculus night — Run one evolution cycle
+// Simulates what the nightly agent does: health check → evolve → research → report
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const projectDir = process.cwd();
+const HOMUNCULUS_DIR = path.join(projectDir, 'homunculus');
+const ARCH_FILE = path.join(projectDir, 'architecture.yaml');
+const INSTINCTS_DIR = path.join(HOMUNCULUS_DIR, 'instincts', 'personal');
+const ARCHIVED_DIR = path.join(HOMUNCULUS_DIR, 'instincts', 'archived');
+const SKILLS_DIR = path.join(HOMUNCULUS_DIR, 'evolved', 'skills');
+const EVALS_DIR = path.join(HOMUNCULUS_DIR, 'evolved', 'evals');
+const OBS_FILE = path.join(HOMUNCULUS_DIR, 'observations.jsonl');
+const SCRIPTS_DIR = path.join(projectDir, 'scripts');
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+
+function countFiles(dir, ext = '.md') {
+  try {
+    return fs.readdirSync(dir).filter(f => f.endsWith(ext)).length;
+  } catch { return 0; }
+}
+
+function countLines(file) {
+  try {
+    return fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean).length;
+  } catch { return 0; }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function parseGoals(yamlContent) {
+  const goals = [];
+  const lines = yamlContent.split('\n');
+  let currentGoal = null;
+  let indent = 0;
+
+  for (const line of lines) {
+    // Match top-level goals (direct children of "goals:")
+    const goalMatch = line.match(/^    (\w+):$/);
+    if (goalMatch && !line.includes('purpose') && !line.includes('metrics') &&
+        !line.includes('health_check') && !line.includes('realized_by') &&
+        !line.includes('goals:') && !line.includes('command') &&
+        !line.includes('expected') && !line.includes('healthy') &&
+        !line.includes('name:') && !line.includes('source')) {
+      currentGoal = goalMatch[1];
+    }
+
+    const purposeMatch = line.match(/purpose:\s*"(.+)"/);
+    if (purposeMatch && currentGoal) {
+      goals.push({ name: currentGoal, purpose: purposeMatch[1] });
+      currentGoal = null;
+    }
+  }
+  return goals;
+}
+
+async function main() {
+  console.log('');
+  console.log(`  ${bold('🌙 Homunculus — Evolution Cycle')}`);
+  console.log(`  ${dim(new Date().toISOString().replace('T', ' ').slice(0, 19))}`);
+  console.log('');
+
+  // Check if initialized
+  if (!fs.existsSync(HOMUNCULUS_DIR)) {
+    console.log(`  ${red('✗')} Not initialized. Run ${bold('npx homunculus-code init')} first.`);
+    process.exit(1);
+  }
+
+  // ─────────────────────────────────────────
+  // Phase 1: Health Check
+  // ─────────────────────────────────────────
+  console.log(`  ${bold('[1/5] Health Check')}`);
+  await sleep(300);
+
+  if (fs.existsSync(ARCH_FILE)) {
+    const yaml = fs.readFileSync(ARCH_FILE, 'utf8');
+    const goals = parseGoals(yaml);
+
+    if (goals.length > 0) {
+      for (const goal of goals) {
+        // Simple heuristic: if realized_by exists and points to real file = healthy
+        const status = yellow('○ no data yet');
+        console.log(`        ${goal.name}: ${status}`);
+        console.log(`        ${dim(goal.purpose)}`);
+      }
+    } else {
+      console.log(`        ${yellow('○')} No goals defined in architecture.yaml`);
+    }
+  } else {
+    console.log(`        ${red('✗')} architecture.yaml not found`);
+  }
+
+  console.log('');
+  await sleep(200);
+
+  // ─────────────────────────────────────────
+  // Phase 2: Scan Instincts
+  // ─────────────────────────────────────────
+  console.log(`  ${bold('[2/5] Scan Instincts')}`);
+  await sleep(300);
+
+  const activeInstincts = countFiles(INSTINCTS_DIR);
+  const archivedInstincts = countFiles(ARCHIVED_DIR);
+  const observations = countLines(OBS_FILE);
+
+  if (activeInstincts > 0) {
+    console.log(`        ${green('✓')} ${activeInstincts} active instincts (${archivedInstincts} archived)`);
+
+    // Run prune check
+    try {
+      const pruneScript = path.join(SCRIPTS_DIR, 'prune-instincts.js');
+      if (fs.existsSync(pruneScript)) {
+        const result = execSync(`node "${pruneScript}"`, {
+          encoding: 'utf8', timeout: 10000, cwd: projectDir
+        });
+        const candidateMatch = result.match(/Candidates:\s*(\d+)/);
+        if (candidateMatch && parseInt(candidateMatch[1]) > 0) {
+          console.log(`        ${yellow('△')} ${candidateMatch[1]} instincts eligible for archival`);
+        }
+      }
+    } catch {}
+  } else if (observations > 0) {
+    console.log(`        ${yellow('○')} ${observations} observations recorded, no instincts extracted yet`);
+    console.log(`        ${dim('Tip: instincts are extracted at session end when enough patterns emerge')}`);
+  } else {
+    console.log(`        ${yellow('○')} No instincts yet — use Claude Code normally, patterns will emerge`);
+    console.log(`        ${dim('The observation hook is watching. Keep using Claude Code.')}`);
+  }
+
+  console.log('');
+  await sleep(200);
+
+  // ─────────────────────────────────────────
+  // Phase 3: Eval Skills
+  // ─────────────────────────────────────────
+  console.log(`  ${bold('[3/5] Eval Skills')}`);
+  await sleep(300);
+
+  const skillCount = countFiles(SKILLS_DIR);
+  const evalCount = countFiles(EVALS_DIR, '.yaml');
+
+  if (skillCount > 0) {
+    console.log(`        ${green('✓')} ${skillCount} evolved skills found`);
+
+    // List skills
+    try {
+      const skills = fs.readdirSync(SKILLS_DIR).filter(f => f.endsWith('.md'));
+      for (const skill of skills) {
+        const name = skill.replace('.md', '');
+        const hasEval = fs.existsSync(path.join(EVALS_DIR, `${name}.eval.yaml`));
+        if (hasEval) {
+          console.log(`          ${green('✓')} ${name} — has eval spec`);
+        } else {
+          console.log(`          ${yellow('○')} ${name} — no eval spec yet`);
+        }
+      }
+    } catch {}
+
+    if (evalCount > 0) {
+      console.log(`        ${dim(`Run 'claude "/eval-skill"' to evaluate, or let the nightly agent handle it`)}`);
+    }
+  } else {
+    console.log(`        ${yellow('○')} No skills yet — instincts converge into skills over time`);
+    console.log(`        ${dim(`Once you have 3+ related instincts, run 'claude "/evolve"'`)}`);
+  }
+
+  console.log('');
+  await sleep(200);
+
+  // ─────────────────────────────────────────
+  // Phase 4: Research
+  // ─────────────────────────────────────────
+  console.log(`  ${bold('[4/5] Research')}`);
+  await sleep(300);
+
+  // Check Claude Code version
+  try {
+    const version = execSync('claude --version 2>/dev/null', {
+      encoding: 'utf8', timeout: 5000
+    }).trim();
+    console.log(`        ${green('✓')} Claude Code ${version}`);
+  } catch {
+    console.log(`        ${yellow('○')} Claude Code version check skipped`);
+  }
+
+  // Check Node version
+  const nodeVersion = process.version;
+  console.log(`        ${green('✓')} Node.js ${nodeVersion}`);
+
+  // Check architecture health
+  if (fs.existsSync(ARCH_FILE)) {
+    const yaml = fs.readFileSync(ARCH_FILE, 'utf8');
+    const goalCount = (yaml.match(/purpose:/g) || []).length;
+    const healthChecks = (yaml.match(/health_check:/g) || []).length;
+    const realizedBy = (yaml.match(/realized_by:/g) || []).length;
+
+    if (healthChecks < goalCount / 2) {
+      console.log(`        ${yellow('△')} ${healthChecks}/${goalCount} goals have health checks — add more for better evolution`);
+    }
+    if (realizedBy < goalCount / 2) {
+      console.log(`        ${yellow('△')} ${realizedBy}/${goalCount} goals have implementations — some are waiting to evolve`);
+    }
+  }
+
+  console.log('');
+  await sleep(200);
+
+  // ─────────────────────────────────────────
+  // Phase 5: Report
+  // ─────────────────────────────────────────
+  console.log(`  ${bold('[5/5] Report')}`);
+  await sleep(300);
+
+  const reportDate = new Date().toISOString().slice(0, 10);
+  const reportLines = [];
+
+  console.log('');
+  console.log(`  ┌${'─'.repeat(52)}┐`);
+  console.log(`  │ ${bold(`  Evolution Report — ${reportDate}`)}              │`);
+  console.log(`  ├${'─'.repeat(52)}┤`);
+
+  // Summary
+  const goalCount = fs.existsSync(ARCH_FILE)
+    ? (fs.readFileSync(ARCH_FILE, 'utf8').match(/purpose:/g) || []).length
+    : 0;
+
+  console.log(`  │                                                    │`);
+  console.log(`  │  ${cyan('Goals:')}          ${String(goalCount).padStart(3)}                              │`);
+  console.log(`  │  ${cyan('Instincts:')}      ${String(activeInstincts).padStart(3)} active / ${String(archivedInstincts).padStart(3)} archived       │`);
+  console.log(`  │  ${cyan('Skills:')}          ${String(skillCount).padStart(3)} (${evalCount} with eval specs)          │`);
+  console.log(`  │  ${cyan('Observations:')}  ${String(observations).padStart(5)}                              │`);
+  console.log(`  │                                                    │`);
+
+  if (activeInstincts === 0 && skillCount === 0) {
+    console.log(`  │  ${bold('Status:')} Fresh install — ready to evolve          │`);
+    console.log(`  │                                                    │`);
+    console.log(`  │  ${dim('Next steps:')}                                      │`);
+    console.log(`  │  ${dim('1. Use Claude Code on your project')}                │`);
+    console.log(`  │  ${dim('2. Patterns will be auto-extracted')}                │`);
+    console.log(`  │  ${dim('3. Run this command again to see progress')}         │`);
+  } else if (skillCount === 0) {
+    console.log(`  │  ${bold('Status:')} Collecting patterns...                   │`);
+    console.log(`  │                                                    │`);
+    console.log(`  │  ${dim('You have instincts! When 3+ are related,')}         │`);
+    console.log(`  │  ${dim('run claude "/evolve" to create your first skill.')} │`);
+  } else {
+    console.log(`  │  ${bold('Status:')} ${green('Evolving')}                                  │`);
+    console.log(`  │                                                    │`);
+    console.log(`  │  ${dim('Run claude "/eval-skill" to check quality,')}       │`);
+    console.log(`  │  ${dim('or set up the nightly agent for autonomy.')}        │`);
+  }
+
+  console.log(`  │                                                    │`);
+  console.log(`  └${'─'.repeat(52)}┘`);
+  console.log('');
+
+  // Save report to file
+  const reportDir = path.join(HOMUNCULUS_DIR, 'reports');
+  if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+
+  const reportContent = [
+    `# Evolution Report — ${reportDate}`,
+    '',
+    '## Summary',
+    `- Goals: ${goalCount}`,
+    `- Instincts: ${activeInstincts} active / ${archivedInstincts} archived`,
+    `- Skills: ${skillCount} (${evalCount} with eval specs)`,
+    `- Observations: ${observations}`,
+    '',
+    `Generated by \`npx homunculus-code night\``,
+  ].join('\n');
+
+  fs.writeFileSync(path.join(reportDir, `${reportDate}.md`), reportContent + '\n');
+  console.log(`  ${dim(`Report saved to homunculus/reports/${reportDate}.md`)}`);
+  console.log('');
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/commands/hm-night.md

@@ -0,0 +1,86 @@
+# /hm-night — Run One Evolution Cycle
+
+Run the full evolution pipeline: health check → instincts → skills → research → report.
+
+## Behavior
+
+You are the Homunculus nightly evolution agent. Run through all 5 phases systematically.
+
+### Phase 1: Health Check
+
+1. Read `architecture.yaml`
+2. For each goal with a `health_check.command`, run it and report pass/fail
+3. For goals without health checks, check if `realized_by` points to an existing file
+4. Report:
+   ```
+   [1/5] Health Check
+         code_quality:    ✅ healthy (tests passing)
+         productivity:    ⚠️ no health check defined
+         knowledge:       ✅ healthy
+   ```
+
+### Phase 2: Scan Instincts
+
+1. Count files in `homunculus/instincts/personal/` and `homunculus/instincts/archived/`
+2. If instincts exist, check for pruning candidates (run `node scripts/prune-instincts.js` if it exists)
+3. Report count and any archival suggestions
+   ```
+   [2/5] Instincts
+         12 active / 5 archived
+         △ 2 candidates for archival (low confidence)
+   ```
+
+### Phase 3: Eval Skills
+
+1. List files in `homunculus/evolved/skills/`
+2. For each skill, check if an eval spec exists in `homunculus/evolved/evals/`
+3. If eval specs exist, run `/eval-skill` on each
+4. Report pass rates
+   ```
+   [3/5] Skills
+         ✓ tdd-workflow: 100% (8/8 scenarios)
+         △ debugging-patterns: 85% (6/7) — needs improvement
+   ```
+
+### Phase 4: Research
+
+1. Check Claude Code version
+2. Scan `architecture.yaml` for goals with no `realized_by` — these are opportunities
+3. Look for goals with failing health checks — these need attention
+4. Suggest improvements:
+   ```
+   [4/5] Research
+         ✓ Claude Code v2.1.81
+         △ 2 goals have no implementation yet
+         → Suggestion: code_quality.review could use a pre-commit hook
+   ```
+
+### Phase 5: Report
+
+Generate a summary report and save to `homunculus/reports/YYYY-MM-DD.md`:
+
+```
+[5/5] Evolution Report — 2026-03-22
+┌──────────────────────────────────────────┐
+│  Goals:      5 (3 healthy, 2 need work)  │
+│  Instincts:  12 active / 5 archived      │
+│  Skills:     3 (2 at 100%, 1 at 85%)     │
+│                                          │
+│  Actions taken:                          │
+│  - Pruned 2 outdated instincts           │
+│  - Improved debugging-patterns to v1.2   │
+│                                          │
+│  Suggestions:                            │
+│  - Add health check to productivity goal │
+│  - Review could use a pre-commit hook    │
+└──────────────────────────────────────────┘
+```
+
+## Important
+
+- Actually RUN health check commands (don't just read them)
+- Actually RUN eval-skill if eval specs exist (don't skip)
+- If a skill fails eval, attempt `/improve-skill` (max 2 rounds)
+- Save the report to `homunculus/reports/`
+- Be concise — this should feel like a progress dashboard, not an essay
+- If the system is fresh (no instincts/skills), give encouraging guidance

package/commands/hm-setup.md

@@ -0,0 +1,65 @@
+# /hm-setup — Set Up Your Goal Tree
+
+Guide the user through defining their goals and generate `architecture.yaml`.
+
+## Behavior
+
+You are helping the user set up Homunculus — a self-evolving AI assistant. Your job is to understand their project and goals, then generate a goal tree.
+
+### Step 1: Understand the Project
+
+Ask the user (conversationally, not a form):
+- What is this project? (e.g., SaaS app, CLI tool, personal project)
+- What do they spend most time on? (e.g., debugging, writing tests, deploying)
+- What frustrates them? (e.g., regressions, slow CI, repetitive tasks)
+- What would they improve if they had infinite time?
+
+Keep it natural — 2-3 questions max, adapt based on answers.
+
+### Step 2: Propose Goals
+
+Based on their answers, propose 3-5 goals with sub-goals. Present them clearly:
+
+```
+Based on what you told me, here's your goal tree:
+
+🎯 [Project Name]
+├── code_quality — Ship fewer bugs
+│   ├── testing — Every change has tests
+│   └── review — Catch issues before merge
+├── productivity — Move faster
+│   ├── automation — Automate repetitive work
+│   └── debugging — Find root causes faster
+└── knowledge — Stay up to date
+    └── tool_updates — Track useful updates
+```
+
+Ask: "Does this look right? Want to add, remove, or change anything?"
+
+### Step 3: Generate architecture.yaml
+
+Once confirmed, generate `architecture.yaml` with:
+- `purpose` for every goal
+- `metrics` where measurable (use reasonable defaults)
+- `health_check` where possible (shell commands that exit 0 = healthy)
+- `realized_by: # will evolve` for all implementations (the system will fill these in)
+
+Write the file using the Write tool.
+
+### Step 4: Confirm
+
+```
+✅ architecture.yaml created with N goals!
+
+Your system is ready to evolve. Use Claude Code normally —
+patterns will be auto-extracted. Run /hm-night anytime to
+trigger an evolution cycle.
+```
+
+## Important
+
+- Keep the conversation SHORT (under 5 back-and-forth)
+- Generate PRACTICAL goals, not abstract ones
+- Use the project's actual tech stack for health checks (e.g., `npm test`, `pytest`, `go test`)
+- Don't overwhelm — 3-5 top-level goals is ideal for a start
+- Goals can always be refined later

package/commands/hm-status.md

@@ -0,0 +1,47 @@
+# /hm-status — Evolution Status Dashboard
+
+Show the current state of the Homunculus evolution system.
+
+## Behavior
+
+Gather and display all evolution metrics in a compact dashboard.
+
+### Data to Collect
+
+1. **Goal Tree**: Read `architecture.yaml`, count goals and sub-goals
+2. **Instincts**: Count files in `homunculus/instincts/personal/` and `archived/`
+3. **Skills**: Count files in `homunculus/evolved/skills/`, note versions
+4. **Agents**: Count files in `homunculus/evolved/agents/`
+5. **Eval Specs**: Count files in `homunculus/evolved/evals/`
+6. **Observations**: Count lines in `homunculus/observations.jsonl`
+7. **Experiments**: Count files in `homunculus/experiments/`
+8. **Reports**: List recent reports in `homunculus/reports/`
+
+### Output Format
+
+```
+🧬 Homunculus Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Goal Tree:     5 goals / 12 sub-goals
+Instincts:     24 active / 8 archived
+Skills:        3 evolved (all 100% eval)
+Agents:        1 specialized
+Observations:  1,247 recorded
+Experiments:   2 completed / 1 queued
+
+Recent Skills:
+  ✓ tdd-workflow v1.2 — 100% (11 scenarios)
+  ✓ debugging-patterns v1.1 — 100% (8 scenarios)
+  ✓ shell-automation v1.0 — 100% (6 scenarios)
+
+Last Evolution: 2026-03-22
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Important
+
+- Use actual file counts, not hardcoded numbers
+- Keep output compact — one screen max
+- If the system is fresh, show zeros and next steps
+- Don't run any evaluations — just report current state

package/examples/reference/README.md

@@ -10,7 +10,19 @@ reference/
 ├── evolved-skills/            # 7 evolved skills (all 100% eval pass)
 │   ├── api-system-diagnosis.md
 │   ├── assistant-system-management.md
-│   ├── claude-code-reference.md
+│   ├── claude-code-reference/    # Split into index + 11 chapters (95% context reduction)
+│   │   ├── index.md              # Routing table — loads chapters on demand
+│   │   ├── ch01-extensions.md
+│   │   ├── ch02-agents.md
+│   │   ├── ch03-hooks.md
+│   │   ├── ch04-mcp.md
+│   │   ├── ch05-ui.md
+│   │   ├── ch06-rules-security.md
+│   │   ├── ch07-model-memory.md
+│   │   ├── ch08-workflows.md
+│   │   ├── ch09-integrations.md
+│   │   ├── ch10-cli-sdk.md
+│   │   └── ch11-output-versions.md
 │   ├── development-verification-patterns.md
 │   ├── multi-agent-design-patterns.md
 │   ├── shell-automation-patterns.md

package/examples/reference/evolved-skills/claude-code-reference/ch01-extensions.md

@@ -0,0 +1,98 @@
+# ch01: 擴展系統 + Built-in Tools + Skills 系統
+
+## 用途
+
+這個 skill 是 Claude Code 進階功能的快速參考。
+適用於設計自動化系統、設定助理架構、或討論 Claude Code 最佳實踐時。
+
+---
+
+## 1. 擴展系統：優先順序
+
+| 功能 | 適用情境 | Context 成本 |
+|------|----------|-------------|
+| CLAUDE.md | 永遠適用的規則（build commands、conventions）| 每次請求都載入 |
+| Skills | 按需知識、可觸發工作流（`/<name>`）| 低（描述每次；內容按需）|
+| Subagents | 隔離執行、平行任務、專用工作者 | 與主 session 隔離 |
+| Agent Teams | 多 session 協同（需互相溝通）| 高（每個 teammate 獨立費用）|
+| MCP | 外部服務連接（DB、Slack、browser）| 每次請求（工具定義）|
+| Hooks | 確定性腳本（lint、format、log）| **零**（外部執行，不進 context）|
+| Plugins | 跨專案打包分享（skills + hooks + MCP）| 同各組件 |
+
+**CLAUDE.md 大小指南**：目標 < 200 行（最多 ~500 行）。超過就把參考資料移到 Skills（按需載入）。
+
+**Skills `disable-model-invocation: true`**：完全隱藏於 Claude，context 成本為零，直到你手動 `/invoke` — 適合有副作用或只想自己觸發的 skill。
+
+**MCP 靜默斷線**：MCP server 中途斷線不會報警，工具直接消失。若發現 MCP 工具突然不可用 → 執行 `/mcp` 確認連線狀態。
+
+## Built-in Tools 分類
+
+| 類別 | 工具 |
+|------|------|
+| 檔案操作 | Read, Edit, Write（Create/Rename）|
+| 搜尋 | Glob（按名稱）、Grep（按內容）|
+| 執行 | Bash、Git |
+| Web | WebSearch、WebFetch |
+| Code Intelligence | Type errors、Go to definition、Find references（需 IDE 插件）|
+
+**Agentic Loop**：Gather Context → Take Action → Verify Results（反覆迴圈，工具輸出形成下一步輸入）
+
+**Context 自動清理三層**：(1) 清除舊工具輸出 → (2) 壓縮對話 → (3) 保留請求與關鍵程式碼
+
+---
+
+## 2. Skills 系統
+
+> **Skills vs Hooks 核心差異**：Skills 是**用戶主動呼叫**的命令（`/skill-name`），不會自動觸發。
+> 若要在工具執行後自動執行邏輯，應使用 **Hooks**（PostToolUse 類型），不是 Skills。
+
+```yaml
+# .claude/skills/fix-issue/SKILL.md
+---
+name: fix-issue
+description: Fix a GitHub issue (disable-model-invocation = user only)
+disable-model-invocation: true       # 只能手動觸發
+context: fork                        # 在獨立 subagent 中執行
+agent: Explore
+allowed-tools: Read, Grep, Bash
+model: claude-sonnet-4-6
+---
+用 `gh issue view $ARGUMENTS` 取得 issue，分析並修復，
+跑測試確認，提交 commit，開 PR。
+```
+
+**動態注入**（在 Claude 看到前就執行）：
+```markdown
+Git status: !`git status --short`
+Branch: !`git branch --show-current`
+```
+
+**變數**：`$ARGUMENTS`, `$ARGUMENTS[N]`, `$0`..., `${CLAUDE_SESSION_ID}`, `${CLAUDE_SKILL_DIR}`
+
+**Bundled Skills（內建）**：
+
+| 指令 | 功能 |
+|------|------|
+| `/simplify [focus]` | 平行 spawn 3 個 review agents（reuse/quality/efficiency），找問題後自動修復 |
+| `/batch <instruction>` | 超大規模變更：分析→分解 5-30 個任務→每個獨立 worktree + PR（需 git）|
+| `/debug [desc]` | 讀取 session debug log，診斷 Claude Code 問題 |
+| `/claude-api` | 載入 Claude API/SDK 參考（偵測到 `anthropic` import 自動啟用）|
+
+```text
+/batch migrate src/ from React class components to functional components
+/batch add JSDoc comments to all exported functions
+```
+
+**進階 frontmatter**：
+```yaml
+user-invocable: false       # 背景知識：Claude 自動載入，用戶不能 /invoke
+argument-hint: "[issue]"    # autocomplete 提示
+Skill(deploy *)             # permissions deny 中禁用特定 skills
+```
+
+**環境**：`SLASH_COMMAND_TOOL_CHAR_BUDGET`（skill context 預算，預設 context window 2%）
+
+**多檔 Skill**：`SKILL.md`（主）+ `reference.md`（按需）+ `scripts/helper.py`（可執行）
+
+---
+