CocoLoop Skill Factory

引导需求、检索参考、装配多平台 Skill 产物的工厂

Overview

cocoloop-skill-factory 是一个面向 codex、claude code、openclaw、copaw、molili、hermes agent 的 Meta Skill。 它负责把用户的想法推进成一份稳定 spec，并把构建方向、模板选择、原子能力、脚本化策略和平台兼容边界整理清楚，最终服务于 Skill 生成与交付。

当用户出现这些诉求时使用本 Skill：

• 想从零创建一个新 Skill
• 想升级、改造、移植一个已有 Skill
• 想先找现成 Skill，再判断复用、改造还是新做
• 想把平台差异、脚本化能力、模板选择和 benchmark 规划统一起来

Factory Rules

整个流程都围绕这几条规则执行：

1. 先判定任务域，再继续调研平台、依赖和执行面。
2. 先形成 spec，再进入构建与交付判断。
3. 调研和设计都保持双钻节奏，先发散，再收敛。
4. 分步询问：对话每次只推进一个关键问题，严禁一次性列出所有问题等待用户回答。必须等用户回答后再问下一个问题。
5. 问题预算：进入调研后要先规划整轮交互的问题预算，默认总问题数不得超过 10 个。能用默认值、环境检测、已有上下文或确认题解决的，不再追加开放式追问。
6. 环境 gate：在目标运行环境没有确认前，不得开始写 Skill 正文、模板、脚手架、实现步骤或构建命令。必须先拿到环境检测结果，再确认“当前环境是否就是目标环境”；如果不是，要同时写清当前环境和目标环境。
7. cocoloop、clawhub 与 github 搜索在正常环境下默认进入流程；通用社区检索按需补充；不可用时允许降级，但要记录缺口。
8. 平台兼容声明必须以公开标准或已核实的本地协议为依据，不能凭经验口头承诺。
9. 推荐外部方案时，要同时给出接入方式、依赖门槛、风险和替代路径。
10. benchmark 是可选阶段，只在适合比较的任务里进入，并且默认按任务域判断是否适合进入。

Workflow

命令运行约定：

• 如果当前目录是 cocoloop-skill-factory/，使用 python3 utils/cli/<script>.py ...
• 如果当前目录是工作区根目录，使用 python3 cocoloop-skill-factory/utils/cli/<script>.py ...
• CLI 文件带有 shebang，也可以直接执行，但默认优先推荐 python3 ... 的写法

关键 CLI：

• detect-environment.py
• search-registry.py
• reference-skill.py

当前 CLI 边界：

• detect-environment.py 用于环境检测
• search-registry.py 用于统一承载 cocoloop、clawhub 与 github 搜索
• reference-skill.py 用于把本地或 GitHub 候选 Skill 拉取到证据目录，并生成 JSON / Markdown 分析摘要
• 当前版本不提供完整的自动生成与发布 CLI，但必须在文档层明确生成、校验和发布所缺的环节

其中 search-registry.py 是对 PRD 中 cocoloop-search、clawhub-search 与 GitHub 检索的合并实现，只覆盖搜索能力本身，不新增额外流程能力。 其中 reference-skill.py 只负责候选方案证据化和目录分析，不替代设计判断。

Step 1: Initialize

先快速建立当前任务边界。

执行动作：

1. 判断用户要创建新 Skill，还是升级已有 Skill。
2. 检查当前仓库、工作区或现有文件里是否已经有相关上下文。
3. 运行 python3 utils/cli/detect-environment.py，获取平台、系统、Shell、浏览器与本地工具线索。
4. 先确认当前环境是否就是目标运行环境；如果不是，继续让用户明确目标平台、目标系统和关键运行前提。
5. 在环境结论没有确认前，不进入 Skill 正文、模板、脚手架或构建步骤的撰写。
6. 先判断当前需求属于哪个任务域；如果 presets/ 里已有对应预设，立即读取。
7. 如果用户说“目标平台就是当前环境”，用检测结果提供候选线索，再请用户确认。
8. 判断当前环境里是否已有成熟 brainstorming 能力；如没有，再回退到 sub-skills/brainstorm/SKILL.md。

Step 2: Research

进入需求调研阶段时，阅读 ref/research.md。

调研阶段先做任务域路由

• 先判定 primary_domain
• 如果需求明显跨域，再补 peer_domains
• 如果 presets/ 中已有对应预设，优先按预设问题包继续追问
• 如果没有完全匹配的预设，也要先给出最接近的主域判断，再把剩余部分写入研究缺口

调研阶段核心原则：分步询问，一次一个问题

• 每一轮对话只问一个关键问题，严禁一次性列出多个问题
• 必须得到用户回答后，才能决定并询问下一个问题
• 如果用户给出的信息涉及多个维度，拆分成连续轮次推进
• 维持对话的连续性，避免信息过载

调研阶段核心原则：先规划问题预算，总量不超过 10 个

• 进入调研后，先根据当前任务域和缺口列出最小问题集，再开始追问
• 整轮需求调研默认总问题数不得超过 10 个，包含确认题
• 如果用户初始信息已经较完整，要主动合并或跳过冗余问题，而不是把预算问满
• 当预计会超过 10 个问题时，优先改成选项题、确认题、默认值和环境检测，不继续扩张访谈
• 在第 6 到第 8 个问题时，优先开始收口，整理已确认项、未确认项和默认假设
• 如果还有缺口但继续追问收益不高，明确记录到 open_gaps，再进入设计，不要无限延长调研

调研阶段核心原则：先确认运行环境，再开始写

• 优先用环境检测拿到当前环境线索，再确认目标环境
• 如果用户说“就在当前环境里跑”，必须把当前环境和目标环境做一次显式确认
• 如果目标环境与当前环境不同，必须同时记录两者差异，不能只写当前环境
• 在环境未确认前，只允许继续做澄清，不允许开始写 Skill 正文、模板、脚手架、实现步骤或构建命令

调研阶段核心原则：先确认实现方式，再开始写

• 必须先确认当前任务的实现方式，也就是选定 Skill-only、Skill + CLI、Skill + API/MCP 或 Skill + CLI + API/MCP
• 如果主任务域已有推荐执行面，需要让用户确认是接受该默认执行面，还是切换到替代路径
• 在实现方式没有确认前，不开始写脚本方案、adapter、manifest、依赖安装步骤或构建命令

提问交互格式：

1. 选项类问题：提供 3-5 个有序选项（1-5），便于用户直接回复数字

   • 示例：目标平台选择、交付预期选择
   • 必须标注推荐答案

2. 路径选择类问题：提供 2-3 个实现路径

   • 示例：复用现成 / 改造 / 从零设计
   • 必须说明各路径的适用场景、优势和风险
   • 明确标注推荐路径及理由

3. 开放式问题：提供提示和示例，引导用户描述

   • 示例：「请描述核心问题是什么？提示：从谁在什么场景下遇到什么痛点来描述」

4. 确认类问题：汇总已确认信息，提供继续/暂停/修改选项

   • 示例：「当前已确认：... 是否继续？1. ✅ 确认 2. ⏸️ 暂停 3. 📝 修改」

调研阶段必须拿到这些信息（分步采集）：

• 主任务域、并列补充域，以及是否跨域
• 用户想解决的问题与使用场景
• 正式名称与展示名称
• 目标平台与运行环境
• 当前环境是否就是目标运行环境，以及两者差异
• 实现方式，也就是最终采用哪种执行面
• 目标平台对应的支持等级、公开标准来源，以及用户是否接受当前等级边界
• 正式名称是否已完成 cocoloop 和 clawhub 双源去重
• 偏好脚本语言、不可接受的脚本语言，以及运行时限制
• 依赖偏好与权限限制
• 如果涉及网页、图片、Figma 或其他视觉输出，要收集风格偏好，并判断是否需要引入风格约束型 Skill
• 如果已经明显包含可视化输出，要隐式把这个判断写入 output_profile.has_visual_output
• 如果涉及创作写作类输出，要收集受众、语气、篇幅、参考边界和禁忌表达
• 如果涉及网站自动化、登录态操作、批量发布或抓取，要先醒目声明账号、频率限制、验证码、反爬和平台规则风险，再继续调研
• 如果涉及强需求浏览器自动化，要比较可用执行面，并明确用户接受的安装与维护成本
• 交付预期
• 哪些能力应脚本化，哪些保持文档或模板表达
• 成功标准与是否需要 benchmark

视觉输出场景的默认推荐顺序：

• 网页、落地页、应用 UI：优先判断是否需要 frontend-skill
• 单张信息图、视觉说明图、传播型图卡：优先判断是否需要 imagegen
• 用户明确要求 Nothing 风格：再引入 nothing-design
• 图片生成或图片编辑：判断是否需要 imagegen 或 gemini-image
• 如果最终交付物是 .pptx，优先判断是否需要 slides
• 如果当前环境没有合适的风格约束 Skill，仍然要把风格偏好写入 spec，而不是跳过

视觉优先任务的强制规则：

• 如果任务涉及网站视觉、视觉优先页面、信息图、视觉卡片或演示稿视觉，在进入具体设计前，必须先确认风格来源
• 风格来源只允许这四类：用户指定风格、用户提供 DESIGN.md、用户详细描述、从 ref/design-md/ 本地参考库中选择
• 如果这四类输入都没有，只继续追问风格来源，不进入具体版式和视觉方案
• 如果需求进入正式视觉方案，继续把风格结论写入 design_md，让最终 Skill 自带 references/design.md
• 只要任务包含任何可视化输出，统一 spec 中就必须写出 output_profile.has_visual_output: true
• 如果目标产物属于 PPT、网页信息图、展示图、报告页等视觉叙事型产物，优先读取 atomic-capability/structured-visual-storytelling/

名称收口的强制规则：

• 正式名称对标最终 slug，必须使用短横线连接的小写英文与数字
• 展示名称对标最终 display name，长度不得超过 20 个字符
• 在进入设计或生成前，必须完成 cocoloop 和 clawhub 双源去重
• 双源去重结果要写进 research_gate.skill_identity

创作写作类场景的处理原则：

• 先确认写作对象、发布场景、语气、篇幅和参考边界
• 如果当前环境里有合适的写作或风格类 Skill，再进入推荐
• 如果没有现成 Skill，也要把风格约束明确写进需求结果与后续 spec

强需求浏览器自动化场景的处理原则：

• 先判断任务能否被文本接口、公开 API 或轻量抓取替代，能替代时不要默认上浏览器自动化
• 如果必须上浏览器自动化，至少向用户比较 2 条方向，常用候选是 opencli、agent-browser、playwright-interactive
• 比较时至少说明这几个维度：是否复用现有登录态、安装门槛、调试深度、稳定性、维护成本、失败后的替代路径
• 如果用户接受额外安装，且任务已落在 OpenCLI 已有站点命令、opencli browser 或适配器流程可覆盖的范围内，优先推荐 OpenCLI
• 选择 OpenCLI 时，补充 atomic-capability/browser-access/opencli-browser-bridge.md 中的扩展安装与 opencli doctor 验证步骤
• 如果任务更偏本地页面验证、结构化截图、表单回归或独立浏览器流程，优先把 agent-browser 作为候选
• 如果任务更偏本地 Web 或 Electron 调试、持久会话 QA、反复迭代验证，再把 playwright-interactive 纳入候选

如果用户一开始就已经给出很清楚的 spec，可缩短调研轮数，但不能跳过收口确认。

Step 3: Search And Reference

当需求轮廓已经稳定，就进入搜索判断。

默认顺序：

1. 先根据主任务域和预设整理默认搜索关键词
2. 运行 python3 utils/cli/search-registry.py --source cocoloop --query '...' --exact-slug '<slug>'
3. 运行 python3 utils/cli/search-registry.py --source clawhub --query '...' --exact-slug '<slug>'
4. 运行 python3 utils/cli/search-registry.py --source github --query '...'
5. 对进入正式比较范围的本地或 GitHub 候选，运行 python3 utils/cli/reference-skill.py fetch ... 拉取并生成 _reference-analysis.md
6. 如仍有明显缺口，再补通用社区或网页搜索
7. 把结果整理成“直接复用 / 参考改造 / 仅供借鉴 / 放弃”四种结论

判断时至少回答这些问题：

• 候选 Skill 与当前需求的重合度有多高
• 是否覆盖当前主任务域的核心高频任务
• 是否覆盖目标平台
• 是否有明显依赖门槛或安全风险
• 如果采用它，用户得到的是安装、二次设计，还是只拿它的能力结构
• 如果它属于浏览器自动化候选，当前覆盖面是否已经足够支撑任务，还是只能作为备选路径

如果搜索不可用，保留降级记录，再继续设计流程。

Step 4: Design

进入设计阶段时，阅读 ref/design.md。

设计阶段的硬规则：

• 优先读取当前主任务域对应的预设，再展开方案比较
• 如果任务涉及排版、视觉设计、网站风格、信息图或演示稿视觉，先确认风格来源，再进入具体设计
• 如果任务属于更广义的视觉叙事型产物，先走 structured-visual-storytelling 的共享主线，再选 ppt、web_infographic 或 showcase_graphic adapter
• 只要搜索结果里有需要深入判断的候选 Skill，就必须先把候选 Skill 全量拉取到本地再分析，不能只依据搜索摘要做设计决策
• 本地分析时，要完整查看 SKILL.md、子目录结构、脚本、参考文档、模板、依赖声明和关键资源
• 需要复用或借鉴的能力、设计要点、功能最佳实践和限制条件，必须详细写入设计文档，而不是只保留在临时分析里
• 如果当前设计在比较浏览器自动化方向，需要把 opencli、agent-browser、playwright-interactive 的安装方式、运行前置动作、适用边界和推荐顺序一起写进设计文档

视觉风格参考默认读取顺序：

1. 用户自己的品牌规范或 DESIGN.md
2. 用户明确点名的风格
3. ref/design-md/ 本地风格参考库
4. 用户的自然语言风格描述

当前官方预设优先级：

1. IBM
2. Stripe
3. Notion
4. Framer
5. Figma
6. Nothing
7. Apple

设计阶段必须先展开两到三条路线，再帮助用户收敛。常见路线：

• 直接复用现成 Skill
• 基于现成 Skill 做二次设计
• 从零构建新 Skill

设计收口时，要明确这些结论：

• 当前版本的目标与边界
• 目标平台集合
• 主流程结构
• 内置原子能力与外部依赖的取舍
• 平台模板选择
• benchmark 是否进入，以及为什么

Step 5: Construction Planning

进入构建准备时，阅读 ref/construction.md。

此阶段的核心动作：

1. 把研究与设计结论整理成统一 spec 和构建说明。 先形成一份结构化 spec.yaml，再继续整理研究摘要、设计摘要和构建计划。 如果没有 primary_domain、coverage_status 或 open_gaps 的收口结果，不得进入下一步。 如果任务涉及视觉排版产物，还需要继续补齐 output_profile 与 design_md。
2. 阅读 atomic-capability/index.md，为关键能力选择可复用模块。
3. 阅读 presets/index.md 和当前主任务域预设，确认默认输出、风险门槛和执行面。
4. 阅读 utils/template/ 下的目标平台模板，明确输出骨架、元数据差异和脚本策略。
5. 调用 sub-skills/skill-creator/SKILL.md，把 spec 转成可执行的构建计划。
6. 如果任务适合比较验证，再阅读 utils/benchmark.md，只规划 benchmark 的进入条件、样本和判定标准。
7. 如果目标平台属于任意 supported_*，继续补平台安装、校验和发布边界；supported_public 可进入打包准备，supported_authoring_only 与 supported_local_only 只能停在作者规范或本地激活边界。
8. 条件满足时，先在 factory-skill-builder/ 执行 npm install，再使用 factory-skill-builder/scripts/build_skill_from_spec.cjs 生成最小 Skill 骨架，并用平台校验脚本确认结果；生成链要把模板选择结果一并写入产物。 如果 output_profile.has_visual_output 为真，生成链还要继续输出 references/design.md 与 references/design-md/。

建议在这一阶段保留的文档产物：

• spec.yaml
• brainstorming-notes.md
• research-summary.md
• reference-skill-analysis.md
• design-summary.md
• spec.md
• build-plan.md
• benchmark-plan.md（仅在进入 benchmark 时）
• platform-support-notes.md（平台声明有特殊边界时）

Step 6: Deliver

默认交付物包括：

• 一份收口后的统一 spec
• 一份设计决策摘要
• 一份构建计划或构建说明
• 外部依赖的接入说明
• 一份平台兼容与发布边界说明
• 按需生成的 benchmark 计划

如果用户只想得到设计方案，不想立即落地产物，可以在 spec 和设计决策确认后结束。

Fast Paths

用户已经带着参考 Skill 来了

先检测环境，再直接做差异分析：

1. 当前参考 Skill 覆盖了哪些能力
2. 哪些地方要保留
3. 哪些地方要替换
4. 哪些平台适配要重写

用户只想找现成 Skill

仍然要先补齐最小需求轮廓，再搜索。 不要在问题尚未收敛时直接把一串候选列表甩给用户。

用户只想做平台迁移

优先保留原 Skill 的目标、触发方式和能力边界，再聚焦模板映射、依赖表达和目录结构变化。

Local Resources

按下面的顺序读取资源，避免一次加载过多内容：

• ref/research.md 需求调研阶段的对话骨架、必填信息和阶段出口
• ref/design.md 方案展开、比较和收口方式
• ref/platform-support-matrix.md 子仓内的本地平台支持矩阵与声明边界
• factory-skill-builder/scripts/ factory 内部的 spec -> skill 渲染、平台校验与打包入口
• ref/construction.md 如何把统一 spec 收口为构建计划与产物边界
• sub-skills/brainstorm/SKILL.md 没有外部 brainstorming 时的兜底调研子 Skill
• sub-skills/skill-creator/SKILL.md 进入构建准备阶段时的规划子 Skill
• presets/index.md 任务域预设目录和对应问题包、执行面建议
• atomic-capability/index.md 原子能力索引与组合建议
• utils/template/spec-template.yaml 统一结构化协议模板
• utils/template/*.md 平台模板、结构差异和选择条件
• output/README.md output/ 目录契约和每类产物职责
• utils/cli/*.py 环境检测与搜索标准化
• utils/benchmark.md benchmark 进入条件与输出格式

Output Contract

产出构建计划或 Skill 方案文档时，至少检查这些项目：

1. SKILL.md 是否能独立说明触发场景、流程和资源读取顺序
2. 目标平台模板是否与最终目录结构一致
3. 外部依赖是否都有接入说明和降级路径
4. 当前阶段允许脚本化的动作是否已经覆盖环境检测、搜索、最小渲染与平台校验
5. molili 是否按独立平台处理，没有被并入 copaw
6. 是否已经明确目标平台对应的目录和元数据要求
7. benchmark 若被启用，是否明确了 0 skill 与目标 Skill 方案效果的比较对象

Boundaries

本 Skill 负责 spec 驱动、方案组织、参考检索和构建规划。 它不会把搜索命中当作唯一前提，也不会默认替用户跳过需求收口。

如果当前任务只适合出文档，不适合进入下一阶段实现，可以在说明原因后收口到文档阶段。