neo-skill 0.1.11

package/.shared/skill-creator/scripts/search.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+Skill Creator Search Tool
+
+Search skill patterns, templates, and reasoning rules.
+Inspired by ui-ux-pro-max's multi-domain search architecture.
+
+Usage:
+    python3 .shared/skill-creator/scripts/search.py "<query>" --domain <domain>
+    python3 .shared/skill-creator/scripts/search.py "<query>" --skill-system
+    python3 .shared/skill-creator/scripts/search.py "<query>" --stack windsurf
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+SCRIPT_DIR = Path(__file__).parent
+DATA_DIR = SCRIPT_DIR.parent / "data"
+
+
+def load_json(path: Path) -> Dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_csv(path: Path) -> List[Dict[str, str]]:
+    with path.open(encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def search_csv(data: List[Dict[str, str]], query: str, fields: Optional[List[str]] = None) -> List[Dict[str, str]]:
+    """Search CSV data for matching rows."""
+    query_lower = query.lower()
+    keywords = query_lower.split()
+    results = []
+    
+    for row in data:
+        score = 0
+        search_fields = fields or list(row.keys())
+        text = " ".join(str(row.get(f, "")) for f in search_fields).lower()
+        
+        for kw in keywords:
+            if kw in text:
+                score += 1
+        
+        if score > 0:
+            results.append((score, row))
+    
+    results.sort(key=lambda x: -x[0])
+    return [r[1] for r in results]
+
+
+def search_domain(domain: str, query: str, max_results: int = 5) -> List[Dict[str, str]]:
+    """Search a specific domain."""
+    domains_config = load_json(DATA_DIR / "domains.json")
+    
+    if domain not in domains_config["domains"]:
+        print(f"Unknown domain: {domain}", file=sys.stderr)
+        print(f"Available: {', '.join(domains_config['domains'].keys())}", file=sys.stderr)
+        sys.exit(1)
+    
+    domain_info = domains_config["domains"][domain]
+    data_file = DATA_DIR / domain_info["data_file"]
+    
+    if not data_file.exists():
+        print(f"Data file not found: {data_file}", file=sys.stderr)
+        sys.exit(1)
+    
+    data = load_csv(data_file)
+    results = search_csv(data, query)
+    return results[:max_results]
+
+
+def search_skill_system(query: str, project_name: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Generate a complete skill system recommendation.
+    Searches all domains in parallel and applies reasoning rules.
+    """
+    domains_config = load_json(DATA_DIR / "domains.json")
+    reasoning_rules = load_csv(DATA_DIR / domains_config["reasoning_file"])
+    
+    # Search all domains
+    results = {}
+    for domain in domains_config["domains"]:
+        results[domain] = search_domain(domain, query, max_results=3)
+    
+    # Apply reasoning rules
+    applicable_rules = search_csv(reasoning_rules, query, ["condition"])
+    
+    # Build recommendation
+    recommendation = {
+        "project": project_name or "Untitled Skill",
+        "query": query,
+        "workflow_pattern": results.get("workflow", [{}])[0] if results.get("workflow") else {},
+        "output_pattern": results.get("output", [{}])[0] if results.get("output") else {},
+        "resource_strategy": results.get("resource", [{}])[0] if results.get("resource") else {},
+        "trigger_examples": [r.get("example_triggers", "") for r in results.get("trigger", [])[:3]],
+        "applicable_rules": [
+            {"condition": r["condition"], "recommendation": r["recommendation"], "rationale": r["rationale"]}
+            for r in applicable_rules[:5]
+        ],
+    }
+    
+    return recommendation
+
+
+def search_stack(stack: str, query: str) -> Dict[str, Any]:
+    """Get stack-specific guidelines."""
+    domains_config = load_json(DATA_DIR / "domains.json")
+    
+    if stack not in domains_config["stacks"]:
+        print(f"Unknown stack: {stack}", file=sys.stderr)
+        print(f"Available: {', '.join(domains_config['stacks'].keys())}", file=sys.stderr)
+        sys.exit(1)
+    
+    stack_info = domains_config["stacks"][stack]
+    return {
+        "stack": stack,
+        "query": query,
+        "description": stack_info["description"],
+        "format": stack_info["format"],
+        "output_path": stack_info["output_path"],
+        "priority": stack_info["priority"],
+    }
+
+
+def format_domain_results(domain: str, results: List[Dict[str, str]]) -> str:
+    """Format domain search results."""
+    if not results:
+        return f"No results found for domain '{domain}'"
+    
+    lines = [f"## {domain.upper()} Domain Results", ""]
+    for i, row in enumerate(results, 1):
+        lines.append(f"### {i}. {row.get('name', row.get('id', 'Unknown'))}")
+        for key, value in row.items():
+            if key not in ("id", "name") and value:
+                lines.append(f"- **{key}**: {value}")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def format_skill_system(rec: Dict[str, Any]) -> str:
+    """Format skill system recommendation."""
+    lines = [
+        "╔════════════════════════════════════════════════════════════════╗",
+        f"║  SKILL SYSTEM: {rec['project']:<47} ║",
+        "╠════════════════════════════════════════════════════════════════╣",
+        f"║  Query: {rec['query']:<54} ║",
+        "╠════════════════════════════════════════════════════════════════╣",
+    ]
+    
+    # Workflow pattern
+    wp = rec.get("workflow_pattern", {})
+    if wp:
+        lines.append(f"║  WORKFLOW: {wp.get('name', 'N/A'):<51} ║")
+        lines.append(f"║    {wp.get('description', '')[:58]:<58} ║")
+    
+    # Output pattern
+    op = rec.get("output_pattern", {})
+    if op:
+        lines.append(f"║  OUTPUT: {op.get('name', 'N/A'):<53} ║")
+        lines.append(f"║    {op.get('description', '')[:58]:<58} ║")
+    
+    # Resource strategy
+    rs = rec.get("resource_strategy", {})
+    if rs:
+        lines.append(f"║  RESOURCES: {rs.get('name', 'N/A'):<50} ║")
+    
+    lines.append("╠════════════════════════════════════════════════════════════════╣")
+    lines.append("║  APPLICABLE RULES:                                             ║")
+    for rule in rec.get("applicable_rules", [])[:3]:
+        cond = rule.get("condition", "")[:20]
+        rec_text = rule.get("recommendation", "")[:35]
+        lines.append(f"║    • {cond}: {rec_text:<38} ║")
+    
+    lines.append("╚════════════════════════════════════════════════════════════════╝")
+    
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Search skill patterns, templates, and reasoning rules"
+    )
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", help="Search specific domain")
+    parser.add_argument("--skill-system", "-s", action="store_true", help="Generate complete skill system")
+    parser.add_argument("--stack", help="Get stack-specific guidelines")
+    parser.add_argument("--project", "-p", help="Project name (for --skill-system)")
+    parser.add_argument("--max-results", "-n", type=int, default=5, help="Max results per domain")
+    parser.add_argument("--format", "-f", choices=["text", "json"], default="text", help="Output format")
+    
+    args = parser.parse_args()
+    
+    if args.skill_system:
+        result = search_skill_system(args.query, args.project)
+        if args.format == "json":
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_skill_system(result))
+    elif args.stack:
+        result = search_stack(args.stack, args.query)
+        if args.format == "json":
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(f"Stack: {result['stack']}")
+            print(f"Format: {result['format']}")
+            print(f"Output: {result['output_path']}")
+    elif args.domain:
+        results = search_domain(args.domain, args.query, args.max_results)
+        if args.format == "json":
+            print(json.dumps(results, indent=2, ensure_ascii=False))
+        else:
+            print(format_domain_results(args.domain, results))
+    else:
+        # Default: search all domains briefly
+        domains_config = load_json(DATA_DIR / "domains.json")
+        for domain in domains_config["domains"]:
+            results = search_domain(domain, args.query, max_results=2)
+            if results:
+                print(format_domain_results(domain, results))
+
+
+if __name__ == "__main__":
+    main()

package/.shared/skill-creator/scripts/validate.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Skill Validator - Validate skillspec.json and generated outputs
+
+Usage:
+    python3 .shared/skill-creator/scripts/validate.py skills/<skill>/skillspec.json
+    python3 .shared/skill-creator/scripts/validate.py skills/<skill>/skillspec.json --strict
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+SCRIPT_DIR = Path(__file__).parent
+DATA_DIR = SCRIPT_DIR.parent / "data"
+REPO_ROOT = SCRIPT_DIR.parent.parent.parent
+
+
+def load_validation_rules() -> List[Dict[str, str]]:
+    """Load validation rules from CSV."""
+    rules_path = DATA_DIR / "validation-rules.csv"
+    if not rules_path.exists():
+        return []
+    with rules_path.open(encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def validate_kebab_case(name: str) -> bool:
+    """Check if name is valid kebab-case."""
+    return bool(re.match(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$", name))
+
+
+def validate_spec(spec: Dict[str, Any], spec_path: Path) -> List[Tuple[str, str, str]]:
+    """
+    Validate skillspec.json structure and content.
+    Returns list of (severity, rule_id, message) tuples.
+    """
+    errors: List[Tuple[str, str, str]] = []
+    
+    # name validation
+    name = spec.get("name", "")
+    if not name:
+        errors.append(("error", "name_required", "name is required"))
+    elif not validate_kebab_case(name):
+        errors.append(("error", "name_kebab", f"name '{name}' is not valid kebab-case"))
+    
+    # description validation
+    desc = spec.get("description", "")
+    if not desc:
+        errors.append(("error", "description_required", "description is required"))
+    elif len(desc) < 20:
+        errors.append(("warning", "description_short", "description is very short (<20 chars)"))
+    
+    # questions validation
+    questions = spec.get("questions", [])
+    if len(questions) > 10:
+        errors.append(("error", "questions_max_10", f"questions must be <= 10 (got {len(questions)})"))
+    
+    # triggers validation
+    triggers = spec.get("triggers", [])
+    if len(triggers) < 3:
+        errors.append(("warning", "triggers_min_3", f"recommend at least 3 triggers (got {len(triggers)})"))
+    
+    # workflow validation
+    workflow = spec.get("workflow", {})
+    if not workflow:
+        errors.append(("error", "workflow_required", "workflow is required"))
+    else:
+        workflow_type = workflow.get("type", "")
+        if workflow_type not in ("sequential", "conditional"):
+            errors.append(("error", "workflow_type_invalid", f"workflow.type must be sequential or conditional"))
+        
+        steps = workflow.get("steps", [])
+        if not steps:
+            errors.append(("error", "steps_not_empty", "workflow.steps must not be empty"))
+        else:
+            for i, step in enumerate(steps):
+                if not step.get("id"):
+                    errors.append(("error", "step_id_required", f"step[{i}].id is required"))
+                if not step.get("title"):
+                    errors.append(("error", "step_title_required", f"step[{i}].title is required"))
+                
+                notes = step.get("notes", "")
+                if len(notes) > 500:
+                    errors.append(("warning", "notes_max_length", 
+                                   f"step[{i}].notes is long ({len(notes)} chars) - consider using references/"))
+    
+    # freedom_level validation
+    freedom = spec.get("freedom_level", "low")
+    if freedom not in ("low", "medium", "high"):
+        errors.append(("error", "freedom_level_invalid", "freedom_level must be low, medium, or high"))
+    
+    return errors
+
+
+def validate_claude_output(skill_name: str, repo_root: Path) -> List[Tuple[str, str, str]]:
+    """Validate Claude SKILL.md strict frontmatter."""
+    errors: List[Tuple[str, str, str]] = []
+    
+    skill_md = repo_root / ".claude" / "skills" / skill_name / "SKILL.md"
+    if not skill_md.exists():
+        return errors  # Not generated yet, skip
+    
+    content = skill_md.read_text(encoding="utf-8")
+    
+    # Check frontmatter
+    if not content.startswith("---\n"):
+        errors.append(("error", "claude_frontmatter_missing", "Claude SKILL.md missing YAML frontmatter"))
+        return errors
+    
+    try:
+        end_idx = content.index("\n---\n", 4)
+        frontmatter = content[4:end_idx]
+    except ValueError:
+        errors.append(("error", "claude_frontmatter_unterminated", "Claude SKILL.md frontmatter not closed"))
+        return errors
+    
+    # Parse frontmatter keys
+    keys = set()
+    for line in frontmatter.splitlines():
+        if ":" in line:
+            key = line.split(":")[0].strip()
+            if key:
+                keys.add(key)
+    
+    allowed_keys = {"name", "description"}
+    extra_keys = keys - allowed_keys
+    if extra_keys:
+        errors.append(("error", "claude_frontmatter_strict", 
+                       f"Claude frontmatter has extra keys (strict mode): {extra_keys}"))
+    
+    return errors
+
+
+def validate_banned_files(skill_name: str, repo_root: Path) -> List[Tuple[str, str, str]]:
+    """Check for banned files in skill bundles."""
+    errors: List[Tuple[str, str, str]] = []
+    
+    banned = {"README.md", "CHANGELOG.md", "INSTALL.md", "LICENSE", "LICENSE.md"}
+    
+    for target_dir in [
+        repo_root / ".claude" / "skills" / skill_name,
+        repo_root / ".github" / "skills" / skill_name,
+    ]:
+        if not target_dir.exists():
+            continue
+        
+        for path in target_dir.rglob("*"):
+            if path.is_file() and path.name in banned:
+                errors.append(("error", "no_banned_files", f"Banned file in skill bundle: {path}"))
+    
+    return errors
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Validate skillspec.json and outputs")
+    parser.add_argument("spec", help="Path to skillspec.json")
+    parser.add_argument("--strict", action="store_true", help="Treat warnings as errors")
+    parser.add_argument("--repo-root", "-r", default=str(REPO_ROOT), help="Repository root")
+    
+    args = parser.parse_args()
+    
+    spec_path = Path(args.spec).resolve()
+    repo_root = Path(args.repo_root).resolve()
+    
+    if not spec_path.exists():
+        print(f"ERROR: Spec not found: {spec_path}", file=sys.stderr)
+        sys.exit(1)
+    
+    spec = json.loads(spec_path.read_text(encoding="utf-8"))
+    skill_name = spec.get("name", "")
+    
+    all_errors: List[Tuple[str, str, str]] = []
+    
+    # Validate spec
+    all_errors.extend(validate_spec(spec, spec_path))
+    
+    # Validate outputs
+    all_errors.extend(validate_claude_output(skill_name, repo_root))
+    all_errors.extend(validate_banned_files(skill_name, repo_root))
+    
+    # Report
+    has_errors = False
+    has_warnings = False
+    
+    for severity, rule_id, message in all_errors:
+        prefix = "ERROR" if severity == "error" else "WARN"
+        print(f"[{prefix}] {rule_id}: {message}")
+        
+        if severity == "error":
+            has_errors = True
+        else:
+            has_warnings = True
+    
+    if not all_errors:
+        print("✓ Validation passed")
+        sys.exit(0)
+    
+    if has_errors or (args.strict and has_warnings):
+        sys.exit(1)
+    
+    print("✓ Validation passed with warnings")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liuminxin45
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# neo-skill（多 AI 助手技能生成器）
+
+一个确定性的 **skill-creator** 仓库。
+
+**GitHub**: https://github.com/liuminxin45/neo-skill
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g neo-skill
+```
+
+**前置依赖**：需要安装 Python 3.8+（命令行执行依赖 Python）
+
+## 功能说明
+- 使用 canonical `skills/<skill>/skillspec.json` 作为单一真源（single source of truth）
+- 为多个 AI 助手生成入口文件：
+  - Claude: `.claude/skills/<skill>/SKILL.md` + `resources/`
+  - Windsurf: `.windsurf/workflows/<skill>.md`
+  - Cursor: `.cursor/commands/<skill>.md`
+  - GitHub / VS Code Skills: `.github/skills/<skill>/SKILL.md` + resources
+- 校验生成的 `SKILL.md` 是否符合 Claude 严格的元数据规则
+- 打包 Claude `.skill`（zip 格式，符合正确的根目录结构）
+
+## 支持的 Skills
+
+| Skill 名称 | 描述 | 来源 |
+|-----------|------|------|
+| **skill-creator** | 对话式收集需求，生成可在多 AI Assistant 运行的技能包 | 内置 |
+| **review-gate** | 建立架构与工程化 PR Review 规范，提供可执行的 Review Checklist | 内置 |
+
+**触发示例**：
+- skill-creator: "我想做一个 skill"、"帮我生成 SKILL.md"、"把我的 prompt 工作流变成 skill"
+- review-gate: "我想建立 PR Review 架构规范检查点"、"帮我生成 PR Review Checklist 模板"、"软评审代码"
+
+## 快速开始
+
+### 典型使用场景
+
+**场景 1：在 neo-skill 仓库内开发/维护 skill**
+```bash
+# 从仓库根目录执行，初始化指定 AI 助手的技能文件
+omni-skill init --ai claude
+omni-skill init --ai windsurf
+omni-skill init --ai all  # 初始化所有支持的 AI 助手
+```
+
+**场景 2：在 neo-skill 仓库内更新并重新生成所有 IDE 入口文件**
+在 neo-skill 仓库根目录执行：
+
+```bash
+omni-skill update
+```
+
+行为说明：
+- 根据上次 init 时保存的 AI 目标，重新同步/生成所有入口文件
+
+**场景 3：在其他项目中使用 neo-skill 的 skill**
+将 neo-skill 仓库克隆到你的项目中（例如 `vendor/neo-skill/`），然后根据你使用的 IDE，复制对应的入口文件到项目根目录：
+- **Windsurf**：复制 `.windsurf/workflows/<skill>.md` 和 `.windsurf/workflows/data/`
+- **Cursor**：复制 `.cursor/commands/<skill>.md`
+- **Claude Desktop**：复制 `.claude/skills/<skill>/`
+- **GitHub / VS Code Skills**：复制 `.github/skills/<skill>/`
+
+### 推荐用法
+
+```bash
+# 初始化指定 AI 助手
+omni-skill init --ai claude
+omni-skill init --ai windsurf --ai cursor  # 可指定多个
+
+# 初始化所有支持的 AI 助手
+omni-skill init --ai all
+
+# 更新（基于上次 init 的配置）
+omni-skill update
+```
+
+### 关于 npm 安装后的 init 行为
+
+当你通过 `npm install -g neo-skill` 安装后：
+
+- **命令来源**：`omni-skill` 和 `skill-creator` 命令来自全局 npm 包（内部调用 Python）
+- **同步内容**：`omni-skill init` 会把包内的技能/资源内容同步到当前项目目录（覆盖式同步）：
+  - `skills/`
+  - `.shared/skill-creator/`
+  - 以及指定 AI 对应的目录（如 `.claude/skills/`、`.windsurf/workflows/` 等）
+
+**核心行为：**
+- 根据 `--ai` 参数生成对应 IDE 的入口文件
+- 不同 IDE 可以共存，切换 IDE 时无需重新生成
+- 生成的文件都是从 canonical `skills/<skill>/skillspec.json` 渲染而来
+
+**参数说明：**
+- `init`：初始化技能文件
+- `update`：基于上次 init 保存的配置重新同步
+- `--ai <target>`：指定目标 AI 助手（可重复使用）
+
+**支持的 AI 助手：**
+claude, cursor, windsurf, antigravity, copilot, kiro, codex, qoder, roocode, gemini, trae, opencode, continue, all
+
+
+## Canonical 与生成文件
+
+### Canonical（可编辑）
+- `skills/<skill>/skillspec.json`
+- `skills/<skill>/references/**`
+- `skills/<skill>/scripts/**`（可选）
+- `skills/<skill>/assets/**`（可选）
+
+### 生成文件（不要手动编辑）
+- `.windsurf/workflows/<skill>.md`
+- `.windsurf/workflows/data/<skill>/**`（从 `skills/<skill>/assets/windsurf-workflow-data` 同步）
+- `.claude/skills/<skill>/**`
+- `.cursor/commands/<skill>.md`
+- `.github/skills/<skill>/**`

package/bin/omni-skill.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+function main() {
+  const pkgRoot = path.resolve(__dirname, "..");
+  const pySrc = path.join(pkgRoot, "src");
+
+  const env = { ...process.env };
+  env.PYTHONPATH = env.PYTHONPATH ? `${pySrc}${path.delimiter}${env.PYTHONPATH}` : pySrc;
+
+  const baseArgs = ["-m", "omni_skill.cli", ...process.argv.slice(2)];
+
+  const candidates = [];
+  if (env.OMNI_SKILL_PYTHON) {
+    candidates.push({ cmd: env.OMNI_SKILL_PYTHON, extraArgs: [] });
+  }
+  if (process.platform === "win32") {
+    candidates.push({ cmd: "python", extraArgs: [] });
+    candidates.push({ cmd: "python3", extraArgs: [] });
+    candidates.push({ cmd: "py", extraArgs: ["-3"] });
+  } else {
+    candidates.push({ cmd: "python3", extraArgs: [] });
+    candidates.push({ cmd: "python", extraArgs: [] });
+  }
+
+  let lastError = null;
+  for (const c of candidates) {
+    const r = spawnSync(c.cmd, [...c.extraArgs, ...baseArgs], { stdio: "inherit", env });
+    if (r.error) {
+      lastError = r.error;
+      const msg = String(r.error.message || "").toLowerCase();
+      if (msg.includes("enoent")) {
+        continue;
+      }
+      console.error(r.error);
+      process.exit(1);
+    }
+    if (typeof r.status === "number" && r.status === 9009) {
+      continue;
+    }
+    process.exit(r.status == null ? 1 : r.status);
+  }
+
+  console.error(
+    "Python not found. Please install Python 3 and ensure 'python' works, or set OMNI_SKILL_PYTHON to your interpreter path.",
+  );
+  if (lastError) {
+    console.error(lastError);
+  }
+  process.exit(127);
+}
+
+main();