neo-skill 0.1.19 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-skill",
-  "version": "0.1.19",
+  "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

@@ -52,6 +52,55 @@ omni-skill install ./skills
 
 **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

@@ -7,6 +7,8 @@ from pathlib import Path
 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"
 
@@ -310,9 +312,36 @@ 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.
@@ -377,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",
@@ -392,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)

package/src/omni_skill/doctor.py

@@ -0,0 +1,323 @@
+"""
+Doctor module: 诊断 skill 安装状态和依赖完整性
+
+遵循架构规则：
+- 检测 source path 泄漏
+- 验证索引路径指向 Install Space
+- 检查依赖闭包完整性
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Set
+
+
+@dataclass
+class DiagnosticIssue:
+    """诊断问题"""
+    severity: str  # error, warning, info
+    category: str  # path_leakage, missing_file, invalid_index, etc.
+    message: str
+    file: Optional[str] = None
+    line: Optional[int] = None
+
+
+@dataclass
+class DiagnosticReport:
+    """诊断报告"""
+    skill_id: str
+    install_root: Optional[str] = None
+    installed_at: Optional[str] = None
+    total_files: int = 0
+    files: List[str] = field(default_factory=list)
+    dependencies: dict = field(default_factory=dict)
+    issues: List[DiagnosticIssue] = field(default_factory=list)
+    
+    def has_errors(self) -> bool:
+        """是否有错误"""
+        return any(issue.severity == "error" for issue in self.issues)
+    
+    def has_warnings(self) -> bool:
+        """是否有警告"""
+        return any(issue.severity == "warning" for issue in self.issues)
+    
+    def format(self) -> str:
+        """格式化输出"""
+        lines = [
+            "=== Skill Diagnostic Report ===",
+            "",
+            f"Skill ID: {self.skill_id}",
+        ]
+        
+        if self.install_root:
+            lines.append(f"Install Root: {self.install_root}")
+        if self.installed_at:
+            lines.append(f"Installed At: {self.installed_at}")
+        
+        lines.extend([
+            "",
+            "--- Dependency Closure ---"
+        ])
+        
+        if self.files:
+            for file in self.files[:10]:  # 只显示前 10 个
+                lines.append(f"✓ {file}")
+            if len(self.files) > 10:
+                lines.append(f"... and {len(self.files) - 10} more files")
+        
+        lines.append(f"\nTotal files: {self.total_files}")
+        
+        if self.dependencies:
+            lines.extend([
+                "",
+                "--- Dependencies ---"
+            ])
+            
+            if "libraries" in self.dependencies and self.dependencies["libraries"]:
+                lines.append("Libraries:")
+                for lib in self.dependencies["libraries"]:
+                    lines.append(f"  - {lib}")
+            
+            if "data_packs" in self.dependencies and self.dependencies["data_packs"]:
+                lines.append("\nData Packs:")
+                for pack in self.dependencies["data_packs"]:
+                    lines.append(f"  - {pack}")
+        
+        lines.extend([
+            "",
+            "--- Issues ---"
+        ])
+        
+        if not self.issues:
+            lines.append("None")
+        else:
+            # 按严重程度分组
+            errors = [i for i in self.issues if i.severity == "error"]
+            warnings = [i for i in self.issues if i.severity == "warning"]
+            infos = [i for i in self.issues if i.severity == "info"]
+            
+            if errors:
+                lines.append("\nErrors:")
+                for issue in errors:
+                    lines.append(f"  ❌ [{issue.category}] {issue.message}")
+                    if issue.file:
+                        lines.append(f"     File: {issue.file}")
+            
+            if warnings:
+                lines.append("\nWarnings:")
+                for issue in warnings:
+                    lines.append(f"  ⚠️  [{issue.category}] {issue.message}")
+                    if issue.file:
+                        lines.append(f"     File: {issue.file}")
+            
+            if infos:
+                lines.append("\nInfo:")
+                for issue in infos:
+                    lines.append(f"  ℹ️  [{issue.category}] {issue.message}")
+        
+        lines.extend([
+            "",
+            "=== Diagnostic Complete ==="
+        ])
+        
+        return "\n".join(lines)
+
+
+class SkillDoctor:
+    """Skill 诊断器"""
+    
+    def __init__(self, install_root: Path):
+        self.install_root = install_root
+    
+    def diagnose(self, skill_id: str, target: str = "windsurf") -> DiagnosticReport:
+        """
+        诊断 skill 安装状态
+        
+        Args:
+            skill_id: skill ID
+            target: 目标 AI 助手
+        
+        Returns:
+            DiagnosticReport
+        """
+        report = DiagnosticReport(skill_id=skill_id)
+        
+        # 1. 查找 install manifest
+        manifest_path = self._find_manifest(skill_id, target)
+        if not manifest_path:
+            report.issues.append(DiagnosticIssue(
+                severity="error",
+                category="missing_manifest",
+                message=f"Install manifest not found for skill '{skill_id}'. Please run 'omni-skill install' first."
+            ))
+            return report
+        
+        # 2. 读取 manifest
+        try:
+            with open(manifest_path, 'r', encoding='utf-8') as f:
+                manifest = json.load(f)
+            
+            report.install_root = manifest.get("install_root")
+            report.installed_at = manifest.get("installed_at")
+            report.dependencies = manifest.get("dependencies", {})
+            
+            files = manifest.get("files", [])
+            report.total_files = len(files)
+            report.files = [f["target"] for f in files[:10]]
+        
+        except Exception as e:
+            report.issues.append(DiagnosticIssue(
+                severity="error",
+                category="invalid_manifest",
+                message=f"Failed to read manifest: {e}",
+                file=str(manifest_path)
+            ))
+            return report
+        
+        # 3. 检查文件完整性
+        self._check_file_integrity(manifest, report)
+        
+        # 4. 检查 source path 泄漏
+        self._check_path_leakage(skill_id, target, report)
+        
+        # 5. 检查索引可解析性
+        self._check_index_validity(skill_id, target, report)
+        
+        return report
+    
+    def _find_manifest(self, skill_id: str, target: str) -> Optional[Path]:
+        """查找 install manifest"""
+        if target == "windsurf":
+            manifest_path = self.install_root / ".windsurf" / "workflows" / "data" / skill_id / ".install_manifest.json"
+        elif target == "claude":
+            manifest_path = self.install_root / ".claude" / "skills" / skill_id / "resources" / ".install_manifest.json"
+        elif target == "cursor":
+            manifest_path = self.install_root / ".cursor" / "commands" / "data" / skill_id / ".install_manifest.json"
+        elif target == "github":
+            manifest_path = self.install_root / ".github" / "skills" / skill_id / ".install_manifest.json"
+        else:
+            return None
+        
+        return manifest_path if manifest_path.exists() else None
+    
+    def _check_file_integrity(self, manifest: dict, report: DiagnosticReport) -> None:
+        """检查文件完整性"""
+        files = manifest.get("files", [])
+        
+        for file_info in files:
+            target = file_info.get("target")
+            if not target:
+                continue
+            
+            target_path = self.install_root / target
+            if not target_path.exists():
+                report.issues.append(DiagnosticIssue(
+                    severity="error",
+                    category="missing_file",
+                    message=f"Referenced file does not exist",
+                    file=target
+                ))
+    
+    def _check_path_leakage(self, skill_id: str, target: str, report: DiagnosticReport) -> None:
+        """检查 source path 泄漏"""
+        # 查找 skill 主文档
+        if target == "windsurf":
+            skill_doc = self.install_root / ".windsurf" / "workflows" / f"{skill_id}.md"
+        elif target == "claude":
+            skill_doc = self.install_root / ".claude" / "skills" / skill_id / "SKILL.md"
+        elif target == "cursor":
+            skill_doc = self.install_root / ".cursor" / "commands" / f"{skill_id}.md"
+        elif target == "github":
+            skill_doc = self.install_root / ".github" / "skills" / skill_id / "SKILL.md"
+        else:
+            return
+        
+        if not skill_doc.exists():
+            report.issues.append(DiagnosticIssue(
+                severity="warning",
+                category="missing_skill_doc",
+                message=f"Skill document not found",
+                file=str(skill_doc)
+            ))
+            return
+        
+        # 检查文档内容
+        try:
+            content = skill_doc.read_text(encoding='utf-8')
+            
+            # 检测禁止的路径模式
+            forbidden_patterns = [
+                "skills/",
+                ".shared/",
+                "../",
+                "../../",
+                "/home/",
+                "/Users/",
+                "C:/",
+                "D:/",
+            ]
+            
+            for pattern in forbidden_patterns:
+                if pattern in content:
+                    report.issues.append(DiagnosticIssue(
+                        severity="error",
+                        category="path_leakage",
+                        message=f"Source path leakage detected: '{pattern}' found in skill document",
+                        file=str(skill_doc)
+                    ))
+        
+        except Exception as e:
+            report.issues.append(DiagnosticIssue(
+                severity="warning",
+                category="read_error",
+                message=f"Failed to read skill document: {e}",
+                file=str(skill_doc)
+            ))
+    
+    def _check_index_validity(self, skill_id: str, target: str, report: DiagnosticReport) -> None:
+        """检查索引可解析性"""
+        # 查找索引文件
+        if target == "windsurf":
+            data_dir = self.install_root / ".windsurf" / "workflows" / "data" / skill_id
+        elif target == "claude":
+            data_dir = self.install_root / ".claude" / "skills" / skill_id / "resources"
+        elif target == "cursor":
+            data_dir = self.install_root / ".cursor" / "commands" / "data" / skill_id
+        elif target == "github":
+            data_dir = self.install_root / ".github" / "skills" / skill_id
+        else:
+            return
+        
+        if not data_dir.exists():
+            return
+        
+        # 查找所有 index.json
+        for index_file in data_dir.rglob("index.json"):
+            try:
+                with open(index_file, 'r', encoding='utf-8') as f:
+                    index_data = json.load(f)
+                
+                # 检查索引项是否存在
+                items = index_data.get("items", {})
+                for item_id, item_info in items.items():
+                    if isinstance(item_info, dict):
+                        item_file = item_info.get("file")
+                        if item_file:
+                            item_path = index_file.parent / item_file
+                            if not item_path.exists():
+                                report.issues.append(DiagnosticIssue(
+                                    severity="error",
+                                    category="missing_indexed_file",
+                                    message=f"Indexed file not found: {item_file}",
+                                    file=str(index_file)
+                                ))
+            
+            except Exception as e:
+                report.issues.append(DiagnosticIssue(
+                    severity="warning",
+                    category="invalid_index",
+                    message=f"Failed to parse index: {e}",
+                    file=str(index_file)
+                ))

package/src/omni_skill/install.py

@@ -0,0 +1,352 @@
+"""
+Install module: 依赖闭包解析、物化拷贝、manifest 生成
+
+遵循架构规则：
+- Source Space vs Install Space 严格分离
+- 最小闭包原则
+- 禁止 source path 泄漏
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+
+@dataclass
+class FileMapping:
+    """文件映射：Source -> Install"""
+    source: Path
+    target: Path
+    hash: str = ""
+    
+    def to_dict(self) -> dict:
+        return {
+            "source": str(self.source),
+            "target": str(self.target),
+            "hash": self.hash
+        }
+
+
+@dataclass
+class InstallManifest:
+    """安装清单"""
+    version: str = "1.0"
+    skill_id: str = ""
+    install_root: str = ""
+    installed_at: str = ""
+    files: List[FileMapping] = field(default_factory=list)
+    dependencies: Dict[str, List[str]] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "skill_id": self.skill_id,
+            "install_root": self.install_root,
+            "installed_at": self.installed_at,
+            "files": [f.to_dict() for f in self.files],
+            "dependencies": self.dependencies
+        }
+    
+    def save(self, path: Path) -> None:
+        """保存 manifest 到文件"""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, 'w', encoding='utf-8') as f:
+            json.dump(self.to_dict(), f, indent=2, ensure_ascii=False)
+
+
+class DependencyClosureResolver:
+    """依赖闭包解析器"""
+    
+    def __init__(self, source_root: Path):
+        self.source_root = source_root
+        self.visited: Set[Path] = set()
+        self.closure: Set[Path] = set()
+    
+    def resolve(self, skill_dir: Path) -> Set[Path]:
+        """
+        解析 skill 的依赖闭包
+        
+        Args:
+            skill_dir: skill 源目录（Source Space）
+        
+        Returns:
+            依赖闭包文件集合
+        """
+        self.visited.clear()
+        self.closure.clear()
+        
+        # 1. 添加 skill 主要文件
+        self._add_skill_files(skill_dir)
+        
+        # 2. 解析 skillspec.json 中的引用
+        skillspec = skill_dir / "skillspec.json"
+        if skillspec.exists():
+            self._resolve_skillspec(skillspec)
+        
+        # 3. 添加必需不变量
+        self._add_universal_invariants()
+        
+        return self.closure
+    
+    def _add_skill_files(self, skill_dir: Path) -> None:
+        """添加 skill 的主要文件"""
+        # skillspec.json
+        skillspec = skill_dir / "skillspec.json"
+        if skillspec.exists():
+            self.closure.add(skillspec)
+        
+        # references/
+        refs_dir = skill_dir / "references"
+        if refs_dir.exists():
+            for ref_file in refs_dir.rglob("*"):
+                if ref_file.is_file():
+                    self.closure.add(ref_file)
+        
+        # scripts/
+        scripts_dir = skill_dir / "scripts"
+        if scripts_dir.exists():
+            for script_file in scripts_dir.rglob("*"):
+                if script_file.is_file():
+                    self.closure.add(script_file)
+        
+        # assets/
+        assets_dir = skill_dir / "assets"
+        if assets_dir.exists():
+            for asset_file in assets_dir.rglob("*"):
+                if asset_file.is_file():
+                    self.closure.add(asset_file)
+    
+    def _resolve_skillspec(self, skillspec: Path) -> None:
+        """解析 skillspec.json 中的引用"""
+        if skillspec in self.visited:
+            return
+        self.visited.add(skillspec)
+        
+        try:
+            with open(skillspec, 'r', encoding='utf-8') as f:
+                spec = json.load(f)
+            
+            # 解析 references
+            for ref in spec.get("references", []):
+                ref_path = skillspec.parent / ref
+                if ref_path.exists():
+                    self.closure.add(ref_path)
+            
+            # 解析 scripts
+            for script in spec.get("scripts", []):
+                script_path = skillspec.parent / script
+                if script_path.exists():
+                    self.closure.add(script_path)
+            
+            # 解析 assets
+            for asset in spec.get("assets", []):
+                asset_path = skillspec.parent / asset
+                if asset_path.exists():
+                    self.closure.add(asset_path)
+            
+            # 解析 libraries（如果有）
+            libraries = spec.get("libraries", [])
+            if libraries:
+                # 生成 requirements.txt
+                self._generate_requirements(skillspec.parent, libraries)
+        
+        except Exception as e:
+            print(f"Warning: Failed to parse {skillspec}: {e}")
+    
+    def _generate_requirements(self, skill_dir: Path, libraries: List) -> None:
+        """生成 requirements.txt"""
+        req_file = skill_dir / "requirements.txt"
+        
+        lines = []
+        for lib in libraries:
+            if isinstance(lib, dict):
+                name = lib.get('name', '')
+                version = lib.get('version', '')
+                if version:
+                    lines.append(f"{name}{version}")
+                else:
+                    lines.append(name)
+            else:
+                lines.append(str(lib))
+        
+        if lines:
+            with open(req_file, 'w', encoding='utf-8') as f:
+                f.write('\n'.join(lines) + '\n')
+            self.closure.add(req_file)
+    
+    def _add_universal_invariants(self) -> None:
+        """添加必需不变量"""
+        shared_dir = self.source_root / ".shared" / "skill-creator" / "data_packs"
+        
+        # universal/
+        universal_dir = shared_dir / "universal"
+        if universal_dir.exists():
+            # schema
+            schema = universal_dir / "schema.skill.json"
+            if schema.exists():
+                self.closure.add(schema)
+            
+            # output_packs/
+            output_packs_dir = universal_dir / "output_packs"
+            if output_packs_dir.exists():
+                for pack_file in output_packs_dir.rglob("*.json"):
+                    self.closure.add(pack_file)
+            
+            # minimal_checklists/
+            checklists_dir = universal_dir / "minimal_checklists"
+            if checklists_dir.exists():
+                for checklist_file in checklists_dir.rglob("*.json"):
+                    self.closure.add(checklist_file)
+
+
+class SkillInstaller:
+    """Skill 安装器：物化拷贝到 Install Space"""
+    
+    def __init__(self, source_root: Path, install_root: Path):
+        self.source_root = source_root
+        self.install_root = install_root
+        self.resolver = DependencyClosureResolver(source_root)
+    
+    def install(self, skill_id: str, target: str = "windsurf") -> InstallManifest:
+        """
+        安装 skill 到 Install Space
+        
+        Args:
+            skill_id: skill ID
+            target: 目标 AI 助手 (windsurf/claude/cursor/github)
+        
+        Returns:
+            InstallManifest
+        """
+        skill_dir = self.source_root / "skills" / skill_id
+        if not skill_dir.exists():
+            raise FileNotFoundError(f"Skill not found: {skill_dir}")
+        
+        # 1. 解析依赖闭包
+        closure = self.resolver.resolve(skill_dir)
+        print(f"Resolved {len(closure)} files in dependency closure")
+        
+        # 2. 确定 install 目标目录
+        install_target_root = self._get_install_target_root(target, skill_id)
+        
+        # 3. 物化拷贝
+        manifest = InstallManifest(
+            skill_id=skill_id,
+            install_root=str(install_target_root.relative_to(self.install_root)),
+            installed_at=datetime.utcnow().isoformat() + "Z"
+        )
+        
+        for source_file in closure:
+            target_file = self._map_to_install_space(source_file, skill_id, target)
+            self._copy_file(source_file, target_file)
+            
+            # 计算哈希
+            file_hash = self._compute_hash(target_file)
+            
+            mapping = FileMapping(
+                source=source_file.relative_to(self.source_root),
+                target=target_file.relative_to(self.install_root),
+                hash=file_hash
+            )
+            manifest.files.append(mapping)
+        
+        # 4. 收集依赖信息
+        manifest.dependencies = self._collect_dependencies(skill_dir)
+        
+        # 5. 保存 manifest
+        manifest_path = install_target_root / ".install_manifest.json"
+        manifest.save(manifest_path)
+        
+        print(f"Installed {skill_id} to {install_target_root}")
+        print(f"Manifest saved to {manifest_path}")
+        
+        return manifest
+    
+    def _get_install_target_root(self, target: str, skill_id: str) -> Path:
+        """获取 install 目标根目录"""
+        if target == "windsurf":
+            return self.install_root / ".windsurf" / "workflows" / "data" / skill_id
+        elif target == "claude":
+            return self.install_root / ".claude" / "skills" / skill_id / "resources"
+        elif target == "cursor":
+            return self.install_root / ".cursor" / "commands" / "data" / skill_id
+        elif target == "github":
+            return self.install_root / ".github" / "skills" / skill_id
+        else:
+            raise ValueError(f"Unknown target: {target}")
+    
+    def _map_to_install_space(self, source_file: Path, skill_id: str, target: str) -> Path:
+        """映射 Source Space 路径到 Install Space 路径"""
+        install_target_root = self._get_install_target_root(target, skill_id)
+        
+        # 计算相对路径
+        try:
+            # 尝试相对于 skills/{skill_id}
+            rel_path = source_file.relative_to(self.source_root / "skills" / skill_id)
+            return install_target_root / rel_path
+        except ValueError:
+            pass
+        
+        try:
+            # 尝试相对于 .shared/skill-creator/data_packs
+            rel_path = source_file.relative_to(self.source_root / ".shared" / "skill-creator" / "data_packs")
+            return install_target_root / "data_packs" / rel_path
+        except ValueError:
+            pass
+        
+        # 兜底：使用文件名
+        return install_target_root / source_file.name
+    
+    def _copy_file(self, source: Path, target: Path) -> None:
+        """拷贝文件"""
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
+    
+    def _compute_hash(self, file_path: Path) -> str:
+        """计算文件哈希"""
+        sha256 = hashlib.sha256()
+        with open(file_path, 'rb') as f:
+            for chunk in iter(lambda: f.read(4096), b''):
+                sha256.update(chunk)
+        return f"sha256:{sha256.hexdigest()}"
+    
+    def _collect_dependencies(self, skill_dir: Path) -> Dict[str, List[str]]:
+        """收集依赖信息"""
+        deps = {
+            "libraries": [],
+            "data_packs": []
+        }
+        
+        # 读取 skillspec.json
+        skillspec = skill_dir / "skillspec.json"
+        if skillspec.exists():
+            try:
+                with open(skillspec, 'r', encoding='utf-8') as f:
+                    spec = json.load(f)
+                
+                # 收集 libraries
+                libraries = spec.get("libraries", [])
+                for lib in libraries:
+                    if isinstance(lib, dict):
+                        name = lib.get('name', '')
+                        if name:
+                            deps["libraries"].append(name)
+                    else:
+                        deps["libraries"].append(str(lib))
+            
+            except Exception as e:
+                print(f"Warning: Failed to parse {skillspec}: {e}")
+        
+        # 收集 data_packs（固定的必需不变量）
+        deps["data_packs"] = [
+            "universal/output_packs",
+            "universal/minimal_checklists",
+            "universal/schema"
+        ]
+        
+        return deps

package/src/skill_creator/core/builder.py

@@ -133,6 +133,22 @@ class SkillBuilder:
                 }
             ]
         
+        # 添加三方库推荐信息到第一个步骤的 notes
+        if steps and ctx.plan and ctx.plan.libraries:
+            lib_notes = ["\n\n**推荐的第三方库**:"]
+            for lib in ctx.plan.libraries:
+                lib_notes.append(f"- `{lib.name}`: {lib.purpose}")
+                if lib.pypi_link:
+                    lib_notes.append(f"  - 安装: `pip install {lib.name}`")
+                if lib.docs_link:
+                    lib_notes.append(f"  - 文档: {lib.docs_link}")
+            
+            # 将库信息添加到第一个步骤的 notes
+            if steps[0].get("notes"):
+                steps[0]["notes"] += "\n".join(lib_notes)
+            else:
+                steps[0]["notes"] = "\n".join(lib_notes)
+        
         return steps
     
     def _generate_triggers(self, ctx: SkillCreatorContext) -> list[str]:

package/src/skill_creator/core/orchestrator.py

@@ -162,6 +162,18 @@ class PlanOrchestrator:
         summary_parts.append("")
         summary_parts.append(f"**输出形式**: {self._get_pack_description(output_pack)}")
         
+        # 添加推荐的三方库信息
+        libraries = self._get_recommended_libraries(ctx)
+        if libraries:
+            summary_parts.append("")
+            summary_parts.append("**推荐的第三方库**:")
+            for lib in libraries:
+                summary_parts.append(f"- `{lib.name}`: {lib.purpose}")
+                if lib.reason:
+                    summary_parts.append(f"  - 推荐理由: {lib.reason}")
+                if lib.pypi_link:
+                    summary_parts.append(f"  - PyPI: {lib.pypi_link}")
+        
         return "\n".join(summary_parts)
     
     def _get_pack_description(self, pack: str) -> str:

package/src/skill_creator/spec/model.py

@@ -63,6 +63,7 @@ class SkillSpec:
     references: List[str] = field(default_factory=list)
     scripts: List[str] = field(default_factory=list)
     assets: List[str] = field(default_factory=list)
+    libraries: List[Any] = field(default_factory=list)  # Recommended third-party libraries
 
     @staticmethod
     def from_path(path: Path) -> "SkillSpec":
@@ -84,6 +85,7 @@ class SkillSpec:
             references=[str(x) for x in _as_list(d.get("references"))],
             scripts=[str(x) for x in _as_list(d.get("scripts"))],
             assets=[str(x) for x in _as_list(d.get("assets"))],
+            libraries=_as_list(d.get("libraries")),
         )
 
     def validate_basic(self) -> List[str]:

package/src/skill_creator/targets/README.md

@@ -8,7 +8,28 @@
 - **claude.py**：生成 `.claude/skills/<skill>/SKILL.md`（兼容输出）。
 - **cursor.py**：生成 `.cursor/commands/<skill>.md`（兼容输出）。
 - **github_skills.py**：生成 `.github/skills/<skill>/SKILL.md`（兼容输出）。
-- **common.py**：渲染共用逻辑。
+- **common.py**：公共渲染函数。
+
+## 公共逻辑复用
+
+所有 target 都使用 `common.py` 中的公共函数，避免代码重复：
+
+- `_render_steps()` - 渲染 workflow steps
+- `_render_resources()` - 渲染 references/scripts/assets
+- `_render_libraries()` - 渲染推荐的第三方库信息
+- `_render_prerequisites()` - 渲染 Prerequisites 部分（包含三方库）
+- `_render_footer()` - 渲染页脚
+
+### 三方库信息展示
+
+**所有 target 都会展示推荐的三方库信息**，确保用户知道需要安装哪些依赖：
+
+- ✅ **windsurf.py** - 在 Prerequisites 部分展示（包含 Python 版本检查）
+- ✅ **claude.py** - 在 Prerequisites 部分展示
+- ✅ **cursor.py** - 在 Prerequisites 部分展示
+- ✅ **github_skills.py** - 在 Prerequisites 部分展示
+
+这确保了无论用户使用哪个 AI 助手，都能获得完整的依赖信息和安装指导。
 
 ## 约定
 

package/src/skill_creator/targets/claude.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from ..spec.model import SkillSpec
 from ..util.frontmatter import dump_frontmatter
-from .common import _render_steps, _render_resources, _render_footer
+from .common import _render_steps, _render_resources, _render_footer, _render_prerequisites
 
 
 def render_claude_skill_md(spec: SkillSpec) -> str:
@@ -16,6 +16,11 @@ def render_claude_skill_md(spec: SkillSpec) -> str:
     body.append(spec.description)
     body.append("")
 
+    # Prerequisites (三方库信息)
+    prerequisites = _render_prerequisites(spec, include_python_check=False)
+    if prerequisites:
+        body.append(prerequisites)
+
     if spec.triggers:
         body.append("## When to use (examples of user requests)")
         for t in spec.triggers:

package/src/skill_creator/targets/common.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import List
+from typing import Any, List
 
 from ..spec.model import SkillSpec, WorkflowStep
 
@@ -41,6 +41,88 @@ def _render_resources(spec: SkillSpec) -> str:
     return "\n".join(lines)
 
 
+def _render_libraries(spec: SkillSpec) -> str:
+    """
+    渲染推荐的第三方库信息（公共逻辑）。
+    所有 target 都应该展示三方库信息。
+    """
+    if not hasattr(spec, 'libraries') or not spec.libraries:
+        return ""
+    
+    lines = []
+    lines.append("**推荐的第三方库**:")
+    lines.append("")
+    
+    for lib in spec.libraries:
+        if isinstance(lib, dict):
+            lib_name = lib.get('name', '')
+            lib_purpose = lib.get('purpose', '')
+            lib_pypi = lib.get('pypi_link', '')
+            lib_docs = lib.get('docs_link', '')
+            
+            lines.append(f"- `{lib_name}`: {lib_purpose}")
+            if lib_pypi:
+                lines.append(f"  - 安装: `pip install {lib_name}`")
+                lines.append(f"  - PyPI: {lib_pypi}")
+            if lib_docs:
+                lines.append(f"  - 文档: {lib_docs}")
+        else:
+            lines.append(f"- `{lib}`")
+    
+    lines.append("")
+    
+    # 生成一键安装命令
+    lib_names = []
+    for lib in spec.libraries:
+        if isinstance(lib, dict):
+            lib_names.append(lib.get('name', ''))
+        else:
+            lib_names.append(str(lib))
+    
+    if lib_names:
+        lines.append("```bash")
+        lines.append("# 安装所有依赖")
+        lines.append("pip install " + " ".join(lib_names))
+        lines.append("```")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def _render_prerequisites(spec: SkillSpec, include_python_check: bool = True) -> str:
+    """
+    渲染 Prerequisites 部分（公共逻辑）。
+    
+    Args:
+        spec: SkillSpec 对象
+        include_python_check: 是否包含 Python 版本检查
+    
+    Returns:
+        Prerequisites 部分的 Markdown 文本
+    """
+    has_prerequisites = spec.scripts or (hasattr(spec, 'libraries') and spec.libraries)
+    if not has_prerequisites:
+        return ""
+    
+    lines = []
+    lines.append("## Prerequisites")
+    lines.append("")
+    
+    # Python 版本检查（可选）
+    if include_python_check and spec.scripts:
+        lines.append("```bash")
+        lines.append("python3 --version || python --version")
+        lines.append("```")
+        lines.append("")
+    
+    # 推荐的第三方库
+    lib_section = _render_libraries(spec)
+    if lib_section:
+        lines.append(lib_section)
+    
+    return "\n".join(lines)
+
+
 def _render_footer() -> str:
     ts = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
     return f"\n---\nGenerated by neo-skill at {ts}.\n"

package/src/skill_creator/targets/cursor.py

@@ -1,11 +1,18 @@
 from __future__ import annotations
 
 from ..spec.model import SkillSpec
+from .common import _render_prerequisites
 
 
 def render_cursor_command_md(spec: SkillSpec) -> str:
     # Cursor's command palette prompts are typically Markdown instructions.
     lines = [f"# {spec.name}", "", spec.description, ""]
+    
+    # Prerequisites (三方库信息)
+    prerequisites = _render_prerequisites(spec, include_python_check=False)
+    if prerequisites:
+        lines.append(prerequisites)
+    
     if spec.triggers:
         lines.append("## When to use")
         lines.extend([f"- {t}" for t in spec.triggers])

package/src/skill_creator/targets/github_skills.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from ..spec.model import SkillSpec
 from ..util.frontmatter import dump_frontmatter
-from .common import _render_steps, _render_resources, _render_footer
+from .common import _render_steps, _render_resources, _render_footer, _render_prerequisites
 
 
 def render_github_skill_md(spec: SkillSpec) -> str:
@@ -22,6 +22,12 @@ def render_github_skill_md(spec: SkillSpec) -> str:
     body.append("## Overview")
     body.append(spec.description)
     body.append("")
+    
+    # Prerequisites (三方库信息)
+    prerequisites = _render_prerequisites(spec, include_python_check=False)
+    if prerequisites:
+        body.append(prerequisites)
+    
     if spec.triggers:
         body.append("## Triggers")
         for t in spec.triggers:

package/src/skill_creator/targets/windsurf.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from ..spec.model import SkillSpec
+from .common import _render_prerequisites
 
 
 def render_windsurf_workflow_md(spec: SkillSpec) -> str:
@@ -26,16 +27,10 @@ def render_windsurf_workflow_md(spec: SkillSpec) -> str:
         "",
     ]
 
-    # Prerequisites (if scripts exist)
-    if spec.scripts:
-        lines.extend([
-            "## Prerequisites",
-            "",
-            "```bash",
-            "python3 --version || python --version",
-            "```",
-            "",
-        ])
+    # Prerequisites (使用公共逻辑)
+    prerequisites = _render_prerequisites(spec, include_python_check=True)
+    if prerequisites:
+        lines.append(prerequisites)
 
     # Triggers
     if spec.triggers: