neo-skill 0.1.18 → 0.1.20

package/.shared/skill-creator/data_packs/tools/README.md

@@ -43,17 +43,22 @@
 }
 ```
 
-## 添加新 Tool
-
-1. 创建 `{tool_id}.json` 文件
-2. 更新 `index.json`，添加索引条目：
-   ```json
-   {
-     "tool_id": {
-       "file": "tool_id.json",
-       "tags": ["..."],
-       "keywords": ["..."]
-     }
+## 如何添加新工具
+
+1. 创建工具详情文件 `{tool-name}.json`
+2. 在 `index.json` 中添加索引条目
+3. 确保 tags 与 capability_tags 设计一致
+
+## 自动推荐机制
+
+skill-creator 会**自动推荐**合适的第三方库，无需用户手动指定：
+
+- **自动触发**：基于 `task_type` 和 `capability_tags` 自动匹配
+- **智能排序**：返回 top-5 最匹配的工具库
+- **多处展示**：推荐信息会在 Plan、Workflow Steps 和最终输出中展示
+- **安全降级**：如果没有匹配的库，不影响 skill 生成
+
+详见：`docs/skill-creator-refactoring/LIBRARY_RECOMMENDATION.md`
    }
    ```
 3. 无需修改代码，系统会自动检索

package/README.md

@@ -85,7 +85,10 @@ omni-skill init --ai all  # 初始化所有支持的 AI 助手
 
 这会：
 - 从 npm 包同步 skills/ 和 .shared/ 到当前目录
-- 为所有 skills 生成 AI 助手的输出文件（.windsurf, .claude, .cursor, .github）
+- 为所有 skills 生成**指定 AI 助手**的输出文件
+  - `--ai windsurf` → 只生成 `.windsurf/workflows/`
+  - `--ai claude` → 只生成 `.claude/skills/`
+  - `--ai all` → 生成所有目标
 - 保存初始化状态到 .neo-skill.json
 
 **2. 使用 skill-creator 创建新 skill**
@@ -103,7 +106,9 @@ omni-skill install ./skills
 
 这会：
 - 复制 skill 到当前目录的 skills/ 文件夹
-- 为该 skill 生成所有 AI 助手的输出文件
+- 为该 skill 生成**所有 AI 助手**的输出文件（.windsurf, .claude, .cursor, .github）
+
+**注意**：与 `init` 不同，`install` 命令总是生成所有 AI 目标的输出，以确保最大兼容性。
 
 **4. 更新 npm 包**
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-skill",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "A multi-assistant skill generator (Claude/Windsurf/Cursor/GitHub Skills) driven by a canonical SkillSpec.",
   "license": "MIT",
   "bin": {

package/skills/skill-creator/references/architecture-rules.md

@@ -0,0 +1,204 @@
+# Skill Creator 架构规则（强制约束）
+
+## 重要提示：AI 必须遵守以下规则
+
+---
+
+## 1. 禁止单文件脚本（Monolith）
+
+### 规则
+
+**严格禁止**生成任何"单文件可执行脚本"作为最终 skill 产物。
+
+### 原因
+
+- 违反分层索引原则
+- 破坏可扩展性
+- 难以维护和复用
+- 无法利用数据包体系
+
+### 允许的形态
+
+✅ **Structured Skill**（唯一允许）：
+- 分层索引文件（index.json）
+- 被索引的数据文件（items/*.json）
+- Skill 主文档（{{skill-id}}.md）
+- 运行时依赖的最小闭包
+
+❌ **Monolith Script**（严格禁止）：
+- 单个 Python/Shell 脚本包含所有逻辑
+- 不使用索引系统
+- 硬编码数据和逻辑
+
+### AI 指令
+
+**不得输出 Monolith**
+**不得建议 Monolith 作为解决方案**
+**即使更简单也必须使用分层索引结构**
+
+---
+
+## 2. Install Space 路径规范
+
+### 路径空间定义
+
+#### Source Space（源文件空间）
+- 仅用于构建/安装阶段
+- 位置：`skills/`, `.shared/`, `src/`
+- **禁止**：运行时依赖
+
+#### Install Space（安装后运行空间）
+- 仅用于运行时
+- 位置：`.windsurf/`, `.claude/`, `.cursor/`, `.github/`
+- **要求**：所有索引路径必须指向此空间
+
+### 路径写法规范
+
+✅ **正确**：使用 Install Space 占位符
+```markdown
+- Data: `{{install_root}}/.windsurf/workflows/data/{{skill-id}}/`
+- Index: `{{install_root}}/.windsurf/workflows/data/{{skill-id}}/index.json`
+```
+
+❌ **错误**：引用 Source Space 路径
+```markdown
+- Data: `skills/{{skill-id}}/data/`
+- Index: `.shared/skill-creator/data_packs/`
+- Relative: `../data/`, `../../skills/`
+```
+
+### 验证
+
+使用 `omni-skill doctor --skill <skill-id>` 验证路径正确性。
+
+---
+
+## 3. 三方库规则
+
+### 自动采用，无需确认
+
+**规则**：
+- ✅ 自动判断并采用三方库
+- ❌ 不要求用户确认
+- ❌ 不要求用户选择 A/B/C
+
+### 结果汇报（强制）
+
+**必须在最终输出中列出**：
+
+```markdown
+## 使用的第三方库
+
+### 1. requests
+- **版本策略**：>=2.28.0
+- **用途**：发起 HTTP 请求
+- **安装方式**：`pip install requests>=2.28.0`
+- **文档链接**：
+  - PyPI: https://pypi.org/project/requests/
+  - Docs: https://requests.readthedocs.io/
+
+### 2. feedparser
+- **版本策略**：>=6.0.0
+- **用途**：解析 RSS/Atom feed
+- **安装方式**：`pip install feedparser>=6.0.0`
+- **文档链接**：
+  - PyPI: https://pypi.org/project/feedparser/
+  - Docs: https://feedparser.readthedocs.io/
+
+### Fallback 方案（可选）
+- 如果不使用 `requests`，可使用标准库 `urllib`
+```
+
+---
+
+## 4. 依赖闭包原则
+
+### 最小闭包
+
+**要求**：
+- ✅ 只拷贝该 skill 需要的最小闭包
+- ❌ 不原封不动复制整个源目录
+- ❌ 不拷贝未被引用的文件
+
+### 闭包内容
+
+每个 skill 的依赖闭包包括：
+1. Skill 主文档（{{skill-id}}.md）
+2. 索引文件（index.json 等）
+3. 索引命中的 items
+4. 必需不变量（universal schema, output packs, minimal checklists）
+5. 三方库声明（requirements.txt）
+6. References/Scripts/Assets
+
+---
+
+## 5. 生成流程
+
+### 步骤
+
+1. **分析需求**：提取任务类型、输出形态、约束条件
+2. **收集信息**：对话式收集（≤10 问）
+3. **设计系统**：分层索引 + 文件化数据包
+4. **生成 SkillSpec**：写入 `skills/<name>/skillspec.json`
+5. **生成输出**：为所有 AI 目标生成文档
+6. **验证**：Schema 校验 + Dry-run
+
+### 禁止事项
+
+❌ 不生成单文件脚本
+❌ 不在文档中引用 Source Space 路径
+❌ 不要求用户确认三方库选型
+❌ 不复制整个源目录
+
+---
+
+## 6. 验收标准
+
+### 功能验收
+
+✅ Skill 产物自包含
+✅ 索引路径只指向 Install Space
+✅ 使用分层索引结构
+✅ 只拷贝最小闭包文件
+
+### 质量验收
+
+✅ 可追溯性：Install manifest 记录完整
+✅ 可复现性：相同输入产生相同输出
+✅ 可维护性：代码结构清晰，文档完整
+
+---
+
+## 7. 示例
+
+### 正确的 Skill 结构
+
+```
+skills/review-gate/
+├── skillspec.json          # Skill 定义
+├── references/             # 规则文档
+│   └── checklist-rules.md
+├── scripts/                # 确定性脚本
+│   └── validate.py
+└── assets/                 # 数据文件
+    └── templates/
+```
+
+### 正确的索引引用
+
+```json
+{
+  "version": "1.0",
+  "items": {
+    "checklist-1": {
+      "file": "{{install_root}}/.windsurf/workflows/data/review-gate/checklists/checklist-1.json"
+    }
+  }
+}
+```
+
+---
+
+**本规则为强制约束，所有 AI 生成的 skill 必须遵守。**
+
+详见：`docs/ARCHITECTURE_RULES.md`

package/src/omni_skill/README.md

@@ -25,10 +25,15 @@ omni-skill init --ai all
 
 **What it does:**
 1. Syncs skills/ and .shared/ from npm package to current directory
-2. Installs all skills (generates outputs for all AI targets)
+2. Installs all skills (generates outputs for **specified AI targets only**)
 3. Writes VERSION files for each AI target
 4. Saves init state to .neo-skill.json
 
+**Example:**
+- `omni-skill init --ai windsurf` → Only generates `.windsurf/workflows/`
+- `omni-skill init --ai claude` → Only generates `.claude/skills/`
+- `omni-skill init --ai all` → Generates all targets (.windsurf, .claude, .cursor, .github)
+
 ### `omni-skill install <path>`
 Install skill(s) from a local directory.
 
@@ -43,7 +48,58 @@ omni-skill install ./skills
 
 **What it does:**
 1. Copies skill(s) to current directory's skills/ folder
-2. Generates outputs for all AI targets (.windsurf, .claude, .cursor, .github)
+2. Generates outputs for **all AI targets** (.windsurf, .claude, .cursor, .github)
+
+**Note:** Unlike `init`, the `install` command always generates outputs for all AI targets to ensure maximum compatibility.
+
+### `omni-skill install-skill <skill-id>`
+Install skill with dependency closure (new architecture).
+
+**Usage:**
+```bash
+omni-skill install-skill review-gate --target windsurf
+omni-skill install-skill skill-creator --target claude
+```
+
+**What it does:**
+1. Resolves skill dependency closure (minimal files)
+2. Materializes files to Install Space
+3. Generates install manifest
+4. Validates paths (no source path leakage)
+
+**Architecture:**
+- Uses Source Space (skills/) for build
+- Copies to Install Space (.windsurf/, .claude/, etc.) for runtime
+- Only copies minimal closure (not entire source directory)
+
+### `omni-skill doctor --skill <skill-id>`
+Diagnose skill installation and dependencies.
+
+**Usage:**
+```bash
+omni-skill doctor --skill review-gate --target windsurf
+```
+
+**What it checks:**
+- Install manifest exists
+- All referenced files exist
+- No source path leakage
+- Index files are valid
+- Dependency closure is complete
+
+**Output:**
+```
+=== Skill Diagnostic Report ===
+Skill ID: review-gate
+Install Root: .windsurf/workflows/data/review-gate
+
+--- Path Validation ---
+✓ No source path leakage detected
+✓ All index paths point to Install Space
+✓ All referenced files exist
+
+=== Diagnostic Complete ===
+```
 
 ### `omni-skill update`
 Update npm package and re-initialize skills.

package/src/omni_skill/cli.py

@@ -4,9 +4,11 @@ import argparse
 import json
 import shutil
 from pathlib import Path
-from typing import Dict, List, Set
+from typing import Dict, List, Optional, Set
 
 from skill_creator.cli import cmd_generate
+from .install import SkillInstaller
+from .doctor import SkillDoctor
 
 STATE_FILE = ".neo-skill.json"
 
@@ -192,10 +194,15 @@ def _generate_outputs_best_effort(pkg_root: Path, cwd: Path) -> None:
             print(f"  Skipping generator for {rel} (exit {e.code})")
 
 
-def _install_skills_from_dir(skills_dir: Path, cwd: Path) -> int:
+def _install_skills_from_dir(skills_dir: Path, cwd: Path, selected_ais: Optional[List[str]] = None) -> int:
     """
     Install skills from a directory (either from npm package or local path).
-    Generates outputs for all AI targets.
+    Generates outputs for specified AI targets.
+    
+    Args:
+        skills_dir: Directory containing skills
+        cwd: Current working directory
+        selected_ais: List of AI targets to generate for. If None, generates for all targets.
     """
     if not skills_dir.exists():
         print(f"Skills directory not found: {skills_dir}")
@@ -206,6 +213,37 @@ def _install_skills_from_dir(skills_dir: Path, cwd: Path) -> int:
         print(f"No skillspec.json found in: {skills_dir}")
         return 1
     
+    # Determine target mapping: AI assistant -> skill-creator target
+    ai_to_target = {
+        "windsurf": "windsurf",
+        "claude": "claude",
+        "cursor": "cursor",
+        "antigravity": "github",
+        "copilot": "github",
+        "kiro": "github",
+        "codex": "github",
+        "qoder": "github",
+        "roocode": "github",
+        "gemini": "github",
+        "trae": "github",
+        "opencode": "github",
+        "continue": "github",
+    }
+    
+    # Determine which targets to generate
+    if selected_ais is None:
+        # Generate all targets
+        generate_all_targets = True
+        targets_list = None
+    else:
+        # Map AI assistants to skill-creator targets
+        targets_set = set()
+        for ai in selected_ais:
+            target = ai_to_target.get(ai, "windsurf")
+            targets_set.add(target)
+        targets_list = sorted(targets_set)
+        generate_all_targets = False
+    
     print(f"\nInstalling {len(specs)} skill(s) from {skills_dir} ...")
     for spec_path in specs:
         skill_name = spec_path.parent.name
@@ -221,11 +259,18 @@ def _install_skills_from_dir(skills_dir: Path, cwd: Path) -> int:
             shutil.copytree(spec_path.parent, dest_skill_dir)
             print(f"    Copied to: {dest_skill_dir}")
         
-        # Generate outputs for all targets
+        # Generate outputs for specified targets
         try:
-            ns = argparse.Namespace(repo_root=str(cwd), spec=str(cwd / "skills" / skill_name / "skillspec.json"), all=True)
-            cmd_generate(ns)
-            print(f"    Generated outputs for all targets")
+            if generate_all_targets:
+                ns = argparse.Namespace(repo_root=str(cwd), spec=str(cwd / "skills" / skill_name / "skillspec.json"), all=True)
+                cmd_generate(ns)
+                print(f"    Generated outputs for all targets")
+            else:
+                # Generate for each target separately
+                for target in targets_list:
+                    ns = argparse.Namespace(repo_root=str(cwd), spec=str(cwd / "skills" / skill_name / "skillspec.json"), all=False, target=target)
+                    cmd_generate(ns)
+                print(f"    Generated outputs for: {', '.join(targets_list)}")
         except SystemExit as e:
             print(f"    Warning: Generator failed (exit {e.code})")
     
@@ -242,10 +287,10 @@ def _handle_init(selected_ais: List[str], mode: str) -> int:
     print("Initializing skills in:", cwd)
     _perform_sync(pkg_root, cwd, sync_pairs)
     
-    # Install all skills from npm package
+    # Install all skills from npm package with specified AI targets
     pkg_skills_dir = pkg_root / "skills"
     if pkg_skills_dir.exists():
-        _install_skills_from_dir(pkg_skills_dir, cwd)
+        _install_skills_from_dir(pkg_skills_dir, cwd, selected_ais=selected_ais)
     
     _write_version_files(cwd, effective_ais, version)
     print("\nDone! neo-skill initialized.")
@@ -267,10 +312,39 @@ def _cmd_init(args: argparse.Namespace) -> int:
     return _handle_init(resolved["selected"], "init")
 
 
+def _cmd_install_new(args: argparse.Namespace) -> int:
+    """
+    Install skill with dependency closure (new architecture).
+    Usage: omni-skill install <skill-id> [--target <agent>]
+    """
+    cwd = Path.cwd().resolve()
+    pkg_root = _get_pkg_root()
+    
+    skill_id = args.skill_id
+    target = getattr(args, 'target', 'windsurf')
+    
+    # 使用新的 SkillInstaller
+    installer = SkillInstaller(source_root=pkg_root, install_root=cwd)
+    
+    try:
+        manifest = installer.install(skill_id, target)
+        print(f"\n✓ Successfully installed {skill_id}")
+        print(f"  Install root: {manifest.install_root}")
+        print(f"  Files: {len(manifest.files)}")
+        if manifest.dependencies.get('libraries'):
+            print(f"  Libraries: {', '.join(manifest.dependencies['libraries'])}")
+        return 0
+    except Exception as e:
+        print(f"\n✗ Installation failed: {e}")
+        return 1
+
+
 def _cmd_install(args: argparse.Namespace) -> int:
     """
-    Install skill(s) from a local directory.
+    Install skill(s) from a local directory (legacy).
     Usage: omni-skill install <path-to-skill-or-skills-dir>
+    
+    Note: install command always generates outputs for all AI targets.
     """
     cwd = Path.cwd().resolve()
     skill_path = Path(args.path).resolve()
@@ -280,13 +354,13 @@ def _cmd_install(args: argparse.Namespace) -> int:
     
     # Check if it's a single skill directory (contains skillspec.json)
     if (skill_path / "skillspec.json").exists():
-        # Single skill
+        # Single skill - generate for all targets
         temp_skills_dir = skill_path.parent
-        return _install_skills_from_dir(temp_skills_dir, cwd)
+        return _install_skills_from_dir(temp_skills_dir, cwd, selected_ais=None)
     
     # Check if it's a skills directory (contains subdirs with skillspec.json)
     elif skill_path.is_dir():
-        return _install_skills_from_dir(skill_path, cwd)
+        return _install_skills_from_dir(skill_path, cwd, selected_ais=None)
     
     else:
         raise SystemExit(f"Invalid path: {skill_path}. Must be a skill directory or skills directory.")
@@ -332,6 +406,28 @@ def _print_init_help() -> None:
     print("  omni-skill init --ai all")
 
 
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    """
+    Diagnose skill installation and dependencies.
+    Usage: omni-skill doctor --skill <skill-id> [--target <agent>]
+    """
+    cwd = Path.cwd().resolve()
+    
+    skill_id = args.skill_id
+    target = getattr(args, 'target', 'windsurf')
+    
+    # 使用 SkillDoctor
+    doctor = SkillDoctor(install_root=cwd)
+    
+    report = doctor.diagnose(skill_id, target)
+    print(report.format())
+    
+    # 返回错误码
+    if report.has_errors():
+        return 1
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="omni-skill",
@@ -347,6 +443,18 @@ def build_parser() -> argparse.ArgumentParser:
     p_install = sub.add_parser("install", help="Install skill(s) from a local directory")
     p_install.add_argument("path", help="Path to skill directory or skills directory")
     p_install.set_defaults(func=_cmd_install)
+    
+    # 新增：install-skill 命令（使用新架构）
+    p_install_new = sub.add_parser("install-skill", help="Install skill with dependency closure (new)")
+    p_install_new.add_argument("skill_id", help="Skill ID to install")
+    p_install_new.add_argument("--target", default="windsurf", help="Target AI (windsurf/claude/cursor/github)")
+    p_install_new.set_defaults(func=_cmd_install_new)
+    
+    # 新增：doctor 命令
+    p_doctor = sub.add_parser("doctor", help="Diagnose skill installation")
+    p_doctor.add_argument("--skill", dest="skill_id", required=True, help="Skill ID to diagnose")
+    p_doctor.add_argument("--target", default="windsurf", help="Target AI (windsurf/claude/cursor/github)")
+    p_doctor.set_defaults(func=_cmd_doctor)
 
     p_update = sub.add_parser("update", help="Update npm package and re-initialize skills")
     p_update.set_defaults(func=_cmd_update)