@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/common/skill-creator/references/output-patterns.md

@@ -0,0 +1,82 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+[Overview]
+
+## Key findings
+[Adapt sections based on what you discover]
+
+## Recommendations
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.

package/.agents/skills/common/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/.agents/skills/common/skill-creator/scripts/init_skill.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path>
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-api-helper --path skills/private
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Explain what this skill does and when to use it. Include the task boundary and realistic trigger scenarios.]
+---
+
+# {skill_title}
+
+## 定位
+
+[TODO: 1-2 句说明本技能解决什么问题，以及它不负责什么。]
+
+## 使用时机
+
+- [TODO: 列出 should-trigger 场景]
+- [TODO: 列出 should-not-trigger 或边界场景]
+
+## 工作流
+
+Progress:
+- [ ] 1. [TODO: 明确第一步]
+- [ ] 2. [TODO: 明确第二步]
+- [ ] 3. [TODO: 明确第三步]
+
+## Gotchas
+
+- [TODO: 记录 2-5 条代理容易做错、但不说就会出错的事实]
+
+## 验证
+
+1. [TODO: 描述如何验证结果]
+2. [TODO: 若失败，如何修正并重新验证]
+
+## 资源导航
+
+- `scripts/`：放可复用、可重复执行的脚本；没有就留空或删除目录
+- `references/`：放按需读取的长文档、规范、Schema
+- `assets/`：放模板、样例、图片、字体等输出资源
+- `evals/`：维护 `train_queries.json`、`validation_queries.json`、`evals.json`
+
+## 环境依赖（如适用）
+
+- [TODO: 如果依赖特定 IDE、网络、系统工具或仓库目录，在这里说明，并同步补到 frontmatter.compatibility]
+"""
+
+EXAMPLE_TRAIN_QUERIES = """[
+  {
+    "query": "[TODO: 一个应触发该 skill 的真实用户请求]",
+    "should_trigger": true
+  },
+  {
+    "query": "[TODO: 一个容易误判、但不应触发该 skill 的近似请求]",
+    "should_trigger": false
+  }
+]
+"""
+
+EXAMPLE_VALIDATION_QUERIES = """[
+  {
+    "query": "[TODO: 一个新的 should-trigger 验证请求]",
+    "should_trigger": true
+  },
+  {
+    "query": "[TODO: 一个新的 should-not-trigger 验证请求]",
+    "should_trigger": false
+  }
+]
+"""
+
+EXAMPLE_EVALS = """{
+  "skill_name": "[TODO: replace-with-skill-name]",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "[TODO: 一个真实任务输入]",
+      "expected_output": "[TODO: 成功输出应该达到的效果]",
+      "files": [],
+      "assertions": [
+        "[TODO: 一个可验证断言]"
+      ]
+    }
+  ]
+}
+"""
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"❌ Error: Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"✅ Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"❌ Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(
+        skill_name=skill_name,
+        skill_title=skill_title
+    )
+
+    skill_md_path = skill_dir / 'SKILL.md'
+    try:
+        skill_md_path.write_text(skill_content)
+        print("✅ Created SKILL.md")
+    except Exception as e:
+        print(f"❌ Error creating SKILL.md: {e}")
+        return None
+
+    # Create resource directories and eval skeleton
+    try:
+        for directory_name in ('scripts', 'references', 'assets', 'evals'):
+            (skill_dir / directory_name).mkdir(exist_ok=True)
+            print(f"✅ Created {directory_name}/")
+
+        evals_dir = skill_dir / 'evals'
+        (evals_dir / 'train_queries.json').write_text(EXAMPLE_TRAIN_QUERIES)
+        (evals_dir / 'validation_queries.json').write_text(EXAMPLE_VALIDATION_QUERIES)
+        (evals_dir / 'evals.json').write_text(EXAMPLE_EVALS.replace('[TODO: replace-with-skill-name]', skill_name))
+        print("✅ Created evals/train_queries.json")
+        print("✅ Created evals/validation_queries.json")
+        print("✅ Created evals/evals.json")
+    except Exception as e:
+        print(f"❌ Error creating resource directories: {e}")
+        return None
+
+    # Print next steps
+    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    print("2. Add compatibility only when the skill really depends on tools, network, or repo layout")
+    print("3. Fill train_queries.json, validation_queries.json, and evals.json")
+    print("4. Delete any empty resource directories you do not need")
+    print("5. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    if len(sys.argv) < 4 or sys.argv[2] != '--path':
+        print("Usage: init_skill.py <skill-name> --path <path>")
+        print("\nSkill name requirements:")
+        print("  - Hyphen-case identifier (e.g., 'data-analyzer')")
+        print("  - Lowercase letters, digits, and hyphens only")
+        print("  - Max 64 characters")
+        print("  - Must match directory name exactly")
+        print("\nExamples:")
+        print("  init_skill.py my-new-skill --path skills/public")
+        print("  init_skill.py my-api-helper --path skills/private")
+        print("  init_skill.py custom-skill --path /custom/location")
+        sys.exit(1)
+
+    skill_name = sys.argv[1]
+    path = sys.argv[3]
+
+    print(f"🚀 Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    print()
+
+    result = init_skill(skill_name, path)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"❌ Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/common/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Quick validation wrapper for local skills.
+
+Delegates to the repository's Node-based skill-spec validator so packaging,
+registry validation, and local one-off checks stay aligned.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _validator_path():
+    return Path(__file__).resolve().parents[5] / "bin" / "skill-spec-validator.js"
+
+
+def validate_skill(skill_path):
+    validator = _validator_path()
+    command = ["node", str(validator), str(skill_path), "--json"]
+    result = subprocess.run(command, capture_output=True, text=True)
+
+    if result.returncode not in (0, 1):
+        message = result.stderr.strip() or result.stdout.strip() or "validator execution failed"
+        return False, message
+
+    try:
+        report = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        message = result.stderr.strip() or result.stdout.strip() or "validator returned invalid JSON"
+        return False, message
+
+    if report.get("errors"):
+        return False, "; ".join(report["errors"])
+
+    warning_count = len(report.get("warnings", []))
+    if warning_count > 0:
+        return True, f"Skill is valid with {warning_count} warning(s)"
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

package/.agents/skills/common/skill-optimizer/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: skill-optimizer
+description: 优化和重构现有 skill 的触发描述、工作流、确认门槛和资源组织方式。当用户说“优化 skill”“检查 skill 质量”“改进某个 skill”“重构技能说明”时使用。默认先审查，再出计划，确认后再改。
+---
+
+# Skill 优化器
+
+## 定位
+
+本技能用于优化已有 skill，不负责从零创建 skill。
+
+分工如下：
+
+- `skill-creator`：从无到有创建 skill
+- `skill-optimizer`：审查、收口、重构现有 skill
+
+## 工作原则
+
+- 先审查，再计划，再修改
+- 未确认前不改目标 skill
+- 优先解决触发失败、确认缺失、流程不可执行的问题
+- 只读取目标 skill 直接相关的 `SKILL.md / references / scripts / assets`
+
+默认参考：
+
+- [审查清单](references/review-checklist.md)
+- [设计模式判断](references/design-patterns.md)
+
+## 工作流
+
+复制并跟踪这份清单：
+
+```text
+优化进度：
+- [ ] 1. 确定范围
+- [ ] 2. 审查现状
+- [ ] 3. 输出优化计划
+- [ ] 4. 用户确认
+- [ ] 5. 实施与校验
+```
+
+### 1. 确定范围
+
+- 先确认目标 skill
+- 若用户只给方向，例如“只改 description”，则只做局部审查
+- 若用户只说“优化这个 skill”，先给完整审查结论
+
+### 2. 审查现状
+
+重点检查：
+
+- `description` 是否同时说明“做什么”和“何时用”
+- SKILL.md 是否清晰、可执行、不过胖
+- 是否缺少确认门槛、gotchas、模板、脚本或 references
+- 是否把重型细节塞进正文而不是拆到 references
+- 输出格式是否稳定，能否交给另一个 agent 执行
+
+### 3. 输出优化计划
+
+必须先给：
+
+1. 审查结论
+2. 分优先级的优化计划
+
+不要直接改文件。
+
+### 4. 用户确认
+
+- 明确等待确认
+- 若用户只同意部分变更，只实施已确认范围
+
+### 5. 实施与校验
+
+至少校验：
+
+- frontmatter 合法
+- `name`、目录名、触发语义一致
+- `description` 能独立触发
+- 主体更短、更清晰、更可执行
+
+## 输出模板
+
+```md
+# Skill 审查结论
+
+## 高优先级
+- ...
+
+## 中优先级
+- ...
+
+# 优化计划
+1. 修改 ...
+2. 新增 ...
+3. 删除或下沉 ...
+```
+
+## 禁止事项
+
+- 未确认前直接改目标 skill
+- 为了“完整”把无关 reference 全部读进上下文
+- 顺手扩大范围，把局部优化升级成整套重构

package/.agents/skills/common/skill-optimizer/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "skill-optimizer",
+  "evals": [
+    {
+      "id": "optimizer-output-1",
+      "prompt": "审查一个现有 skill，指出 description、workflow 和 resources 的问题，并给出分优先级优化计划。",
+      "files": [],
+      "expected_output": "输出应先给审查结论，再给按优先级排序的优化计划，不直接改文件。",
+      "assertions": [
+        "先审查后计划",
+        "指出触发、结构和资源组织问题",
+        "保留等待用户确认的门槛"
+      ]
+    }
+  ]
+}

package/.agents/skills/common/skill-optimizer/evals/train_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "优化这个 skill 的触发描述和 references 结构",
+    "should_trigger": true
+  },
+  {
+    "query": "检查一下这个 skill 为什么老是误触发",
+    "should_trigger": true
+  },
+  {
+    "query": "帮我新建一个 skill",
+    "should_trigger": false
+  },
+  {
+    "query": "给现有 skill 加一个脚本并重构正文",
+    "should_trigger": true
+  }
+]

package/.agents/skills/common/skill-optimizer/evals/validation_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "重写 skill 的 workflow 和 gotchas",
+    "should_trigger": true
+  },
+  {
+    "query": "审查这个 skill 的 frontmatter 是否合规",
+    "should_trigger": true
+  },
+  {
+    "query": "从零搭一个新 skill 包",
+    "should_trigger": false
+  },
+  {
+    "query": "给我列出有哪些可安装的开源 skills",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/skill-optimizer/references/design-patterns.md

@@ -0,0 +1,26 @@
+# Skill 设计模式判断
+
+优化现有 skill 时，先判断它主要属于哪类模式：
+
+- `Tool Wrapper`
+  - 主要职责是稳定调用某个工具或脚本
+- `Generator`
+  - 主要职责是产出文档、代码骨架或模板
+- `Reviewer`
+  - 主要职责是检查、评审、给出问题项
+- `Inversion`
+  - 主要职责是先计划、先确认，再进入实施
+- `Pipeline`
+  - 主要职责是组织多个顺序步骤
+
+判断标准：
+
+- 如果主要价值在“发现问题”，优先按 `Reviewer`
+- 如果主要价值在“先出方案再动手”，优先按 `Inversion`
+- 如果主要价值在“稳定生成产物”，优先按 `Generator`
+
+常见问题：
+
+- 一个 skill 同时承担 Review、Plan、Implement，导致门槛模糊
+- 明明是 `Reviewer`，却把大量生成模板塞进正文
+- 明明是 `Pipeline`，却没有明确的停止条件和确认点

package/.agents/skills/common/skill-optimizer/references/review-checklist.md

@@ -0,0 +1,22 @@
+# Skill 审查清单
+
+按以下顺序检查：
+
+1. 触发是否清晰
+2. 工作流是否可执行
+3. 是否存在必须确认却没有卡住的步骤
+4. 正文是否过胖，是否应拆到 `references/` 或 `scripts/`
+5. 输出是否稳定、便于交接
+6. 是否有明显的默认行为越权
+
+优先修复：
+
+- 触发不准
+- 工作流断裂
+- 缺少确认门槛
+
+其次修复：
+
+- 结构臃肿
+- references / scripts / assets 组织混乱
+- 输出格式不稳定