neo-skill 0.1.11

package/src/omni_skill/cli.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+from pathlib import Path
+from typing import Dict, List, Set
+
+from skill_creator.cli import cmd_generate
+
+STATE_FILE = ".neo-skill.json"
+
+SUPPORTED_AIS = [
+    "claude", "cursor", "windsurf", "antigravity", "copilot",
+    "kiro", "codex", "qoder", "roocode", "gemini", "trae", "opencode", "continue",
+]
+
+AI_COPY_RULES: Dict[str, Dict] = {
+    "claude": {
+        "sync_pairs": [(".claude/skills", ".claude/skills")],
+        "base_dirs": [".claude"],
+    },
+    "windsurf": {
+        "sync_pairs": [(".windsurf/workflows", ".windsurf/workflows")],
+        "base_dirs": [".windsurf"],
+    },
+    "cursor": {
+        "sync_pairs": [(".cursor/commands", ".cursor/commands")],
+        "base_dirs": [".cursor"],
+    },
+    "copilot": {
+        "sync_pairs": [(".github/skills", ".github/skills")],
+        "base_dirs": [".github"],
+    },
+    "antigravity": {
+        "sync_pairs": [(".agent", ".agent"), (".shared", ".shared")],
+        "base_dirs": [".agent", ".shared"],
+    },
+    "kiro": {
+        "sync_pairs": [(".kiro", ".kiro")],
+        "base_dirs": [".kiro"],
+    },
+    "codex": {
+        "sync_pairs": [(".codex", ".codex")],
+        "base_dirs": [".codex"],
+    },
+    "qoder": {
+        "sync_pairs": [(".qoder", ".qoder")],
+        "base_dirs": [".qoder"],
+    },
+    "roocode": {
+        "sync_pairs": [(".roocode", ".roocode")],
+        "base_dirs": [".roocode"],
+    },
+    "gemini": {
+        "sync_pairs": [(".gemini", ".gemini")],
+        "base_dirs": [".gemini"],
+    },
+    "trae": {
+        "sync_pairs": [(".trae", ".trae")],
+        "base_dirs": [".trae"],
+    },
+    "opencode": {
+        "sync_pairs": [(".opencode", ".opencode")],
+        "base_dirs": [".opencode"],
+    },
+    "continue": {
+        "sync_pairs": [(".continue", ".continue")],
+        "base_dirs": [".continue"],
+    },
+}
+
+
+def _get_pkg_root() -> Path:
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def _get_pkg_version() -> str:
+    pkg_json = _get_pkg_root() / "package.json"
+    if pkg_json.exists():
+        try:
+            data = json.loads(pkg_json.read_text(encoding="utf-8"))
+            return str(data.get("version", "unknown")).strip() or "unknown"
+        except Exception:
+            pass
+    return "unknown"
+
+
+def _write_init_state(cwd: Path, selected_ais: List[str]) -> None:
+    state_path = cwd / STATE_FILE
+    payload = {"ais": selected_ais}
+    state_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _read_init_state(cwd: Path) -> Dict:
+    state_path = cwd / STATE_FILE
+    if not state_path.exists():
+        return {"ok": False, "error": f"Missing {STATE_FILE}. Please run: omni-skill init --ai <target>"}
+    try:
+        data = json.loads(state_path.read_text(encoding="utf-8"))
+        ais = [a.strip().lower() for a in data.get("ais", []) if a]
+        resolved = _resolve_selected_ais(ais)
+        if not resolved["ok"]:
+            return resolved
+        if not resolved["selected"]:
+            return {"ok": False, "error": f"Invalid {STATE_FILE}: ais is empty. Please re-run init."}
+        return {"ok": True, "selected": resolved["selected"]}
+    except Exception:
+        return {"ok": False, "error": f"Invalid {STATE_FILE}. Please delete it and re-run init."}
+
+
+def _resolve_selected_ais(ai_values: List[str]) -> Dict:
+    supported: Set[str] = set(SUPPORTED_AIS + ["all"])
+    if not ai_values:
+        return {"ok": True, "selected": []}
+    for v in ai_values:
+        if v not in supported:
+            return {"ok": False, "error": f"Unknown --ai value: {v}"}
+    if "all" in ai_values:
+        return {"ok": True, "selected": list(SUPPORTED_AIS)}
+    return {"ok": True, "selected": list(set(ai_values))}
+
+
+def _sync_dir_replace(src: Path, dest: Path) -> None:
+    if not src.exists():
+        return
+    dest.mkdir(parents=True, exist_ok=True)
+    for entry in src.iterdir():
+        dest_path = dest / entry.name
+        if dest_path.exists():
+            if dest_path.is_dir():
+                shutil.rmtree(dest_path)
+            else:
+                dest_path.unlink()
+        if entry.is_dir():
+            shutil.copytree(entry, dest_path)
+        else:
+            shutil.copy2(entry, dest_path)
+
+
+def _build_sync_pairs(effective_ais: List[str]) -> List[tuple]:
+    pairs = [
+        ("skills", "skills"),
+        (".shared/skill-creator", ".shared/skill-creator"),
+    ]
+    for ai in effective_ais:
+        rules = AI_COPY_RULES.get(ai)
+        if rules:
+            pairs.extend(rules["sync_pairs"])
+    return pairs
+
+
+def _perform_sync(pkg_root: Path, cwd: Path, sync_pairs: List[tuple]) -> None:
+    for src_rel, dest_rel in sync_pairs:
+        src = pkg_root / src_rel
+        dest = cwd / dest_rel
+        if src.resolve() == dest.resolve():
+            print(f"  Skipping {dest_rel} (source equals destination)")
+            continue
+        if not src.exists():
+            print(f"  Skipping {dest_rel} (not found in package)")
+            continue
+        print(f"  Syncing {dest_rel} (replace items)")
+        _sync_dir_replace(src, dest)
+
+
+def _write_version_files(cwd: Path, effective_ais: List[str], version: str) -> None:
+    for ai in effective_ais:
+        rules = AI_COPY_RULES.get(ai)
+        if not rules:
+            continue
+        for base_dir in rules["base_dirs"]:
+            dir_path = cwd / base_dir
+            dir_path.mkdir(parents=True, exist_ok=True)
+            (dir_path / "VERSION").write_text(f"{version}\n", encoding="utf-8")
+
+
+def _generate_outputs_best_effort(pkg_root: Path, cwd: Path) -> None:
+    skills_dir = cwd / "skills"
+    if not skills_dir.exists():
+        return
+    specs = sorted(skills_dir.glob("*/skillspec.json"))
+    if not specs:
+        return
+    print("\nGenerating skill outputs from skillspec.json ...")
+    for spec_path in specs:
+        try:
+            ns = argparse.Namespace(repo_root=str(cwd), spec=str(spec_path))
+            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 _handle_init(selected_ais: List[str], mode: str) -> int:
+    pkg_root = _get_pkg_root()
+    cwd = Path.cwd().resolve()
+    version = _get_pkg_version()
+    effective_ais = selected_ais if selected_ais else list(SUPPORTED_AIS)
+
+    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)
+    _write_version_files(cwd, effective_ais, version)
+    print("\nDone! neo-skill initialized.")
+
+    if mode == "init":
+        _write_init_state(cwd, selected_ais)
+
+    return 0
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    ai_values = [a.strip().lower() for a in (args.ai or []) if a]
+    resolved = _resolve_selected_ais(ai_values)
+    if not resolved["ok"]:
+        raise SystemExit(resolved["error"])
+    if not resolved["selected"]:
+        _print_init_help()
+        return 1
+    return _handle_init(resolved["selected"], "init")
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    cwd = Path.cwd().resolve()
+    state = _read_init_state(cwd)
+    if not state["ok"]:
+        raise SystemExit(state["error"])
+    return _handle_init(state["selected"], "update")
+
+
+def _print_init_help() -> None:
+    supported = "|".join(SUPPORTED_AIS + ["all"])
+    print("Usage: omni-skill init --ai <target>")
+    print(f"  <target>: {supported}")
+    print("Examples:")
+    print("  omni-skill init --ai claude")
+    print("  omni-skill init --ai cursor")
+    print("  omni-skill init --ai windsurf")
+    print("  omni-skill init --ai all")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="omni-skill",
+        description="Multi-assistant skill initializer and generator.",
+    )
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Initialize skills for target AI assistants")
+    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_update.set_defaults(func=_cmd_update)
+
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    rc = args.func(args)
+    raise SystemExit(rc)
+
+
+if __name__ == "__main__":
+    main()

package/src/skill_creator/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.11"

package/src/skill_creator/cli.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import List
+
+from .spec.validate import assert_spec_valid, validate_spec
+from .spec.render import generate_all
+from .packaging.package import package_claude_skill, package_repo_zip
+from .util.fs import ensure_dir, write_json
+
+DEFAULT_QUESTIONS: List[str] = [
+    "这个 skill 的一句话目标是什么（动词开头）？",
+    "用户会用哪些触发语句/关键词来表述这个需求（至少 5 条）？",
+    "期望输出是什么形态（报告/代码/补丁/命令/文件树/清单）？",
+    "硬约束有哪些（例如不可改变行为/不可联网/必须跑测试等）？",
+    "允许使用的工具边界是什么（shell/git/python/读写文件/网络等）？",
+    "需要哪些输入（repo/commit/diff/config/logs 等），从哪里来？",
+    "工作流要拆成哪些关键步骤/分支？关键 gate 是什么？",
+    "常见失败/边界情况有哪些？希望如何处理（停止/回退/提示）？",
+    "哪些内容应放到 references 或 scripts 以降低上下文占用？",
+]
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    skill_name = args.name.strip()
+    skill_dir = repo_root / "skills" / skill_name
+    ensure_dir(skill_dir / "references")
+    ensure_dir(skill_dir / "scripts")
+    ensure_dir(skill_dir / "assets")
+
+    spec_path = skill_dir / "skillspec.json"
+    if spec_path.exists() and not args.force:
+        raise SystemExit(f"Spec already exists: {spec_path} (use --force to overwrite)")
+
+    spec = {
+        "version": 1,
+        "name": skill_name,
+        "description": args.description.strip() if args.description else f"<TODO: describe when to use {skill_name}>",
+                "questions": DEFAULT_QUESTIONS,
+        "triggers": [
+            f"Create a new skill named {skill_name}",
+            f"Update the {skill_name} skill",
+            f"Generate SKILL.md for {skill_name}",
+            f"Package {skill_name} as a Claude .skill zip",
+            f"Validate the {skill_name} skill",
+        ],
+        "freedom_level": "low",
+        "workflow": {
+            "type": "sequential",
+            "steps": [
+                {
+                    "id": "collect",
+                    "title": "Collect requirements (<=10 questions)",
+                    "kind": "action",
+                    "commands": [],
+                    "notes": "Ask only what is missing. Never exceed 10 questions total.",
+                },
+                {
+                    "id": "plan",
+                    "title": "Plan resources (SKILL.md vs references vs scripts)",
+                    "kind": "action",
+                    "commands": [],
+                    "notes": "Enforce progressive disclosure: keep SKILL.md concise; move details into references/.",
+                },
+                {
+                    "id": "generate",
+                    "title": "Generate multi-assistant outputs",
+                    "kind": "action",
+                    "commands": [
+                        f"skill-creator generate skills/{skill_name}/skillspec.json",
+                    ],
+                    "notes": "Produce Claude/Windsurf/Cursor/GitHub Skills wrappers.",
+                },
+                {
+                    "id": "validate",
+                    "title": "Validate the spec + outputs",
+                    "kind": "gate",
+                    "commands": [
+                        f"skill-creator validate skills/{skill_name}/skillspec.json",
+                    ],
+                    "notes": "Fail fast on metadata violations or banned files.",
+                },
+                {
+                    "id": "package",
+                    "title": "Package for Claude (.skill)",
+                    "kind": "action",
+                    "commands": [
+                        f"skill-creator package --target claude --skill {skill_name}",
+                    ],
+                    "notes": "Zip root must be the skill folder (not flat files).",
+                },
+            ],
+        },
+        "references": [
+            "references/output-patterns.md",
+            "references/workflows.md",
+        ],
+        "scripts": [
+            "scripts/init_skill.py",
+            "scripts/validate_skill.py",
+            "scripts/package_skill.py",
+        ],
+        "assets": [],
+    }
+
+    # Seed references from shared templates if present
+    shared_data = repo_root / ".shared" / "skill-creator" / "data"
+    if (shared_data / "output-patterns.md").exists():
+        (skill_dir / "references" / "output-patterns.md").write_text(
+            (shared_data / "output-patterns.md").read_text(encoding="utf-8"),
+            encoding="utf-8",
+        )
+    if (shared_data / "workflows.md").exists():
+        (skill_dir / "references" / "workflows.md").write_text(
+            (shared_data / "workflows.md").read_text(encoding="utf-8"),
+            encoding="utf-8",
+        )
+
+    # Minimal script placeholders (deterministic tools often live here)
+    (skill_dir / "scripts" / "init_skill.py").write_text(
+        """# Placeholder: generated skill-specific initializer\n""",
+        encoding="utf-8",
+    )
+    (skill_dir / "scripts" / "validate_skill.py").write_text(
+        """# Placeholder: generated skill-specific validator\n""",
+        encoding="utf-8",
+    )
+    (skill_dir / "scripts" / "package_skill.py").write_text(
+        """# Placeholder: generated skill-specific packager\n""",
+        encoding="utf-8",
+    )
+
+    write_json(spec_path, spec)
+    print(str(spec_path))
+    return 0
+
+
+def cmd_generate(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    spec_path = Path(args.spec).resolve()
+    assert_spec_valid(spec_path)
+    
+    # Determine targets: default is windsurf only, --all for all targets
+    if getattr(args, "all", False):
+        targets = None  # None means all targets
+        print("Generating for all targets (windsurf + backward compat)...")
+    else:
+        targets = [getattr(args, "target", "windsurf") or "windsurf"]
+        print(f"Generating for: {targets[0]} (primary target)")
+    
+    spec = generate_all(repo_root, spec_path, targets=targets)
+    print(f"Generated outputs for: {spec.name}")
+    return 0
+
+
+def _validate_claude_frontmatter(skill_md: Path) -> List[str]:
+    # Strict: frontmatter must contain only name + description.
+    txt = skill_md.read_text(encoding="utf-8")
+    if not txt.startswith("---\n"):
+        return [f"Missing YAML frontmatter: {skill_md}"]
+    try:
+        end = txt.index("\n---\n", 4)
+    except ValueError:
+        return [f"Unterminated YAML frontmatter: {skill_md}"]
+    fm = txt[4:end].strip().splitlines()
+    keys = []
+    for line in fm:
+        if not line.strip() or line.strip().startswith("#"):
+            continue
+        if ":" not in line:
+            continue
+        keys.append(line.split(":", 1)[0].strip())
+    missing = [k for k in ["name", "description"] if k not in keys]
+    extra = [k for k in keys if k not in {"name", "description"}]
+    errs = []
+    if missing:
+        errs.append(f"Frontmatter missing keys {missing}: {skill_md}")
+    if extra:
+        errs.append(f"Frontmatter has extra keys {extra} (Claude strict mode): {skill_md}")
+    return errs
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    spec_path = Path(args.spec).resolve()
+
+    errors = validate_spec(spec_path)
+    if errors:
+        raise SystemExit("Spec validation failed:\n- " + "\n- ".join(errors))
+
+    # Validate generated outputs if present
+    spec_name = Path(args.spec).resolve().parent.name
+    claude_skill_md = repo_root / ".claude" / "skills" / spec_name / "SKILL.md"
+    if claude_skill_md.exists():
+        fm_errors = _validate_claude_frontmatter(claude_skill_md)
+        if fm_errors:
+            raise SystemExit("Claude SKILL.md validation failed:\n- " + "\n- ".join(fm_errors))
+
+    # Ban noisy docs inside target skill folders (keep only execution-relevant files)
+    banned = {"README.md", "CHANGELOG.md", "INSTALL.md"}
+    for target_root in [repo_root / ".claude" / "skills" / spec_name, repo_root / ".github" / "skills" / spec_name]:
+        if not target_root.exists():
+            continue
+        for p in target_root.rglob("*"):
+            if p.is_file() and p.name in banned:
+                raise SystemExit(f"Banned file inside skill bundle: {p}")
+
+    print("OK")
+    return 0
+
+
+def cmd_package(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    out_dir = repo_root / "dist"
+    ensure_dir(out_dir)
+
+    if args.target == "claude":
+        # Validate before packaging
+        cmd_validate(
+            argparse.Namespace(
+                repo_root=str(repo_root),
+                spec=str(repo_root / "skills" / args.skill / "skillspec.json"),
+            )
+        )
+        out = package_claude_skill(repo_root, args.skill, out_dir)
+        print(str(out))
+        return 0
+
+    if args.target == "repo":
+        out = package_repo_zip(repo_root, out_dir / f"{repo_root.name}.zip")
+        print(str(out))
+        return 0
+
+    raise SystemExit(f"Unknown target: {args.target}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="skill-creator",
+        description="Canonical SkillSpec -> multi-assistant skill outputs",
+    )
+    p.add_argument("--repo-root", default=".", help="Repo root (default: current directory)")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Initialize a new skill directory under skills/")
+    p_init.add_argument("name", help="Skill name (kebab-case)")
+    p_init.add_argument("--description", default="", help="Short description (should include trigger conditions)")
+    p_init.add_argument("--force", action="store_true", help="Overwrite if already exists")
+    p_init.set_defaults(func=cmd_init)
+
+    p_gen = sub.add_parser("generate", help="Generate multi-assistant outputs from skillspec.json")
+    p_gen.add_argument("spec", help="Path to skillspec.json")
+    p_gen.add_argument("--target", "-t", choices=["windsurf", "claude", "cursor", "github"],
+                       default="windsurf", help="Target to generate (default: windsurf)")
+    p_gen.add_argument("--all", "-a", action="store_true",
+                       help="Generate for all targets (windsurf + backward compat)")
+    p_gen.set_defaults(func=cmd_generate)
+
+    p_val = sub.add_parser("validate", help="Validate spec and generated outputs")
+    p_val.add_argument("spec", help="Path to skillspec.json")
+    p_val.set_defaults(func=cmd_validate)
+
+    p_pkg = sub.add_parser("package", help="Package outputs")
+    p_pkg.add_argument("--target", choices=["claude", "repo"], required=True)
+    p_pkg.add_argument("--skill", default="", help="Skill name (required for --target claude)")
+    p_pkg.set_defaults(func=cmd_package)
+
+    return p
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    rc = args.func(args)
+    raise SystemExit(rc)

package/src/skill_creator/packaging/package.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..util.fs import ensure_dir
+from .ziputil import zip_dir
+
+
+def package_claude_skill(repo_root: Path, skill_name: str, out_dir: Path) -> Path:
+    """Create a .skill zip for Claude.
+
+    Layout (zip root contains folder <skill_name>/):
+      <skill_name>/SKILL.md
+      <skill_name>/resources/*
+    """
+    claude_skill_dir = repo_root / ".claude" / "skills" / skill_name
+    if not claude_skill_dir.exists():
+        raise FileNotFoundError(f"Claude skill dir not found: {claude_skill_dir}")
+
+    ensure_dir(out_dir)
+    out_path = out_dir / f"{skill_name}.skill"
+    zip_dir(claude_skill_dir, out_path, root_name=skill_name)
+    return out_path
+
+
+def package_repo_zip(repo_root: Path, out_path: Path) -> Path:
+    """Zip the entire repo for distribution (IDE-friendly)."""
+    repo_root = repo_root.resolve()
+    zip_dir(repo_root, out_path, root_name=repo_root.name)
+    return out_path

package/src/skill_creator/packaging/ziputil.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+
+def zip_dir(src_dir: Path, out_path: Path, *, root_name: Optional[str] = None) -> None:
+    """Zip a directory.
+
+    If root_name is provided, the zip will contain entries under that root folder,
+    regardless of the actual directory name.
+    """
+    src_dir = src_dir.resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(out_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in src_dir.rglob("*"):
+            if p.is_dir():
+                continue
+            rel = p.relative_to(src_dir)
+            if root_name:
+                arcname = Path(root_name) / rel
+            else:
+                arcname = rel
+            zf.write(p, arcname.as_posix())