neo-skill 0.1.11

package/src/skill_creator/spec/model.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..util.fs import read_json
+
+
+def _as_list(x: Any) -> List[Any]:
+    if x is None:
+        return []
+    if isinstance(x, list):
+        return x
+    return [x]
+
+
+def _kebab_case_ok(name: str) -> bool:
+    return (
+        bool(name)
+        and all(c.islower() or c.isdigit() or c == "-" for c in name)
+        and "--" not in name
+        and not name.startswith("-")
+        and not name.endswith("-")
+    )
+
+
+@dataclass
+class WorkflowStep:
+    id: str
+    title: str
+    kind: str = "action"  # action|gate|branch
+    commands: List[str] = field(default_factory=list)
+    notes: str = ""
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "WorkflowStep":
+        return WorkflowStep(
+            id=str(d.get("id", "")).strip(),
+            title=str(d.get("title", "")).strip(),
+            kind=str(d.get("kind", "action")).strip(),
+            commands=[str(c) for c in _as_list(d.get("commands"))],
+            notes=str(d.get("notes", "")).strip(),
+        )
+
+
+@dataclass
+class SkillSpec:
+    version: int
+    name: str
+    description: str
+
+    
+    # Prompting
+    questions: List[str] = field(default_factory=list)  # must be <= 10
+    triggers: List[str] = field(default_factory=list)
+    freedom_level: str = "low"  # low|medium|high
+
+    # Workflow + assets
+    workflow_type: str = "sequential"  # sequential|conditional
+    steps: List[WorkflowStep] = field(default_factory=list)
+
+    references: List[str] = field(default_factory=list)
+    scripts: List[str] = field(default_factory=list)
+    assets: List[str] = field(default_factory=list)
+
+    @staticmethod
+    def from_path(path: Path) -> "SkillSpec":
+        data = read_json(path)
+        return SkillSpec.from_dict(data)
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "SkillSpec":
+        steps = [WorkflowStep.from_dict(x) for x in _as_list(d.get("workflow", {}).get("steps"))]
+        return SkillSpec(
+            version=int(d.get("version", 1)),
+            name=str(d.get("name", "")).strip(),
+            description=str(d.get("description", "")).strip(),
+            questions=[str(x) for x in _as_list(d.get("questions"))],
+            triggers=[str(x) for x in _as_list(d.get("triggers"))],
+            freedom_level=str(d.get("freedom_level", "low")).strip(),
+            workflow_type=str(d.get("workflow", {}).get("type", "sequential")).strip(),
+            steps=steps,
+            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"))],
+        )
+
+    def validate_basic(self) -> List[str]:
+        errors: List[str] = []
+        if self.version != 1:
+            errors.append(f"Unsupported spec version: {self.version}")
+        if not _kebab_case_ok(self.name):
+            errors.append("name must be kebab-case (lowercase letters, digits, hyphen)")
+        if not self.description:
+            errors.append("description is required")
+        if len(self.questions) > 10:
+            errors.append("questions must be <= 10")
+        if self.freedom_level not in {"low", "medium", "high"}:
+            errors.append("freedom_level must be one of: low, medium, high")
+        if self.workflow_type not in {"sequential", "conditional"}:
+            errors.append("workflow.type must be sequential or conditional")
+        if not self.steps:
+            errors.append("workflow.steps must not be empty")
+        # minimal step validation
+        for i, s in enumerate(self.steps):
+            if not s.id:
+                errors.append(f"workflow.steps[{i}].id is required")
+            if not s.title:
+                errors.append(f"workflow.steps[{i}].title is required")
+        return errors

package/src/skill_creator/spec/render.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from ..util.fs import ensure_dir, copytree, copyfile
+from .model import SkillSpec
+from ..targets.claude import render_claude_skill_md
+from ..targets.windsurf import render_windsurf_workflow_md
+from ..targets.cursor import render_cursor_command_md
+from ..targets.github_skills import render_github_skill_md
+
+# Primary target is Windsurf; others are backward compat
+PRIMARY_TARGET = "windsurf"
+BACKWARD_COMPAT_TARGETS = ["claude", "cursor", "github"]
+ALL_TARGETS = [PRIMARY_TARGET] + BACKWARD_COMPAT_TARGETS
+
+
+def generate_target(repo_root: Path, spec: SkillSpec, spec_dir: Path, target: str) -> Path:
+    """Generate output for a specific target. Returns output path."""
+    refs_dir = spec_dir / "references"
+    scripts_dir = spec_dir / "scripts"
+    assets_dir = spec_dir / "assets"
+    skill_readme = spec_dir / "readme.txt"
+
+    if target == "windsurf":
+        # PRIMARY: Windsurf workflow
+        out_path = repo_root / ".windsurf" / "workflows" / f"{spec.name}.md"
+        ensure_dir(out_path.parent)
+        out_path.write_text(render_windsurf_workflow_md(spec), encoding="utf-8")
+        
+        # Windsurf workflow data (optional)
+        windsurf_data_src = assets_dir / "windsurf-workflow-data"
+        if windsurf_data_src.exists():
+            windsurf_data_dst = repo_root / ".windsurf" / "workflows" / "data" / spec.name
+            copytree(windsurf_data_src, windsurf_data_dst)
+        return out_path
+
+    elif target == "claude":
+        # BACKWARD COMPAT: Claude SKILL.md
+        claude_dir = repo_root / ".claude" / "skills" / spec.name
+        ensure_dir(claude_dir)
+        out_path = claude_dir / "SKILL.md"
+        out_path.write_text(render_claude_skill_md(spec), encoding="utf-8")
+        if skill_readme.exists():
+            copyfile(skill_readme, claude_dir / "readme.txt")
+        claude_res = claude_dir / "resources"
+        copytree(refs_dir, claude_res / "references")
+        copytree(scripts_dir, claude_res / "scripts")
+        copytree(assets_dir, claude_res / "assets")
+        return out_path
+
+    elif target == "cursor":
+        # BACKWARD COMPAT: Cursor command
+        out_path = repo_root / ".cursor" / "commands" / f"{spec.name}.md"
+        ensure_dir(out_path.parent)
+        out_path.write_text(render_cursor_command_md(spec), encoding="utf-8")
+        return out_path
+
+    elif target == "github":
+        # BACKWARD COMPAT: GitHub Skills
+        gh_dir = repo_root / ".github" / "skills" / spec.name
+        ensure_dir(gh_dir)
+        out_path = gh_dir / "SKILL.md"
+        out_path.write_text(render_github_skill_md(spec), encoding="utf-8")
+        if skill_readme.exists():
+            copyfile(skill_readme, gh_dir / "readme.txt")
+        copytree(refs_dir, gh_dir / "references")
+        copytree(scripts_dir, gh_dir / "scripts")
+        copytree(assets_dir, gh_dir / "assets")
+        return out_path
+
+    else:
+        raise ValueError(f"Unknown target: {target}")
+
+
+def generate_windsurf(repo_root: Path, spec_path: Path) -> SkillSpec:
+    """Generate Windsurf output only (primary target)."""
+    spec = SkillSpec.from_path(spec_path)
+    spec_dir = spec_path.parent
+    generate_target(repo_root, spec, spec_dir, "windsurf")
+    return spec
+
+
+def generate_all(repo_root: Path, spec_path: Path, targets: Optional[List[str]] = None) -> SkillSpec:
+    """
+    Generate outputs for specified targets.
+    
+    Args:
+        repo_root: Repository root path
+        spec_path: Path to skillspec.json
+        targets: List of targets to generate. Default: all targets.
+    
+    Returns:
+        Loaded SkillSpec
+    """
+    repo_root = repo_root.resolve()
+    spec_path = spec_path.resolve()
+    spec = SkillSpec.from_path(spec_path)
+    spec_dir = spec_path.parent
+
+    if targets is None:
+        targets = ALL_TARGETS
+
+    for target in targets:
+        generate_target(repo_root, spec, spec_dir, target)
+
+    return spec

package/src/skill_creator/spec/validate.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from .model import SkillSpec
+
+
+def validate_spec(spec_path: Path) -> List[str]:
+    spec = SkillSpec.from_path(spec_path)
+    return spec.validate_basic()
+
+
+def assert_spec_valid(spec_path: Path) -> None:
+    errors = validate_spec(spec_path)
+    if errors:
+        joined = "\n- " + "\n- ".join(errors)
+        raise SystemExit(f"Spec validation failed:{joined}\n")

package/src/skill_creator/targets/claude.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from ..spec.model import SkillSpec
+from ..util.frontmatter import dump_frontmatter
+from .common import _render_steps, _render_resources, _render_footer
+
+
+def render_claude_skill_md(spec: SkillSpec) -> str:
+    # Strict metadata: only name + description.
+    fm = dump_frontmatter({"name": spec.name, "description": spec.description})
+
+    body = []
+    body.append("# " + spec.name)
+    body.append("")
+    body.append("## What this skill does")
+    body.append(spec.description)
+    body.append("")
+
+    if spec.triggers:
+        body.append("## When to use (examples of user requests)")
+        for t in spec.triggers:
+            body.append(f"- {t}")
+        body.append("")
+
+    body.append("## Degrees of freedom")
+    body.append(
+        f"This skill is designed for **{spec.freedom_level}** freedom (high=heuristic, low=deterministic scripts)."
+    )
+    body.append("")
+
+    if spec.questions:
+        body.append("## Requirement collection (at most 10 questions)")
+        body.append("Ask only what is missing. Never exceed 10 questions total.")
+        for i, q in enumerate(spec.questions, start=1):
+            body.append(f"{i}. {q}")
+        body.append("")
+
+    body.append("## Workflow")
+    body.append(f"*Mode:* `{spec.workflow_type}`")
+    body.append("")
+    body.append(_render_steps(spec.steps))
+    body.append("")
+
+    body.append(_render_resources(spec))
+    body.append("## Output contract")
+    body.append("When invoked, produce:")
+    body.append("A) A proposed directory tree")
+    body.append("B) SKILL.md / workflow entry file(s)")
+    body.append("C) Any scripts/references/assets")
+    body.append("D) A validation checklist with pass/fail")
+
+    body.append(_render_footer())
+    return fm + "\n".join(body)

package/src/skill_creator/targets/common.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List
+
+from ..spec.model import SkillSpec, WorkflowStep
+
+
+def _render_steps(steps: List[WorkflowStep]) -> str:
+    out = []
+    for i, s in enumerate(steps, start=1):
+        out.append(f"### Step {i} — {s.title}")
+        if s.kind:
+            out.append(f"*Type:* `{s.kind}`")
+        if s.notes:
+            out.append(s.notes)
+        if s.commands:
+            out.append("\n```bash")
+            out.extend(s.commands)
+            out.append("```\n")
+    return "\n".join(out)
+
+
+def _render_resources(spec: SkillSpec) -> str:
+    lines = []
+    if spec.references:
+        lines.append("## References (loaded on-demand)")
+        for p in spec.references:
+            lines.append(f"- `{p}`")
+        lines.append("")
+    if spec.scripts:
+        lines.append("## Scripts (deterministic tools)")
+        for p in spec.scripts:
+            lines.append(f"- `{p}`")
+        lines.append("")
+    if spec.assets:
+        lines.append("## Assets")
+        for p in spec.assets:
+            lines.append(f"- `{p}`")
+        lines.append("")
+    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

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from ..spec.model import SkillSpec
+
+
+def render_cursor_command_md(spec: SkillSpec) -> str:
+    # Cursor's command palette prompts are typically Markdown instructions.
+    lines = [f"# {spec.name}", "", spec.description, ""]
+    if spec.triggers:
+        lines.append("## When to use")
+        lines.extend([f"- {t}" for t in spec.triggers])
+        lines.append("")
+    lines.append("## Command")
+    lines.append("Run these deterministic steps in the repository:")
+    lines.append("```bash")
+    if spec.name == "skill-creator":
+        lines.append("python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json")
+        lines.append("python3 .shared/skill-creator/scripts/validate.py skills/<skill>/skillspec.json")
+        lines.append("python3 .shared/skill-creator/scripts/package.py --target claude --skill <skill>")
+    else:
+        lines.append("omni-skill init --cursor")
+        lines.append("omni-skill do --agent")
+    lines.append("```")
+    lines.append("")
+    lines.append("## Workflow")
+    lines.append(f"Mode: `{spec.workflow_type}`")
+    lines.append("")
+    for i, step in enumerate(spec.steps, start=1):
+        lines.append(f"### {i}. {step.title}")
+        if step.commands:
+            lines.append("```bash")
+            lines.extend(step.commands)
+            lines.append("```")
+    return "\n".join(lines)

package/src/skill_creator/targets/github_skills.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from ..spec.model import SkillSpec
+from ..util.frontmatter import dump_frontmatter
+from .common import _render_steps, _render_resources, _render_footer
+
+
+def render_github_skill_md(spec: SkillSpec) -> str:
+    # GitHub/Agent Skills can support additional metadata; keep it conservative.
+    fm = dump_frontmatter(
+        {
+            "name": spec.name,
+            "description": spec.description,
+            "compatibility": "Multi-assistant (Claude/Windsurf/Cursor/GitHub Skills)",
+            "metadata": "Generated from canonical skillspec.json",
+        }
+    )
+
+    body = []
+    body.append("# " + spec.name)
+    body.append("")
+    body.append("## Overview")
+    body.append(spec.description)
+    body.append("")
+    if spec.triggers:
+        body.append("## Triggers")
+        for t in spec.triggers:
+            body.append(f"- {t}")
+        body.append("")
+    body.append("## Workflow")
+    body.append(f"*Mode:* `{spec.workflow_type}`")
+    body.append("")
+    body.append(_render_steps(spec.steps))
+    body.append("")
+    body.append(_render_resources(spec))
+    body.append("## Output contract")
+    body.append("- Deterministic artifacts (files, zips, reports) whenever possible")
+    body.append("- Machine-readable output available when scripts support `--json`")
+    body.append(_render_footer())
+    return fm + "\n".join(body)

package/src/skill_creator/targets/windsurf.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from ..spec.model import SkillSpec
+
+
+def render_windsurf_workflow_md(spec: SkillSpec) -> str:
+    """
+    Render Windsurf workflow markdown (PRIMARY target).
+    
+    Follows ui-ux-pro-max patterns:
+    - Clear workflow steps with numbered sections
+    - Gate steps marked with 🚦
+    - References expanded to full paths
+    - Deterministic tools section for scripts
+    """
+    # YAML frontmatter
+    lines = [
+        "---",
+        f"description: {spec.description}",
+        "auto_execution_mode: 3",
+        "---",
+        "",
+        f"# {spec.name}",
+        "",
+        spec.description,
+        "",
+    ]
+
+    # Prerequisites (if scripts exist)
+    if spec.scripts:
+        lines.extend([
+            "## Prerequisites",
+            "",
+            "```bash",
+            "python3 --version || python --version",
+            "```",
+            "",
+        ])
+
+    # Triggers
+    if spec.triggers:
+        lines.append("## Triggers")
+        lines.append("")
+        for t in spec.triggers:
+            lines.append(f"- {t}")
+        lines.append("")
+
+    # How to Use (for skill-creator specifically)
+    is_skill_creator = spec.name == "skill-creator"
+    if is_skill_creator:
+        lines.extend([
+            "## How to Use This Workflow",
+            "",
+            "When user requests skill creation (create, build, generate, update), follow this workflow:",
+            "",
+        ])
+
+    # Workflow
+    lines.append("## Workflow")
+    lines.append("")
+    lines.append(f"Mode: `{spec.workflow_type}`")
+    lines.append("")
+    
+    for i, step in enumerate(spec.steps, start=1):
+        kind_badge = " 🚦 GATE" if step.kind == "gate" else ""
+        lines.append(f"### Step {i}: {step.title}{kind_badge}")
+        lines.append("")
+        
+        if step.notes:
+            notes = step.notes
+            # Expand references paths
+            notes = notes.replace("`references/", f"`skills/{spec.name}/references/")
+            lines.append(notes)
+            lines.append("")
+        
+        if step.commands:
+            lines.append("```bash")
+            for cmd in step.commands:
+                lines.append(cmd)
+            lines.append("```")
+            lines.append("")
+
+    # References section
+    if spec.references:
+        lines.append("## References")
+        lines.append("")
+        for ref in spec.references:
+            ref_path = f"skills/{spec.name}/{ref}"
+            lines.append(f"- `{ref_path}`")
+        lines.append("")
+
+    # Deterministic tools (for skill-creator)
+    if is_skill_creator:
+        lines.extend([
+            "## Search & Generate Tools",
+            "",
+            "```bash",
+            "# Search skill patterns and get recommendations",
+            'python3 .shared/skill-creator/scripts/search.py "<keywords>" --skill-system -p "<name>"',
+            "",
+            "# Generate Windsurf workflow (primary target)",
+            "python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json",
+            "",
+            "# Generate all targets (backward compat)",
+            "python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json --all",
+            "",
+            "# Validate spec and outputs",
+            "python3 .shared/skill-creator/scripts/validate.py skills/<skill>/skillspec.json",
+            "",
+            "# Package Claude .skill",
+            "python3 .shared/skill-creator/scripts/package.py --target claude --skill <skill>",
+            "```",
+            "",
+        ])
+
+    # Footer
+    lines.extend([
+        "---",
+        "",
+        f"*Generated by skill-creator. Source: `skills/{spec.name}/skillspec.json`*",
+    ])
+
+    return "\n".join(lines)

package/src/skill_creator/util/frontmatter.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Dict, Any
+
+
+def dump_frontmatter(fields: Dict[str, Any]) -> str:
+    """Dump a minimal YAML frontmatter block.
+
+    Notes:
+    - We intentionally keep this implementation small and dependency-free.
+    - Values are rendered as single-line scalars (quoted when needed).
+    """
+    lines = ["---"]
+    for k, v in fields.items():
+        if v is None:
+            continue
+        s = str(v)
+        # Quote if it contains colon, newline, or leading/trailing whitespace
+        if any(ch in s for ch in [":", "\n"]) or s != s.strip():
+            s = s.replace("\\", "\\\\").replace('"', '\\"')
+            s = f'"{s}"'
+        lines.append(f"{k}: {s}")
+    lines.append("---")
+    return "\n".join(lines) + "\n"

package/src/skill_creator/util/fs.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict
+
+
+def ensure_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, obj: Any) -> None:
+    ensure_dir(path.parent)
+    path.write_text(json.dumps(obj, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def copytree(src: Path, dst: Path, *, overwrite: bool = True) -> None:
+    if not src.exists():
+        return
+    if dst.exists() and overwrite:
+        shutil.rmtree(dst)
+    shutil.copytree(src, dst)
+
+
+def copyfile(src: Path, dst: Path) -> None:
+    ensure_dir(dst.parent)
+    shutil.copy2(src, dst)