neo-skill 0.1.11

package/skills/skill-creator/references/skill-system-design.md

@@ -0,0 +1,112 @@
+# Skill System Design
+
+How to design a complete skill system using the search tool and reasoning rules.
+
+## Design System Generation
+
+Use the search tool to generate a comprehensive skill system:
+
+```bash
+python3 .shared/skill-creator/scripts/search.py "<keywords>" --skill-system -p "<project_name>"
+```
+
+This command:
+1. Searches all domains (workflow, output, resource, trigger, validation)
+2. Applies reasoning rules from `skill-reasoning.csv`
+3. Returns complete design: pattern, output, resources, rules
+
+## Design Components
+
+### 1. Workflow Pattern
+
+Choose based on task complexity:
+
+| Pattern | When to Use | Example |
+|---------|-------------|---------|
+| Sequential | Linear tasks, clear dependencies | collect → generate → validate |
+| Conditional | Multiple paths, feature flags | if new: create else: update |
+| Gated | Quality-critical, multi-phase | step → gate → step → gate |
+| Parallel | Independent subtasks | [search_a, search_b] → merge |
+| Iterative | Refinement, feedback loops | draft → review → revise |
+
+### 2. Output Pattern
+
+Match output to task type:
+
+| Task Type | Output Pattern | Template Location |
+|-----------|---------------|-------------------|
+| Review/Audit | Checklist | `references/checklist-template.md` |
+| Generation | Code + Tree | inline or `scripts/` |
+| Analysis | Report | `references/report-template.md` |
+| Fix/Debug | Patch/Diff | inline |
+| Transform | Structured data | `assets/` |
+
+### 3. Resource Strategy
+
+Apply progressive disclosure:
+
+| Content Type | Location | When |
+|--------------|----------|------|
+| Rules/Guidelines | `references/` | Static knowledge AI reads |
+| Data/Templates | `assets/` | Structured, searchable data |
+| Deterministic ops | `scripts/` | Reproducible execution |
+| Cross-skill shared | `.shared/` | Reusable across skills |
+| Step-local only | `notes` field | Truly unique to one step |
+
+### 4. Reasoning Rules
+
+Common reasoning patterns from `skill-reasoning.csv`:
+
+| Condition | Recommendation | Rationale |
+|-----------|---------------|-----------|
+| Deterministic output | Use scripts/ | Reproducible results |
+| Large context (>2000 tokens) | Progressive disclosure | Split into references/ |
+| Reusable rules | Shared data | Move to .shared/ |
+| Multi-step workflow | Sequential with gates | Validation between phases |
+| User input required | Collect step first | Ensure requirements met |
+| Error-prone step | Add gate | Clear error messages |
+
+## Master + Overrides Pattern
+
+For complex skills, use hierarchical configuration:
+
+### Master (skillspec.json)
+- Contains all default rules
+- Single source of truth
+- All steps reference it
+
+### Overrides (references/<context>.md)
+- Context-specific deviations
+- Override master for specific pages/steps
+- Document why deviation is needed
+
+### Lookup Order
+1. Check `references/<context>.md` for specific context
+2. Fall back to `skillspec.json` defaults
+3. Fall back to `.shared/` common patterns
+
+## Example Design Session
+
+**Input**: "code review skill for TypeScript projects"
+
+```bash
+python3 .shared/skill-creator/scripts/search.py "code review typescript audit" --skill-system -p "ts-review"
+```
+
+**Output**:
+```
+╔════════════════════════════════════════════════════════════════╗
+║  SKILL SYSTEM: ts-review                                       ║
+╠════════════════════════════════════════════════════════════════╣
+║  WORKFLOW: Gated Workflow                                      ║
+║    Checkpoints that must pass before proceeding                ║
+║  OUTPUT: Checklist Pattern                                     ║
+║    Actionable items with status                                ║
+║  RESOURCES: Reference Documents                                ║
+╠════════════════════════════════════════════════════════════════╣
+║  APPLICABLE RULES:                                             ║
+║    • review_task: checklist_output                             ║
+║    • multi_step_workflow: sequential_with_gates                ║
+║    • large_context: progressive_disclosure                     ║
+╚════════════════════════════════════════════════════════════════╝
+```

package/skills/skill-creator/references/sources.md

@@ -0,0 +1,5 @@
+# Sources / Notes
+
+- Agent Skills spec (progressive disclosure, metadata): https://agentskills.io/specification
+- Anthropic agent skills repo (skill-creator example): https://github.com/anthropics/skills
+- ui-ux-pro-max-skill (multi-assistant adapters + shared data/scripts): https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

package/skills/skill-creator/references/workflow-step-editing.md

@@ -0,0 +1,103 @@
+# Workflow Step Editing Protocol
+
+Use this protocol when the task is to update an existing skill (not create a new one) by modifying `workflow.steps` in `skills/<skill>/skillspec.json`.
+
+## Inputs (must collect)
+
+- **Target**: which existing skill to update (`<skill>`)
+- **Current spec**: contents of `skills/<skill>/skillspec.json`
+- **New requirements**: the user's new needs (can be bullets, examples, constraints)
+- **Constraints**: hard limits (tools allowed, compatibility, fail-fast gates, etc.)
+- **Knowledge base structure**: what should live in `references/` (rules/specs/templates) vs `assets/` (data/templates) vs `scripts/` (deterministic execution)
+
+## Output contract (must produce)
+
+- **Change summary**
+  - Added steps
+  - Removed steps
+  - Merged steps
+  - Step edits (notes/commands/kind/title)
+  - Rationale for each structural change
+  - Knowledge base edits (references/assets/scripts)
+- **Final `workflow.steps`** (as JSON array)
+- **Notes on rerunning generation**
+
+## Step mapping procedure
+
+1. **Normalize requirements**
+   - Rewrite the user's needs into atomic requirements (one intent per line).
+   - Tag each as one of:
+     - `action` (do something)
+     - `gate` (must block on failure)
+     - `branch` (conditional/decision)
+
+2. **Extract current step intents**
+   - For each existing step, summarize:
+     - Primary intent
+     - Inputs it needs
+     - Outputs it produces
+     - Whether it is `action` / `gate`
+
+3. **Classify each atomic requirement**
+   - Try to place it into exactly one existing step.
+   - If it fits multiple steps, choose the one with the strongest ownership and add a short note explaining why.
+   - If it fits none, mark as `needs_new_step`.
+
+4. **Design new steps (only when needed)**
+   - Create a new step if:
+     - It introduces a new phase (new inputs, new outputs), or
+     - It would overload an existing step's intent.
+   - Step `id` rules:
+     - kebab-case
+     - stable, intent-based (avoid renaming unless necessary)
+   - Step `notes` rules:
+     - Prefer **index-style notes**: keep `workflow.steps[*].notes` short and point to canonical knowledge in `references/` or `assets/`.
+     - Put detailed rule text, denylist/allowlist, and examples into `references/*.md` (or `assets/*` when it is structured data).
+     - Only keep step-local details in `notes` when they are truly unique and cannot be shared.
+
+5. **Delete or merge steps (allowed but strict)**
+   - **Merge** only if two steps have overlapping intent and their separation no longer provides clarity or gating value.
+   - **Delete** only if:
+     - It is fully subsumed by other steps, and
+     - It does not represent a required gate, and
+     - You provide an explicit mapping showing where its responsibilities went.
+
+## Safety checks (must pass)
+
+- **No lost requirements**: every atomic requirement must be mapped to a final step.
+- **Gate preservation**: if an existing step is a `gate`, do not delete it unless its check is preserved elsewhere.
+- **Command contract**: any step that relies on deterministic scripts must keep commands copy-pastable.
+- **Minimal disruption**: prefer editing `notes/commands` over renaming/reordering steps.
+- **Knowledge-base first**: if a step becomes long or rule-heavy, move the details into `references/` or `assets/` and keep the step as an index.
+
+## Final output template
+
+### Change summary
+
+- Added steps:
+- Removed steps:
+- Merged steps:
+- Edited steps:
+- Rationale:
+
+### Final workflow.steps (JSON)
+
+```json
+[
+  {
+    "id": "<id>",
+    "title": "<title>",
+    "kind": "action",
+    "commands": [],
+    "notes": "<notes>"
+  }
+]
+```
+
+### Regeneration
+
+Regenerate multi-assistant outputs after updating the spec:
+
+```bash
+omni-skill init --skill <skill>
+```

package/skills/skill-creator/references/workflows.md

@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
+
+```markdown
+Filling a PDF form involves these steps:
+
+1. Analyze the form (run analyze_form.py)
+2. Create field mapping (edit fields.json)
+3. Validate mapping (run validate_fields.py)
+4. Fill the form (run fill_form.py)
+5. Verify output (run verify_output.py)
+```
+
+## Conditional Workflows
+
+For tasks with branching logic, guide Claude through decision points:
+
+```markdown
+1. Determine the modification type:
+   **Creating new content?** → Follow "Creation workflow" below
+   **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```

package/skills/skill-creator/scripts/init_skill.py

@@ -0,0 +1,34 @@
+"""skill-creator: deterministic initializer.
+
+Thin wrapper around the repository CLI (keeps skill bundles small).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _add_src_to_path() -> None:
+    repo_root = Path(__file__).resolve().parents[3]
+    src = repo_root / "src"
+    if str(src) not in sys.path:
+        sys.path.insert(0, str(src))
+
+
+def main() -> int:
+    # Usage:
+    #   python3 skills/skill-creator/scripts/init_skill.py <skill-name> [--description "..."]
+    if len(sys.argv) < 2:
+        print('Usage: python3 skills/skill-creator/scripts/init_skill.py <skill-name> [--description "..."]')
+        return 2
+    _add_src_to_path()
+    name = sys.argv[1]
+    extra = sys.argv[2:]
+    cmd = [sys.executable, "-m", "skill_creator.cli", "init", name] + extra
+    return subprocess.call(cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,34 @@
+"""skill-creator: deterministic packager.
+
+Packages a Claude-ready .skill zip.
+
+Usage:
+  python3 skills/skill-creator/scripts/package_skill.py <skill-name>
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _add_src_to_path() -> None:
+    repo_root = Path(__file__).resolve().parents[3]
+    src = repo_root / "src"
+    if str(src) not in sys.path:
+        sys.path.insert(0, str(src))
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: python3 skills/skill-creator/scripts/package_skill.py <skill-name>")
+        return 2
+    _add_src_to_path()
+    skill_name = sys.argv[1]
+    cmd = [sys.executable, "-m", "skill_creator.cli", "package", "--target", "claude", "--skill", skill_name]
+    return subprocess.call(cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/skill-creator/scripts/validate_skill.py

@@ -0,0 +1,35 @@
+"""skill-creator: deterministic validator.
+
+Validates:
+- SkillSpec schema (kebab-case name, <=10 questions, workflow exists)
+- Generated Claude SKILL.md strict frontmatter (only name/description)
+- Banned files inside skill bundles (README/CHANGELOG/etc)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _add_src_to_path() -> None:
+    repo_root = Path(__file__).resolve().parents[3]
+    src = repo_root / "src"
+    if str(src) not in sys.path:
+        sys.path.insert(0, str(src))
+
+
+def main() -> int:
+    # Usage:
+    #   python3 skills/skill-creator/scripts/validate_skill.py skills/<skill>/skillspec.json
+    if len(sys.argv) != 2:
+        print("Usage: python3 skills/skill-creator/scripts/validate_skill.py skills/<skill>/skillspec.json")
+        return 2
+    _add_src_to_path()
+    cmd = [sys.executable, "-m", "skill_creator.cli", "validate", sys.argv[1]]
+    return subprocess.call(cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/skill-creator/skillspec.json

@@ -0,0 +1,117 @@
+{
+  "version": 1,
+  "name": "skill-creator",
+  "description": "对话式收集需求（最多 10 问），生成 Windsurf workflow（主要目标）+ Claude/Cursor/GitHub Skills 兼容输出。支持多级数据索引、共享资源架构、Master+Overrides 模式。",
+  "primary_target": "windsurf",
+  "backward_compat": ["claude", "cursor", "github"],
+  "questions": [
+    "这个 skill 的一句话目标是什么（动词开头，面向可重复任务）？",
+    "用户会用哪些触发语句/关键词来表述这个需求（至少 5 条）？",
+    "期望输出是什么形态（报告/代码/补丁/命令/文件树/清单等）？",
+    "硬约束有哪些（例如不可改变行为/不可联网/必须跑测试等）？",
+    "允许使用的工具边界是什么（shell/git/python/读写文件/网络等）？",
+    "需要哪些输入（repo/commit/diff/config/logs 等），从哪里来？",
+    "工作流要拆成哪些关键步骤/分支？关键 gate 是什么？",
+    "常见失败/边界情况有哪些？希望如何处理（停止/回退/提示）？",
+    "哪些内容应放到 references/（规则）、assets/（数据）、scripts/（确定性执行）或 .shared/（跨skill复用）？"
+  ],
+  "triggers": [
+    "我想做一个 skill",
+    "帮我生成 Windsurf workflow",
+    "帮我生成 SKILL.md",
+    "把我的 prompt 工作流变成 skill",
+    "帮我在已有 skill 的基础上补充/重构 workflow steps",
+    "做一个 skill 库/skill creator",
+    "打包成 Claude .skill",
+    "create a new skill",
+    "generate workflow for my task"
+  ],
+  "freedom_level": "low",
+  "workflow": {
+    "type": "sequential",
+    "steps": [
+      {
+        "id": "analyze",
+        "title": "分析用户需求",
+        "kind": "action",
+        "commands": [],
+        "notes": "提取关键信息：任务类型、输出形态、约束条件、工具边界。可用搜索辅助：`python3 .shared/skill-creator/scripts/search.py \"<keywords>\" --skill-system`"
+      },
+      {
+        "id": "collect",
+        "title": "对话式收集需求（<=10 问）",
+        "kind": "action",
+        "commands": [],
+        "notes": "只问缺失信息；最多 10 个问题；优先级：目标 > 触发词 > 输出形态 > 约束 > 工具边界。详见 `references/requirement-collection.md`"
+      },
+      {
+        "id": "design",
+        "title": "设计 Skill 系统（Master + Overrides）",
+        "kind": "action",
+        "commands": [
+          "python3 .shared/skill-creator/scripts/search.py \"<task_keywords>\" --skill-system -p \"<skill_name>\""
+        ],
+        "notes": "生成完整设计：workflow pattern + output pattern + resource strategy + reasoning rules。详见 `references/skill-system-design.md`"
+      },
+      {
+        "id": "spec",
+        "title": "落地 SkillSpec（单一真源）",
+        "kind": "action",
+        "commands": [],
+        "notes": "写入 skills/<name>/skillspec.json；采用索引式 notes（指向 references/）；确定 references/scripts/assets/.shared 分布。"
+      },
+      {
+        "id": "edit-workflow",
+        "title": "补充/重构 workflow steps",
+        "kind": "action",
+        "commands": [],
+        "notes": "更新已有 skill 时：读取现有 spec → 归类新需求到已有 step → 必要时新增/合并 step → 输出变更摘要。协议见 `references/workflow-step-editing.md`"
+      },
+      {
+        "id": "generate",
+        "title": "生成 Windsurf workflow（+ 兼容输出）",
+        "kind": "action",
+        "commands": [
+          "python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json",
+          "python3 .shared/skill-creator/scripts/generate.py skills/<skill>/skillspec.json --all"
+        ],
+        "notes": "默认只生成 Windsurf；--all 生成全部兼容目标（Claude/Cursor/GitHub）。"
+      },
+      {
+        "id": "validate",
+        "title": "校验（spec + outputs + 结构）",
+        "kind": "gate",
+        "commands": [
+          "python3 .shared/skill-creator/scripts/validate.py skills/<skill>/skillspec.json"
+        ],
+        "notes": "检查：kebab-case 命名、questions<=10、Claude frontmatter strict、无 banned files。详见 `.shared/skill-creator/data/validation-rules.csv`"
+      },
+      {
+        "id": "checklist",
+        "title": "Pre-delivery Checklist",
+        "kind": "gate",
+        "commands": [],
+        "notes": "交付前检查：triggers 覆盖常见表述、workflow steps 完整、references 无冗余、scripts 可执行。详见 `references/pre-delivery-checklist.md`"
+      },
+      {
+        "id": "package",
+        "title": "打包分发",
+        "kind": "action",
+        "commands": [
+          "python3 .shared/skill-creator/scripts/package.py --target claude --skill <skill>"
+        ],
+        "notes": "Claude .skill zip（根是 skill 文件夹）；可选 --target repo 打包整个仓库。"
+      }
+    ]
+  },
+  "references": [
+    "references/output-patterns.md",
+    "references/workflows.md",
+    "references/workflow-step-editing.md",
+    "references/requirement-collection.md",
+    "references/skill-system-design.md",
+    "references/pre-delivery-checklist.md"
+  ],
+  "scripts": [],
+  "assets": []
+}

package/src/omni_skill/__init__.py

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