neo-skill 0.1.11

package/.shared/skill-creator/data/domains.json

@@ -0,0 +1,56 @@
+{
+  "domains": {
+    "workflow": {
+      "description": "Workflow patterns: sequential, conditional, parallel, gate-based",
+      "keywords": ["sequential", "conditional", "parallel", "gate", "branch", "loop", "retry"],
+      "data_file": "workflow-patterns.csv"
+    },
+    "output": {
+      "description": "Output patterns: template, examples, structured, report",
+      "keywords": ["template", "example", "structured", "report", "code", "patch", "checklist"],
+      "data_file": "output-patterns.csv"
+    },
+    "validation": {
+      "description": "Validation rules: spec, frontmatter, structure, naming",
+      "keywords": ["validate", "check", "gate", "lint", "schema", "strict", "frontmatter"],
+      "data_file": "validation-rules.csv"
+    },
+    "resource": {
+      "description": "Resource organization: references, scripts, assets",
+      "keywords": ["reference", "script", "asset", "data", "template", "shared", "progressive"],
+      "data_file": "resource-patterns.csv"
+    },
+    "trigger": {
+      "description": "Trigger patterns: action verbs, context keywords, intent signals",
+      "keywords": ["create", "build", "fix", "review", "generate", "update", "help"],
+      "data_file": "trigger-patterns.csv"
+    }
+  },
+  "stacks": {
+    "windsurf": {
+      "description": "Windsurf workflow format (PRIMARY)",
+      "format": "yaml-frontmatter + markdown",
+      "output_path": ".windsurf/workflows/{name}.md",
+      "priority": 1
+    },
+    "claude": {
+      "description": "Claude SKILL.md format (backward compat)",
+      "format": "strict yaml-frontmatter (name+description only)",
+      "output_path": ".claude/skills/{name}/SKILL.md",
+      "priority": 2
+    },
+    "cursor": {
+      "description": "Cursor command format (backward compat)",
+      "format": "markdown with bash blocks",
+      "output_path": ".cursor/commands/{name}.md",
+      "priority": 3
+    },
+    "github": {
+      "description": "GitHub Skills format (backward compat)",
+      "format": "extended yaml-frontmatter",
+      "output_path": ".github/skills/{name}/SKILL.md",
+      "priority": 4
+    }
+  },
+  "reasoning_file": "skill-reasoning.csv"
+}

package/.shared/skill-creator/data/output-patterns.csv

@@ -0,0 +1,8 @@
+id,name,description,when_to_use,template_type,example
+template,"Template Pattern","Structured output with placeholders","Reports, documents, code generation","strict or flexible","# [Title]\n## Summary\n[content]"
+examples,"Examples Pattern","Input/output pairs for style learning","Style-sensitive output, commit messages","input_output_pairs","Input: X -> Output: Y"
+structured,"Structured Data","JSON/YAML/CSV machine-readable output","API responses, data exports, configs","schema_based","{ key: value }"
+checklist,"Checklist Pattern","Actionable items with status","Reviews, audits, validation","checkbox_list","- [ ] Item 1\n- [ ] Item 2"
+code,"Code Generation","Source code with imports and tests","Implementation tasks","language_specific","```python\ndef func():\n    pass\n```"
+patch,"Patch/Diff Pattern","Changes to existing code","Bug fixes, refactoring","unified_diff","+added\n-removed"
+tree,"Directory Tree","File/folder structure","Project scaffolding, organization","ascii_tree","src/\n  index.ts\n  utils/"

package/.shared/skill-creator/data/resource-patterns.csv

@@ -0,0 +1,8 @@
+id,name,location,content_type,when_to_use,size_limit
+reference,"Reference Documents","references/","markdown rules, specs, templates","Static knowledge, rules, guidelines that AI reads","<5KB per file"
+script,"Deterministic Scripts","scripts/","python, bash, node scripts","Reproducible operations, validation, packaging","<500 lines"
+asset,"Structured Data","assets/","csv, json, yaml data files","Searchable data, templates, configs","<100KB"
+shared,"Shared Resources",".shared/{skill}/","cross-skill data and scripts","Reusable across multiple skills","per-file limits apply"
+index,"Index Notes","workflow.steps[].notes","short pointers to resources","Keep steps lightweight, point to details","<200 chars"
+master,"Master Config","skillspec.json","single source of truth","All skill metadata and workflow definition","<10KB"
+override,"Page/Step Override","{context}.md","context-specific deviations","When specific context needs different rules","<2KB"

package/.shared/skill-creator/data/skill-reasoning.csv

@@ -0,0 +1,11 @@
+condition,recommendation,priority,rationale
+"deterministic_output",use_scripts,high,"When output must be reproducible, use scripts/ instead of heuristics"
+"large_context",progressive_disclosure,high,"When context >2000 tokens, split into references/ and use index-style notes"
+"reusable_rules",shared_data,medium,"When rules apply to multiple skills, move to .shared/"
+"multi_step_workflow",sequential_with_gates,high,"For complex workflows, add gate steps for validation between phases"
+"user_input_required",collect_step_first,high,"When user input is needed, always start with a collect requirements step"
+"code_output",template_pattern,medium,"When generating code, provide templates in references/ for consistency"
+"review_task",checklist_output,high,"For review/audit tasks, output structured checklists"
+"api_integration",scripts_with_validation,high,"For API calls, use scripts/ with built-in validation"
+"error_prone_step",add_gate,high,"For steps that commonly fail, add a gate with clear error messages"
+"shared_across_skills",move_to_shared,medium,"Data/scripts used by multiple skills should live in .shared/"

package/.shared/skill-creator/data/trigger-patterns.csv

@@ -0,0 +1,8 @@
+id,verb,context_keywords,intent,example_triggers
+create,"create, build, make, generate, scaffold","new, skill, workflow, project","Create new artifact from scratch","创建一个skill, build a new workflow, make a skill for X"
+update,"update, modify, edit, change, refactor","existing, current, improve, add to","Modify existing artifact","更新已有skill, add steps to workflow, refactor the skill"
+review,"review, check, audit, validate, verify","quality, compliance, standards","Inspect for quality/compliance","审查这个skill, validate the spec, check for issues"
+fix,"fix, repair, debug, resolve, patch","bug, issue, error, broken","Resolve a problem","修复这个问题, fix the validation error, resolve the conflict"
+explain,"explain, describe, document, clarify","how, why, what, understand","Provide understanding","解释这个workflow, how does this work, document the process"
+convert,"convert, transform, migrate, port","from, to, into, format","Change format/structure","把prompt转成skill, convert to Claude format, migrate to Windsurf"
+package,"package, bundle, zip, export, distribute","deploy, share, publish","Prepare for distribution","打包成.skill, export for Claude, prepare for distribution"

package/.shared/skill-creator/data/validation-rules.csv

@@ -0,0 +1,11 @@
+id,rule,target,severity,message,fix_hint
+name_kebab,"name must be kebab-case","skillspec.name",error,"Name '{value}' is not kebab-case","Use lowercase letters, digits, and hyphens only"
+description_required,"description is required","skillspec.description",error,"Description is empty","Add a one-sentence description of when to use this skill"
+questions_max_10,"questions must be <= 10","skillspec.questions",error,"Too many questions ({count})","Consolidate or prioritize to 10 or fewer"
+triggers_min_3,"at least 3 triggers recommended","skillspec.triggers",warning,"Only {count} triggers defined","Add more example phrases users might say"
+steps_not_empty,"workflow must have steps","skillspec.workflow.steps",error,"No workflow steps defined","Add at least one step to the workflow"
+step_id_required,"each step needs an id","workflow.steps[].id",error,"Step {index} missing id","Add a unique kebab-case id"
+step_title_required,"each step needs a title","workflow.steps[].title",error,"Step {index} missing title","Add a descriptive title"
+claude_frontmatter_strict,"Claude frontmatter only name+description","claude/SKILL.md",error,"Extra frontmatter keys: {keys}","Remove all keys except name and description"
+no_banned_files,"no README/CHANGELOG in skill bundle","skill bundle",error,"Banned file found: {file}","Remove or move to project root"
+notes_max_length,"step notes should be concise","workflow.steps[].notes",warning,"Notes too long ({chars} chars)","Move details to references/ and use index-style notes"

package/.shared/skill-creator/data/workflow-patterns.csv

@@ -0,0 +1,6 @@
+id,name,description,when_to_use,structure,example_steps
+sequential,"Sequential Workflow","Steps execute in order, each depends on previous","Simple linear tasks, clear dependencies","step1 -> step2 -> step3","collect -> plan -> generate -> validate -> package"
+conditional,"Conditional Workflow","Branches based on input or intermediate results","Tasks with multiple paths, feature flags","if condition: path_a else: path_b","analyze -> (new_skill: create, existing: update) -> validate"
+gated,"Gated Workflow","Checkpoints that must pass before proceeding","Quality-critical tasks, multi-phase projects","step -> gate -> step -> gate","generate -> lint_gate -> test_gate -> deploy"
+parallel,"Parallel Workflow","Independent steps that can run concurrently","Performance-critical, independent subtasks","[step_a, step_b, step_c] -> merge","[search_style, search_color, search_font] -> synthesize"
+iterative,"Iterative Workflow","Repeat steps until condition met","Refinement tasks, user feedback loops","while !done: step -> check","draft -> review -> (approved: done, rejected: revise)"

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

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""
+Skill Generator - Generate multi-assistant outputs from skillspec.json
+
+Primary target: Windsurf (with backward compatibility for Claude/Cursor/GitHub)
+
+Usage:
+    python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json
+    python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json --target windsurf
+    python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json --all
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+SCRIPT_DIR = Path(__file__).parent
+REPO_ROOT = SCRIPT_DIR.parent.parent.parent  # .shared/skill-creator/scripts -> repo root
+
+
+def load_spec(spec_path: Path) -> Dict[str, Any]:
+    return json.loads(spec_path.read_text(encoding="utf-8"))
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def copytree_safe(src: Path, dst: Path) -> None:
+    """Copy directory tree, skipping if source doesn't exist."""
+    if not src.exists():
+        return
+    if dst.exists():
+        shutil.rmtree(dst)
+    shutil.copytree(src, dst)
+
+
+def render_windsurf(spec: Dict[str, Any], spec_dir: Path) -> str:
+    """Render Windsurf workflow markdown (PRIMARY target)."""
+    name = spec["name"]
+    desc = spec.get("description", "")
+    
+    lines = [
+        "---",
+        f"description: {desc}",
+        "auto_execution_mode: 3",
+        "---",
+        "",
+        f"# {name}",
+        "",
+        f"{desc}",
+        "",
+    ]
+    
+    # Triggers
+    triggers = spec.get("triggers", [])
+    if triggers:
+        lines.append("## Triggers")
+        lines.append("")
+        for t in triggers:
+            lines.append(f"- {t}")
+        lines.append("")
+    
+    # Prerequisites (check for scripts)
+    scripts = spec.get("scripts", [])
+    if scripts:
+        lines.append("## Prerequisites")
+        lines.append("")
+        lines.append("```bash")
+        lines.append("python3 --version || python --version")
+        lines.append("```")
+        lines.append("")
+    
+    # Workflow
+    lines.append("## Workflow")
+    lines.append("")
+    workflow = spec.get("workflow", {})
+    workflow_type = workflow.get("type", "sequential")
+    lines.append(f"Mode: `{workflow_type}`")
+    lines.append("")
+    
+    steps = workflow.get("steps", [])
+    for i, step in enumerate(steps, 1):
+        title = step.get("title", f"Step {i}")
+        kind = step.get("kind", "action")
+        kind_badge = "🚦 GATE" if kind == "gate" else ""
+        
+        lines.append(f"### Step {i}: {title} {kind_badge}")
+        lines.append("")
+        
+        notes = step.get("notes", "")
+        if notes:
+            # Expand references paths
+            notes = notes.replace("`references/", f"`skills/{name}/references/")
+            lines.append(notes)
+            lines.append("")
+        
+        commands = step.get("commands", [])
+        if commands:
+            lines.append("```bash")
+            for cmd in commands:
+                lines.append(cmd)
+            lines.append("```")
+            lines.append("")
+    
+    # Resources
+    refs = spec.get("references", [])
+    if refs:
+        lines.append("## References")
+        lines.append("")
+        for ref in refs:
+            ref_path = f"skills/{name}/{ref}"
+            lines.append(f"- `{ref_path}`")
+        lines.append("")
+    
+    # Footer
+    lines.append("---")
+    lines.append("")
+    lines.append("*Generated by skill-creator. Source: `skills/{}/skillspec.json`*".format(name))
+    
+    return "\n".join(lines)
+
+
+def render_claude(spec: Dict[str, Any], spec_dir: Path) -> str:
+    """Render Claude SKILL.md (backward compat, strict frontmatter)."""
+    name = spec["name"]
+    desc = spec.get("description", "")
+    
+    lines = [
+        "---",
+        f"name: {name}",
+        f"description: {desc}",
+        "---",
+        "",
+        f"# {name}",
+        "",
+        "## What this skill does",
+        "",
+        desc,
+        "",
+    ]
+    
+    triggers = spec.get("triggers", [])
+    if triggers:
+        lines.append("## When to use")
+        lines.append("")
+        for t in triggers:
+            lines.append(f"- {t}")
+        lines.append("")
+    
+    questions = spec.get("questions", [])
+    if questions:
+        lines.append("## Requirement collection (at most 10 questions)")
+        lines.append("")
+        for i, q in enumerate(questions, 1):
+            lines.append(f"{i}. {q}")
+        lines.append("")
+    
+    lines.append("## Workflow")
+    lines.append("")
+    workflow = spec.get("workflow", {})
+    for i, step in enumerate(workflow.get("steps", []), 1):
+        title = step.get("title", f"Step {i}")
+        kind = step.get("kind", "action")
+        lines.append(f"### {i}. {title}" + (" (GATE)" if kind == "gate" else ""))
+        notes = step.get("notes", "")
+        if notes:
+            lines.append(notes)
+        commands = step.get("commands", [])
+        if commands:
+            lines.append("```bash")
+            lines.extend(commands)
+            lines.append("```")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def render_cursor(spec: Dict[str, Any], spec_dir: Path) -> str:
+    """Render Cursor command markdown (backward compat)."""
+    name = spec["name"]
+    desc = spec.get("description", "")
+    
+    lines = [f"# {name}", "", desc, ""]
+    
+    triggers = spec.get("triggers", [])
+    if triggers:
+        lines.append("## When to use")
+        for t in triggers:
+            lines.append(f"- {t}")
+        lines.append("")
+    
+    lines.append("## Steps")
+    lines.append("")
+    workflow = spec.get("workflow", {})
+    for i, step in enumerate(workflow.get("steps", []), 1):
+        lines.append(f"{i}. {step.get('title', 'Step')}")
+    
+    return "\n".join(lines)
+
+
+def render_github(spec: Dict[str, Any], spec_dir: Path) -> str:
+    """Render GitHub Skills SKILL.md (backward compat)."""
+    name = spec["name"]
+    desc = spec.get("description", "")
+    
+    lines = [
+        "---",
+        f"name: {name}",
+        f"description: {desc}",
+        "compatibility: Multi-assistant (Claude/Windsurf/Cursor/GitHub)",
+        "---",
+        "",
+        f"# {name}",
+        "",
+        desc,
+        "",
+    ]
+    
+    workflow = spec.get("workflow", {})
+    lines.append("## Workflow")
+    lines.append("")
+    for i, step in enumerate(workflow.get("steps", []), 1):
+        lines.append(f"### {i}. {step.get('title', 'Step')}")
+        if step.get("notes"):
+            lines.append(step["notes"])
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def generate_target(spec: Dict[str, Any], spec_dir: Path, target: str, repo_root: Path) -> Path:
+    """Generate output for a specific target."""
+    name = spec["name"]
+    
+    if target == "windsurf":
+        content = render_windsurf(spec, spec_dir)
+        out_path = repo_root / ".windsurf" / "workflows" / f"{name}.md"
+    elif target == "claude":
+        content = render_claude(spec, spec_dir)
+        out_path = repo_root / ".claude" / "skills" / name / "SKILL.md"
+    elif target == "cursor":
+        content = render_cursor(spec, spec_dir)
+        out_path = repo_root / ".cursor" / "commands" / f"{name}.md"
+    elif target == "github":
+        content = render_github(spec, spec_dir)
+        out_path = repo_root / ".github" / "skills" / name / "SKILL.md"
+    else:
+        raise ValueError(f"Unknown target: {target}")
+    
+    ensure_dir(out_path.parent)
+    out_path.write_text(content, encoding="utf-8")
+    
+    # Copy resources for Claude and GitHub (they need local copies)
+    if target in ("claude", "github"):
+        res_dst = out_path.parent / "resources"
+        copytree_safe(spec_dir / "references", res_dst / "references")
+        copytree_safe(spec_dir / "scripts", res_dst / "scripts")
+        copytree_safe(spec_dir / "assets", res_dst / "assets")
+    
+    return out_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate multi-assistant outputs from skillspec.json")
+    parser.add_argument("spec", help="Path to skillspec.json")
+    parser.add_argument("--target", "-t", choices=["windsurf", "claude", "cursor", "github"],
+                        help="Generate for specific target (default: windsurf)")
+    parser.add_argument("--all", "-a", action="store_true", help="Generate for all targets")
+    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"Spec not found: {spec_path}", file=sys.stderr)
+        sys.exit(1)
+    
+    spec = load_spec(spec_path)
+    spec_dir = spec_path.parent
+    
+    if args.all:
+        targets = ["windsurf", "claude", "cursor", "github"]
+    else:
+        targets = [args.target or "windsurf"]
+    
+    for target in targets:
+        out_path = generate_target(spec, spec_dir, target, repo_root)
+        print(f"Generated: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Package skills for distribution
+
+Usage:
+    python3 .shared/skill-creator/scripts/package.py --target claude --skill <skill>
+    python3 .shared/skill-creator/scripts/package.py --target repo
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent
+REPO_ROOT = SCRIPT_DIR.parent.parent.parent
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def package_claude_skill(skill_name: str, repo_root: Path, out_dir: Path) -> Path:
+    """
+    Package a Claude skill as .skill zip file.
+    
+    Claude .skill format:
+    - Zip root must be the skill folder
+    - Must contain SKILL.md with strict frontmatter
+    - Resources in resources/ subfolder
+    """
+    skill_dir = repo_root / ".claude" / "skills" / skill_name
+    
+    if not skill_dir.exists():
+        print(f"ERROR: Claude skill not found: {skill_dir}", file=sys.stderr)
+        print("Run generate.py first to create Claude output", file=sys.stderr)
+        sys.exit(1)
+    
+    # Validate before packaging
+    validate_script = SCRIPT_DIR / "validate.py"
+    spec_path = repo_root / "skills" / skill_name / "skillspec.json"
+    
+    if validate_script.exists() and spec_path.exists():
+        result = subprocess.run(
+            [sys.executable, str(validate_script), str(spec_path)],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            print("Validation failed:", file=sys.stderr)
+            print(result.stdout, file=sys.stderr)
+            print(result.stderr, file=sys.stderr)
+            sys.exit(1)
+    
+    ensure_dir(out_dir)
+    out_path = out_dir / f"{skill_name}.skill"
+    
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for path in skill_dir.rglob("*"):
+            if path.is_file():
+                arcname = path.relative_to(skill_dir.parent)
+                zf.write(path, arcname)
+    
+    return out_path
+
+
+def package_repo_zip(repo_root: Path, out_dir: Path) -> Path:
+    """Package entire repo as zip for easy sharing."""
+    ensure_dir(out_dir)
+    out_path = out_dir / f"{repo_root.name}.zip"
+    
+    # Use git archive if available
+    try:
+        result = subprocess.run(
+            ["git", "archive", "--format=zip", "--output", str(out_path), "HEAD"],
+            cwd=repo_root,
+            capture_output=True
+        )
+        if result.returncode == 0:
+            return out_path
+    except FileNotFoundError:
+        pass
+    
+    # Fallback: manual zip (respecting gitignore patterns)
+    gitignore = repo_root / ".gitignore"
+    ignore_patterns = set()
+    if gitignore.exists():
+        for line in gitignore.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                ignore_patterns.add(line.strip("/"))
+    
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for path in repo_root.rglob("*"):
+            if path.is_file():
+                rel = path.relative_to(repo_root)
+                
+                # Skip common ignored patterns
+                skip = False
+                for part in rel.parts:
+                    if part in ignore_patterns or part.startswith("."):
+                        skip = True
+                        break
+                
+                if not skip:
+                    zf.write(path, rel)
+    
+    return out_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Package skills for distribution")
+    parser.add_argument("--target", "-t", choices=["claude", "repo"], required=True,
+                        help="Package target")
+    parser.add_argument("--skill", "-s", help="Skill name (required for --target claude)")
+    parser.add_argument("--repo-root", "-r", default=str(REPO_ROOT), help="Repository root")
+    parser.add_argument("--out-dir", "-o", help="Output directory (default: dist/)")
+    
+    args = parser.parse_args()
+    
+    repo_root = Path(args.repo_root).resolve()
+    out_dir = Path(args.out_dir) if args.out_dir else repo_root / "dist"
+    
+    if args.target == "claude":
+        if not args.skill:
+            print("ERROR: --skill required for --target claude", file=sys.stderr)
+            sys.exit(1)
+        out_path = package_claude_skill(args.skill, repo_root, out_dir)
+    else:
+        out_path = package_repo_zip(repo_root, out_dir)
+    
+    print(f"Packaged: {out_path}")
+
+
+if __name__ == "__main__":
+    main()