piflow-skill-generator

name	piflow-skill-generator
description	PiFlow 技能生成器。当用户完成了一次完整并成功的数据处理任务时调用，根据当前 skills/generated 的本地约定和 references/piflow_skill_template.md 通用模板创建、更新或校验 PiFlow-compatible skill，包括 UTF-8 编码的 SKILL.md、DAG 可读的 input_params/output_params、version/tag 元数据、skill.json、scripts/references/assets 资源目录，以及本地校验脚本。仅在用户明确要求生成或保存 skill，或某次数据处理任务已经完成并需要把已验证成功的操作流程沉淀为 skill 时使用；默认不要因为“可能需要 skill”或“当前能力不足”而优先触发此 skill。
name_zh	PiFlow 算子生成器
version	1.1.2
allowed-tools	["process"]
input_params	[{"name":"spec_path","type":"string","required":false,"description":"技能规格 JSON 文件路径，必须使用 UTF-8 编码；与 flow_path 二选一"},{"name":"output_root","type":"string","required":false,"default":"skills/generated","description":"输出根目录；deepagent 虚拟文件环境默认写入 skills/generated（相对于 workspace 根）"},{"name":"overwrite","type":"bool","required":false,"default":false,"description":"是否覆盖已存在的技能目录"},{"name":"flow_path","type":"string","required":false,"description":"已验证成功的流程摘要 JSON 路径；与 spec_path 二选一"},{"name":"restored_spec_out","type":"string","required":false,"description":"使用 flow_path 时恢复出的 spec 草稿输出路径"},{"name":"rewrite_followup_hint","type":"string","required":false,"default":"","description":"可选提示语；当 skill 生成完成后，如用户随后给出新的流程，可提示是否进入生成器内部改写链路继续改写"}]
output_params	[{"name":"skill_dir","type":"directory","description":"生成后的技能目录"},{"name":"skill_md","type":"markdown_file","description":"生成后的 SKILL.md"},{"name":"rewrite_followup_suggestion","type":"json_file","description":"生成完成后的改写 follow-up 建议信息"}]
tag	AI处理
publisher	COMMUNITY

PiFlow Skill Generator

核心规则

除去对运行/测试时的产物进行分析，其他工作应尽量提前计划和生成，避免在安装或测试阶段才发现文档不完整、脚本缺失或资源错误。技能生成器的目标是一次性生成一个完整、可靠、符合约定的技能目录，能直接被 PiFlow 识别和使用，但它不是默认优先入口。

生成能被 PiFlow 理解的技能目录。所有文本文件必须以 UTF-8 读写，尤其是中文内容；Python 读写文件时显式使用 encoding="utf-8"，JSON 输出使用 ensure_ascii=False。

按库内技能的粒度控制内容：SKILL.md 只放触发、流程和必要契约；可执行逻辑放 scripts/；较长规则、字段说明和领域资料放 references/；模板、图标、示例素材放 assets/。

生成正文时优先参照 references/piflow_skill_template.md。当 spec 中提供 core_features、trigger_conditions、processing_logic、supported_formats、output_structure、output_examples 等字段时，将它们填入模板对应章节。

本技能必须能在没有其他技能辅助的环境中独立生成可靠技能：只依赖当前技能目录内的 SKILL.md、references/piflow_skill_template.md、references/rewrite_followup_internal.md、scripts/generate_piflow_skill.py、scripts/generate_skill_files.py、scripts/register_skill_artifacts.py、scripts/rewrite_piflow_skill.py 和 scripts/validate_piflow_skill.py。生成时不要假设另一个 skill 会补全文档、脚本或元数据。本技能负责 skill 化与沉淀，不负责代替用户完成所有真实处理任务本身。

本技能支持三条触发链路：

1. 手动生成链路 当用户明确要求“生成 skill”“保存为 skill”“封装为 skill”“创建自定义技能”时，直接进入 skill 生成阶段，行为与当前链路一致。

2. 回调式沉淀链路 当现有技能库无法直接满足需求时，应先在 skill 层面声明当前没有可直接复用的现成 skill，并优先引导大模型先帮助用户解决问题本身，例如生成脚本、处理流程、输入输出约定、验证步骤等。只有在这些处理流程已经跑通、结果已验证后，才回调进入本技能，并提示用户是否根据之前的成功操作流程将其封装为 skill。

3. 生成后改写链路 当一个 skill 已经生成完成并经过基础校验后，如果用户随后又提供了一个新的成功流程、更新后的脚本或更合理的输入输出设计，不要默认忽略这些新信息；应主动询问用户，是否要以这个新的流程为指引，对刚生成的 skill 做一次最小改写；若用户确认，则优先进入生成器内部改写链路，以“保留原 skill 名称 + overwrite 重建”的方式做最小改写，而不是要求用户重新生成一个同义的新 skill。

因此，本技能不是默认优先入口，但也不再只局限于“任务完全结束后人工另起一轮对话”；它可以作为缺 skill 场景下的回调式沉淀终点。

此外，本技能提供一个最小“生成后再改写”的后续触发路径：

• 当一个 skill 已经生成完成后，如果用户随后又给出了新的成功流程、新的输入输出约定或新的脚本实现，可以询问用户：
• “是否要以这次新的流程作为指引，对刚生成的 skill 再做一次改写？”
• 若用户同意，则应进入生成器内部改写链路，对刚生成的 skill 做最小重写，而不是要求用户重新生成一个同义的新 skill。
• 详细依赖与调用关系见 references/rewrite_followup_internal.md。

在涉及安装、环境准备或可执行脚本验证时，优先完成最小必要依赖，再运行一个简单冒烟测试确认关键入口可执行、基础参数可解析、输出路径可写。若安装或测试失败，允许自动重试，单个阶段最多重试 5 次；若 5 次后仍失败，停止流程并把失败原因、失败步骤和最后一次错误返回给用户。

安装依赖或配置前置环境时，若不明确安装的流程或操作，需要调用网络工具获取安装指南或官方文档，或者直接调用搜索查询安装步骤，不要假设已经知道如何安装或配置。

路径规则

deepagent 的虚拟文件环境以 workspace 为根。生成的技能必须放在 （相对于 workspace 根），这样 PiFlow 才能发现。