@tinkcarlos/skillora 0.2.2 → 0.2.4

package/CLAUDE.md

@@ -0,0 +1,215 @@
+# CLAUDE.md
+
+## 🌐 语言设置 (Language Setting)
+
+**强制要求**: 所有输出内容必须使用**简体中文**，包括但不限于：
+- 任务分析和计划 (Task Analysis & Plan)
+- Todo列表 (Todo List)
+- 技能切换通知 (Skill Switch Notification)
+- 任务完成报告 (Completion Report)
+- 问题澄清和确认 (Clarification & Confirmation)
+
+## Core Decision Flow (Execute on EVERY user input)
+
+```
+Step 1: Task Type Matching (Highest Priority)
+┌─────────────────────────────────────────────────────────────────┐
+│  Keywords → Force Skill (regardless of complexity)              │
+│  ├─ fix/bug/error/exception/broken → @bug-fixing               │
+│  ├─ develop/feature/implement/add → @fullstack-developer       │
+│  ├─ optimize/refactor/improve → @fullstack-developer           │
+│  ├─ review/check code/PR → @code-review                        │
+│  ├─ frontend/UI/interface/style → @frontend-design             │
+│  └─ Other → Go to Step 2                                       │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+Step 2: Complexity Assessment (Only when Step 1 doesn't match)
+┌─────────────────────────────────────────────────────────────────┐
+│  Steps → Action                                                 │
+│  ├─ 1-2 steps → Simple → Execute directly                      │
+│  ├─ 3-5 steps → Medium → Must create Todo + Recommend Skill    │
+│  └─ 5+ steps → Complex → Must Todo + Must Skill + Must MCP     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Skill Mapping Table
+
+### Mandatory Skills (Must invoke when matched)
+
+| Task Type | Skill | MCP Tools | Closed-loop |
+|-----------|-------|-----------|-------------|
+| Bug Fix | `@bug-fixing` | serena | → @code-review → loop |
+| Feature Dev | `@fullstack-developer` | sequential-thinking + serena | → @code-review → loop |
+| Code Review | `@code-review` | serena | Issues → @bug-fixing |
+| Frontend UI | `@frontend-design` | context7 | → @fullstack-developer → @code-review |
+| Test Design | `@test-architect-live` | sequential-thinking | - |
+| Documentation | `@doc-coauthoring` | memory | - |
+| Requirements | `@product-requirements` | sequential-thinking | - |
+| Project Arch | `@project-development` | sequential-thinking + memory | - |
+
+### Implicit Intent Recognition
+
+| User Pattern | Auto-invoke |
+|--------------|-------------|
+| Pastes error log / stack trace | `@bug-fixing` |
+| Shares code + "help me look" | `@code-review` |
+| "How to implement..." | `@fullstack-developer` |
+| Mentions new component/page | `@fullstack-developer` + `@frontend-design` |
+| Discusses API/endpoint | `@api-design-principles` |
+| Mentions database/migration | `@database-migration` |
+
+### Sub-task Triggers (Auto-switch during main task)
+
+| Scenario | Auto-invoke |
+|----------|-------------|
+| DB/table changes | `@database-migration` |
+| New API endpoint | `@api-design-principles` |
+| UI component work | `@frontend-design` |
+| Auth/security | `@auth-implementation-patterns` |
+| FastAPI | `@fastapi-templates` |
+| LangChain/LLM | `@langchain-architecture` |
+| React state | `@react-state-management` |
+
+### File Type Skills
+
+| Type | Skill | Type | Skill |
+|------|-------|------|-------|
+| .docx | `@docx` | .pptx | `@pptx` |
+| .xlsx/.csv | `@xlsx` | .pdf | `@pdf` |
+
+## MCP Tools Rules
+
+### Iron Rule: MCP = Read-Only
+
+All MCP tools are for **reading and analysis only**. Code editing must use Claude Code native Edit/Write tools.
+
+### Tool Selection
+
+| Scenario | Use Tool |
+|----------|----------|
+| Plan complex tasks (≥3 steps) | `sequential-thinking` |
+| Query library/API docs | `context7` |
+| Search best practices | `Exa Search` |
+| Analyze code structure | `serena` (read-only) |
+| Save/retrieve context | `memory` |
+
+### Forbidden serena Operations
+
+```
+❌ replace_symbol_body
+❌ insert_after_symbol
+❌ insert_before_symbol
+❌ rename_symbol
+```
+
+## Workflow Rules
+
+### Closed-loop (Mandatory for code changes)
+
+```
+Main Skill → @code-review → (issues? → @bug-fixing → @code-review)* → Summary
+```
+
+### Skill Switch Notification (Required)
+
+```
+🔄 Skill Switch: [@current] → [@new]
+Reason: [Brief explanation]
+```
+
+### Task Completion Report (Required)
+
+```
+📊 Tool Report
+- Skills: [@skill1], [@skill2]
+- MCP: [tool1], [tool2]
+- Chain: @main → @sub → @code-review
+```
+
+## Core Rules
+
+| Rule | Description |
+|------|-------------|
+| **中文输出** | 所有对话内容必须使用中文，包括任务列表、计划、分析、报告 |
+| Check Every Input | Re-evaluate task type on each user message |
+| Task Type > Complexity | Even 1-step bug fix must use @bug-fixing |
+| Analyze Before Action | Output analysis before coding |
+| Ask Don't Guess | Clarify when uncertain |
+| Transparent Output | Notify on skill switch, report on completion |
+
+## Skills System
+
+### How to Invoke Skills
+
+Use `Skill` tool to load skills. Example: invoke skill "bug-fixing"
+
+### Core Skills (15)
+
+| Category | Skill | Triggers |
+|----------|-------|----------|
+| Dev Core | `@bug-fixing` | bug, error, fix |
+| | `@fullstack-developer` | feature, develop |
+| | `@code-review` | review, PR |
+| Frontend | `@frontend-design` | UI, component |
+| | `@tailwind-design-system` | tailwind, CSS |
+| Backend | `@api-design-principles` | API, REST |
+| | `@database-migration` | DB, migration |
+| Docs | `@doc-coauthoring` | documentation |
+| | `@product-requirements` | PRD, requirements |
+| | `@project-development` | architecture |
+| Testing | `@test-architect-live` | test cases |
+| | `@webapp-testing` | E2E, browser test |
+| Files | `@docx` `@xlsx` `@pdf` `@pptx` | file types |
+
+### Extended Skills (85+)
+
+Run `openskills list` or `openskills search <query>` to discover more skills.
+
+Categories: Data Engineering, Cloud Infrastructure, CI/CD, Security, LLM/AI, Frontend, Backend, Observability, Blockchain
+
+## Python Development
+
+Always use virtual environment for Python projects:
+```bash
+# Windows
+python -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+venv\Scripts\python.exe script.py
+```
+
+## Hooks 自动触发规则
+
+### Skill 调用时
+
+| Hook | 触发时机 | 作用 |
+|------|----------|------|
+| PreToolUse:Skill | Skill 调用前 | 记录调用、提醒锚点 |
+| PostToolUse:Skill | Skill 调用后 | 验证完成、检查偏离 |
+
+### Subagent 派发时
+
+| Hook | 触发时机 | 作用 |
+|------|----------|------|
+| PreToolUse:Task | Subagent 派发前 | 检查锚点完整性 |
+| PostToolUse:Task | Subagent 返回后 | 验证偏离、更新进度 |
+| SubagentStop | Subagent 停止时 | 恢复上下文、输出检查清单 |
+
+### Hook 输出解读
+
+| 输出 | 含义 | 处理 |
+|------|------|------|
+| `⚠️ WARNING: missing context anchor` | Subagent 缺少锚点 | 重新派发，添加锚点 |
+| `🔄 Subagent completed` | Subagent 正常完成 | 验证范围，继续任务 |
+| `📋 Checklist` | 检查清单 | 逐项验证 |
+
+### 日志文件
+
+| 文件 | 内容 |
+|------|------|
+| `~/.claude/skill-invocation-log.jsonl` | Skill 调用记录 |
+| `~/.claude/subagent-dispatch-log.jsonl` | Subagent 派发记录 |
+
+### Subagent 调用模板
+
+详见 `.claude/skills/shared-references/subagent-dispatch-templates.md`

package/lib/init.js

@@ -6,12 +6,12 @@ const os = require("os");
 const readline = require("readline");
 
 const PLATFORMS = [
-  { name: "Claude Code", value: "claude-code", native: true },
-  { name: "Cursor", value: "cursor" },
-  { name: "Codex/GPT", value: "codex" },
-  { name: "Gemini", value: "gemini" },
-  { name: "Windsurf", value: "windsurf" },
-  { name: "Aider", value: "aider" },
+  { name: "Claude Code", value: "claude-code", selected: true },
+  { name: "Cursor", value: "cursor", selected: false },
+  { name: "Codex/GPT", value: "codex", selected: false },
+  { name: "Gemini", value: "gemini", selected: false },
+  { name: "Windsurf", value: "windsurf", selected: false },
+  { name: "Aider", value: "aider", selected: false },
 ];
 
 const INSTALL_MODES = [
@@ -20,50 +20,126 @@ const INSTALL_MODES = [
   { name: "全局模式 (~/.claude/skills/ - 所有项目共享)", value: "global" },
 ];
 
-function createReadline() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+function clearLines(count) {
+  for (let i = 0; i < count; i++) {
+    process.stdout.write("\x1b[1A\x1b[2K");
+  }
 }
 
-async function question(rl, prompt) {
-  return new Promise((resolve, reject) => {
-    rl.question(prompt, resolve);
-    rl.once("close", () => reject(new Error("User cancelled")));
+function renderMultiSelect(title, options, cursor) {
+  const lines = [`\n${title}`];
+  options.forEach((opt, i) => {
+    const pointer = i === cursor ? ">" : " ";
+    const check = opt.selected ? "[✓]" : "[ ]";
+    lines.push(`  ${pointer} ${check} ${opt.name}`);
   });
+  lines.push("\n  ↑↓ 移动  空格 选择  回车 确认");
+  return lines;
 }
 
-async function selectMultiple(rl, title, options) {
-  console.log(`\n${title}`);
+function renderSingleSelect(title, options, cursor) {
+  const lines = [`\n${title}`];
   options.forEach((opt, i) => {
-    const marker = opt.native ? "◉" : "◯";
-    console.log(`  ${i + 1}. [${marker}] ${opt.name}`);
+    const pointer = i === cursor ? ">" : " ";
+    const radio = i === cursor ? "(●)" : "( )";
+    lines.push(`  ${pointer} ${radio} ${opt.name}`);
   });
-  console.log("\n输入数字选择 (多选用逗号分隔, 如: 1,2), 回车确认:");
+  lines.push("\n  ↑↓ 移动  回车 确认");
+  return lines;
+}
 
-  const answer = await question(rl, "> ");
-  if (!answer.trim()) {
-    return options.filter((o) => o.native).map((o) => o.value);
-  }
+async function selectMultiple(title, options) {
+  return new Promise((resolve) => {
+    const opts = options.map((o) => ({ ...o }));
+    let cursor = 0;
+    let lines = renderMultiSelect(title, opts, cursor);
 
-  const indices = answer.split(",").map((s) => parseInt(s.trim(), 10) - 1);
-  return indices
-    .filter((i) => i >= 0 && i < options.length)
-    .map((i) => options[i].value);
-}
+    process.stdout.write(lines.join("\n") + "\n");
 
-async function selectSingle(rl, title, options) {
-  console.log(`\n${title}`);
-  options.forEach((opt, i) => {
-    const marker = i === 0 ? "◉" : "◯";
-    console.log(`  ${i + 1}. [${marker}] ${opt.name}`);
+    if (!process.stdin.isTTY) {
+      resolve(opts.filter((o) => o.selected).map((o) => o.value));
+      return;
+    }
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+
+    const onKeypress = (str, key) => {
+      if (key.ctrl && key.name === "c") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKeypress);
+        process.exit(0);
+      }
+
+      if (key.name === "up") {
+        cursor = cursor > 0 ? cursor - 1 : opts.length - 1;
+      } else if (key.name === "down") {
+        cursor = cursor < opts.length - 1 ? cursor + 1 : 0;
+      } else if (key.name === "space") {
+        opts[cursor].selected = !opts[cursor].selected;
+      } else if (key.name === "return") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKeypress);
+        clearLines(lines.length);
+        const selected = opts.filter((o) => o.selected).map((o) => o.value);
+        console.log(`${title}`);
+        console.log(`  已选择: ${selected.length > 0 ? selected.join(", ") : "(无)"}\n`);
+        resolve(selected);
+        return;
+      }
+
+      clearLines(lines.length);
+      lines = renderMultiSelect(title, opts, cursor);
+      process.stdout.write(lines.join("\n") + "\n");
+    };
+
+    process.stdin.on("keypress", onKeypress);
   });
-  console.log("\n输入数字选择 (默认: 1):");
+}
+
+async function selectSingle(title, options) {
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let lines = renderSingleSelect(title, options, cursor);
+
+    process.stdout.write(lines.join("\n") + "\n");
+
+    if (!process.stdin.isTTY) {
+      resolve(options[0].value);
+      return;
+    }
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+
+    const onKeypress = (str, key) => {
+      if (key.ctrl && key.name === "c") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKeypress);
+        process.exit(0);
+      }
+
+      if (key.name === "up") {
+        cursor = cursor > 0 ? cursor - 1 : options.length - 1;
+      } else if (key.name === "down") {
+        cursor = cursor < options.length - 1 ? cursor + 1 : 0;
+      } else if (key.name === "return") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKeypress);
+        clearLines(lines.length);
+        console.log(`${title}`);
+        console.log(`  已选择: ${options[cursor].name}\n`);
+        resolve(options[cursor].value);
+        return;
+      }
 
-  const answer = await question(rl, "> ");
-  const index = answer.trim() ? parseInt(answer.trim(), 10) - 1 : 0;
-  return options[Math.max(0, Math.min(index, options.length - 1))].value;
+      clearLines(lines.length);
+      lines = renderSingleSelect(title, options, cursor);
+      process.stdout.write(lines.join("\n") + "\n");
+    };
+
+    process.stdin.on("keypress", onKeypress);
+  });
 }
 
 function getTargetDir(mode) {
@@ -97,9 +173,96 @@ function listSkillDirs(rootDir) {
     .filter((d) => fs.existsSync(path.join(d, "SKILL.md")));
 }
 
-function generateClaudeMd(skills) {
+function parseFrontmatter(content) {
+  if (!content || !content.startsWith("---")) return {};
+  const endIndex = content.indexOf("\n---", 3);
+  if (endIndex === -1) return {};
+
+  const raw = content.slice(3, endIndex).trim();
+  const data = {};
+  let currentKey = null;
+  let multilineValue = [];
+
+  for (const line of raw.split(/\r?\n/)) {
+    const indented = line.startsWith("  ") || line.startsWith("\t");
+    if (indented && currentKey) {
+      multilineValue.push(line.trim());
+      continue;
+    }
+
+    if (currentKey && multilineValue.length > 0) {
+      data[currentKey] = multilineValue.join(" ").trim();
+      multilineValue = [];
+    }
+
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+
+    if (value === "|" || value === ">") {
+      currentKey = key;
+      multilineValue = [];
+      continue;
+    }
+
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key && value) data[key] = value;
+    currentKey = null;
+  }
+
+  if (currentKey && multilineValue.length > 0) {
+    data[currentKey] = multilineValue.join(" ").trim();
+  }
+
+  return data;
+}
+
+function readSkillMeta(skillDir) {
+  try {
+    const content = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
+    const fm = parseFrontmatter(content);
+    return {
+      name: fm.name || path.basename(skillDir),
+      description: fm.description || "",
+      userInvocable: fm["user-invocable"] !== "false",
+    };
+  } catch (err) {
+    console.error(`Warning: Failed to read ${skillDir}: ${err.message}`);
+    return {
+      name: path.basename(skillDir),
+      description: "",
+      userInvocable: true,
+    };
+  }
+}
+
+function generateClaudeMdFromTemplate(templatePath, skills) {
   const invocableSkills = skills.filter((s) => s.userInvocable);
-  const slashCommands = invocableSkills.map((s) => `/ora/${s.name}`).join(", ");
+  const slashCommands = invocableSkills.map((s) => `/ora/${s.name}`);
+
+  if (fs.existsSync(templatePath)) {
+    let content = fs.readFileSync(templatePath, "utf8");
+    // 替换 openskills 为 skillora
+    content = content.replace(/openskills/g, "skillora");
+    // 更新技能数量
+    content = content.replace(
+      /Core Skills \(\d+\)/,
+      `Core Skills (${skills.length})`
+    );
+    content = content.replace(
+      /Extended Skills \(\d+\+\)/,
+      `Extended Skills (${skills.length}+)`
+    );
+    return content;
+  }
+
+  // 如果模板不存在，生成简化版本
   return `# CLAUDE.md
 
 ## Skills System
@@ -108,7 +271,7 @@ function generateClaudeMd(skills) {
 
 ### 斜杠命令（推荐）
 
-${slashCommands || "(无可调用技能)"}
+${slashCommands.join(", ")}
 
 ### CLI 命令
 
@@ -118,6 +281,8 @@ ${slashCommands || "(无可调用技能)"}
 }
 
 function generateCursorRules(skills) {
+  const invocableSkills = skills.filter((s) => s.userInvocable);
+  const slashCommands = invocableSkills.map((s) => `/ora/${s.name}`).join(", ");
   const skillList = skills
     .map((s) => `- ${s.name}: ${s.description}`)
     .join("\n");
@@ -127,6 +292,10 @@ function generateCursorRules(skills) {
 
 ${skillList}
 
+## Slash Commands (Claude Code)
+
+${slashCommands}
+
 ## Usage
 
 使用 \`skillora read <skill-name>\` 加载技能详情。
@@ -171,75 +340,6 @@ ${skillTable}
 `;
 }
 
-function parseFrontmatter(content) {
-  if (!content || !content.startsWith("---")) return {};
-  const endIndex = content.indexOf("\n---", 3);
-  if (endIndex === -1) return {};
-
-  const raw = content.slice(3, endIndex).trim();
-  const data = {};
-  let currentKey = null;
-  let multilineValue = [];
-
-  for (const line of raw.split(/\r?\n/)) {
-    const indented = line.startsWith("  ") || line.startsWith("\t");
-    if (indented && currentKey) {
-      multilineValue.push(line.trim());
-      continue;
-    }
-
-    if (currentKey && multilineValue.length > 0) {
-      data[currentKey] = multilineValue.join(" ").trim();
-      multilineValue = [];
-    }
-
-    const idx = line.indexOf(":");
-    if (idx === -1) continue;
-    const key = line.slice(0, idx).trim();
-    let value = line.slice(idx + 1).trim();
-
-    if (value === "|" || value === ">") {
-      currentKey = key;
-      multilineValue = [];
-      continue;
-    }
-
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-    if (key && value) data[key] = value;
-    currentKey = null;
-  }
-
-  if (currentKey && multilineValue.length > 0) {
-    data[currentKey] = multilineValue.join(" ").trim();
-  }
-
-  return data;
-}
-
-function readSkillMeta(skillDir) {
-  try {
-    const content = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
-    const fm = parseFrontmatter(content);
-    return {
-      name: fm.name || path.basename(skillDir),
-      description: fm.description || "",
-      userInvocable: fm["user-invocable"] !== "false",
-    };
-  } catch (err) {
-    console.error(`Warning: Failed to read ${skillDir}: ${err.message}`);
-    return {
-      name: path.basename(skillDir),
-      description: "",
-      userInvocable: true,
-    };
-  }
-}
-
 async function runInit(options, bundledSkillsDir) {
   let platforms = options.platform
     ? options.platform.split(",").map((s) => s.trim())
@@ -258,22 +358,20 @@ async function runInit(options, bundledSkillsDir) {
   }
 
   // 交互式选择
-  let rl = null;
   if (!platforms || !mode) {
-    rl = createReadline();
-    try {
-      if (!platforms) {
-        platforms = await selectMultiple(rl, "选择要配置的平台:", PLATFORMS);
-      }
-      if (!mode) {
-        mode = await selectSingle(rl, "选择安装模式:", INSTALL_MODES);
-      }
-    } finally {
-      rl.close();
+    if (!platforms) {
+      platforms = await selectMultiple("选择要配置的平台:", PLATFORMS);
+    }
+    if (!mode) {
+      mode = await selectSingle("选择安装模式:", INSTALL_MODES);
     }
   }
 
-  console.log("\n正在配置...\n");
+  if (platforms.length === 0) {
+    platforms = ["claude-code"];
+  }
+
+  console.log("正在配置...\n");
 
   // 确定目标目录
   const targetDir = getTargetDir(mode);
@@ -299,21 +397,29 @@ async function runInit(options, bundledSkillsDir) {
   const skills = installedSkillDirs.map(readSkillMeta);
 
   const cwd = process.cwd();
+  const packageRoot = path.resolve(__dirname, "..");
   const created = [];
 
   // 生成平台配置文件
   if (platforms.includes("claude-code")) {
     const claudeMdPath = path.join(cwd, "CLAUDE.md");
-    if (!fs.existsSync(claudeMdPath)) {
-      fs.writeFileSync(claudeMdPath, generateClaudeMd(skills), "utf8");
+    if (!fs.existsSync(claudeMdPath) || options.force) {
+      const templatePath = path.join(packageRoot, "CLAUDE.md");
+      fs.writeFileSync(
+        claudeMdPath,
+        generateClaudeMdFromTemplate(templatePath, skills),
+        "utf8"
+      );
       created.push("CLAUDE.md");
     }
   }
 
   if (platforms.includes("cursor")) {
     const cursorPath = path.join(cwd, ".cursorrules");
-    fs.writeFileSync(cursorPath, generateCursorRules(skills), "utf8");
-    created.push(".cursorrules");
+    if (!fs.existsSync(cursorPath) || options.force) {
+      fs.writeFileSync(cursorPath, generateCursorRules(skills), "utf8");
+      created.push(".cursorrules");
+    }
   }
 
   const needsAgentsMd = platforms.some((p) =>
@@ -322,12 +428,14 @@ async function runInit(options, bundledSkillsDir) {
 
   if (needsAgentsMd) {
     const agentsPath = path.join(cwd, "AGENTS.md");
-    fs.writeFileSync(
-      agentsPath,
-      generateAgentsMd(skills, "skillora"),
-      "utf8",
-    );
-    created.push("AGENTS.md");
+    if (!fs.existsSync(agentsPath) || options.force) {
+      fs.writeFileSync(
+        agentsPath,
+        generateAgentsMd(skills, "skillora"),
+        "utf8",
+      );
+      created.push("AGENTS.md");
+    }
   }
 
   // 输出结果

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinkcarlos/skillora",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "CLI installer for bundled Claude Code skills (SKILL.md format)",
   "bin": {
     "skillora": "bin/cli.js"
@@ -9,6 +9,7 @@
     "bin",
     "lib",
     ".claude/skills",
+    "CLAUDE.md",
     "README.md"
   ],
   "keywords": [