neo-skill 0.1.17 → 0.1.19

package/README.md

@@ -22,14 +22,17 @@ pip install neo-skill
 ### 命令行工具（安装后）
 
 ```bash
-# 初始化技能
-omni-skill init --ai claude
+# 初始化技能（从 npm 包安装所有 skills）
+omni-skill init --ai windsurf
 
-# 生成技能输出
-skill-creator generate skills/skill-name/skillspec.json
+# 手动安装本地创建的 skill
+omni-skill install ./skills/my-new-skill
 
-# 验证技能
-skill-creator validate skills/skill-name/skillspec.json
+# 更新 npm 包并重新初始化
+omni-skill update
+
+# 查看帮助
+omni-skill --help
 ```
 
 ### 直接运行 Python 模块（开发模式）
@@ -72,29 +75,51 @@ python -m skill_creator.cli validate skills/skill-name/skillspec.json
 
 ### 使用场景
 
-**初始化技能文件**
+**1. 初始化技能（首次使用）**
 ```bash
 # 初始化指定 AI 助手的技能文件
-omni-skill init --ai claude
 omni-skill init --ai windsurf
+omni-skill init --ai claude
 omni-skill init --ai all  # 初始化所有支持的 AI 助手
-
-# 更新（基于上次 init 的配置）
-omni-skill update
 ```
 
-**生成和验证技能**
+这会：
+- 从 npm 包同步 skills/ 和 .shared/ 到当前目录
+- 为所有 skills 生成**指定 AI 助手**的输出文件
+  - `--ai windsurf` → 只生成 `.windsurf/workflows/`
+  - `--ai claude` → 只生成 `.claude/skills/`
+  - `--ai all` → 生成所有目标
+- 保存初始化状态到 .neo-skill.json
+
+**2. 使用 skill-creator 创建新 skill**
+
+在 IDE 中输入 `/skill-creator`（Windsurf）或使用其他 AI 助手的触发方式，按照对话式流程创建新 skill。
+
+**3. 安装刚创建的 skill**
 ```bash
-# 生成技能输出
-skill-creator generate skills/skill-name/skillspec.json
+# 安装单个 skill
+omni-skill install ./skills/my-new-skill
 
-# 验证技能
-skill-creator validate skills/skill-name/skillspec.json
+# 或安装整个 skills 目录
+omni-skill install ./skills
+```
 
-# 打包 Claude 技能
-skill-creator package --target claude --skill skill-name
+这会：
+- 复制 skill 到当前目录的 skills/ 文件夹
+- 为该 skill 生成**所有 AI 助手**的输出文件（.windsurf, .claude, .cursor, .github）
+
+**注意**：与 `init` 不同，`install` 命令总是生成所有 AI 目标的输出，以确保最大兼容性。
+
+**4. 更新 npm 包**
+```bash
+# 更新到最新版本并重新初始化
+omni-skill update
 ```
 
+这会：
+- 运行 `npm install neo-skill@latest`
+- 重新执行 `omni-skill init`（使用保存的 AI 目标）
+
 **在其他项目中使用**
 将 neo-skill 仓库克隆到你的项目中（例如 `vendor/neo-skill/`），然后：
 1. 设置 PYTHONPATH：`export PYTHONPATH=$PWD/vendor/neo-skill/src:$PYTHONPATH`

package/package.json

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

package/src/omni_skill/README.md

@@ -10,3 +10,56 @@
 ## 约定
 
 - 同步规则与生成行为应保持确定性（同输入得到同输出）。
+
+## Commands
+
+### `omni-skill init --ai <target>`
+Initialize skills for target AI assistants.
+
+**Usage:**
+```bash
+omni-skill init --ai windsurf
+omni-skill init --ai claude
+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 **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.
+
+**Usage:**
+```bash
+# Install a single skill
+omni-skill install ./skills/my-new-skill
+
+# Install all skills from a directory
+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)
+
+**Note:** Unlike `init`, the `install` command always generates outputs for all AI targets to ensure maximum compatibility.
+
+### `omni-skill update`
+Update npm package and re-initialize skills.
+
+**Usage:**
+```bash
+omni-skill update
+```
+
+**What it does:**
+1. Runs `npm install neo-skill@latest`
+2. Re-runs `omni-skill init` with saved AI targets

package/src/omni_skill/cli.py

@@ -4,7 +4,7 @@ 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
 
@@ -185,13 +185,96 @@ def _generate_outputs_best_effort(pkg_root: Path, cwd: Path) -> None:
     print("\nGenerating skill outputs from skillspec.json ...")
     for spec_path in specs:
         try:
-            ns = argparse.Namespace(repo_root=str(cwd), spec=str(spec_path))
+            ns = argparse.Namespace(repo_root=str(cwd), spec=str(spec_path), all=True)
             cmd_generate(ns)
         except SystemExit as e:
             rel = spec_path.relative_to(cwd) if spec_path.is_relative_to(cwd) else spec_path
             print(f"  Skipping generator for {rel} (exit {e.code})")
 
 
+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 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}")
+        return 1
+    
+    specs = sorted(skills_dir.glob("*/skillspec.json"))
+    if not specs:
+        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
+        print(f"  Installing skill: {skill_name}")
+        
+        # Copy skill to cwd/skills if not already there
+        dest_skill_dir = cwd / "skills" / skill_name
+        if spec_path.parent.resolve() != dest_skill_dir.resolve():
+            dest_skill_dir.parent.mkdir(parents=True, exist_ok=True)
+            if dest_skill_dir.exists():
+                import shutil
+                shutil.rmtree(dest_skill_dir)
+            shutil.copytree(spec_path.parent, dest_skill_dir)
+            print(f"    Copied to: {dest_skill_dir}")
+        
+        # Generate outputs for specified targets
+        try:
+            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})")
+    
+    return 0
+
+
 def _handle_init(selected_ais: List[str], mode: str) -> int:
     pkg_root = _get_pkg_root()
     cwd = Path.cwd().resolve()
@@ -201,7 +284,12 @@ def _handle_init(selected_ais: List[str], mode: str) -> int:
     sync_pairs = _build_sync_pairs(effective_ais)
     print("Initializing skills in:", cwd)
     _perform_sync(pkg_root, cwd, sync_pairs)
-    _generate_outputs_best_effort(pkg_root, cwd)
+    
+    # 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, selected_ais=selected_ais)
+    
     _write_version_files(cwd, effective_ais, version)
     print("\nDone! neo-skill initialized.")
 
@@ -222,11 +310,59 @@ def _cmd_init(args: argparse.Namespace) -> int:
     return _handle_init(resolved["selected"], "init")
 
 
+def _cmd_install(args: argparse.Namespace) -> int:
+    """
+    Install skill(s) from a local directory.
+    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()
+    
+    if not skill_path.exists():
+        raise SystemExit(f"Path not found: {skill_path}")
+    
+    # Check if it's a single skill directory (contains skillspec.json)
+    if (skill_path / "skillspec.json").exists():
+        # Single skill - generate for all targets
+        temp_skills_dir = skill_path.parent
+        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, selected_ais=None)
+    
+    else:
+        raise SystemExit(f"Invalid path: {skill_path}. Must be a skill directory or skills directory.")
+
+
 def _cmd_update(args: argparse.Namespace) -> int:
+    """
+    Update npm package and re-initialize skills.
+    """
+    import subprocess
+    
     cwd = Path.cwd().resolve()
     state = _read_init_state(cwd)
     if not state["ok"]:
         raise SystemExit(state["error"])
+    
+    print("Updating neo-skill npm package...")
+    result = subprocess.run(
+        ["npm", "install", "neo-skill@latest"],
+        cwd=cwd,
+        capture_output=True,
+        text=True
+    )
+    
+    if result.returncode != 0:
+        print(f"Warning: npm install failed: {result.stderr}")
+        print("Continuing with re-initialization...")
+    else:
+        print("Package updated successfully.")
+    
+    print("\nRe-initializing skills...")
     return _handle_init(state["selected"], "update")
 
 
@@ -253,7 +389,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_init.add_argument("--ai", action="append", help="Target AI (can be repeated)")
     p_init.set_defaults(func=_cmd_init)
 
-    p_update = sub.add_parser("update", help="Update skills based on previous init state")
+    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)
+
+    p_update = sub.add_parser("update", help="Update npm package and re-initialize skills")
     p_update.set_defaults(func=_cmd_update)
 
     return p