qclaw自定义技能开发需严格遵循五步规范：一、标准目录结构（含skill.yaml、main.py等5文件）；二、skill.yaml配置（含name、description、input/output schema）；三、main.py执行逻辑（run函数签名、i/o限制、返回格式）；四、依赖管理（requirements.txt精确版本、禁止非pypi源）；五、本地vetting验证（qclaw-vet与qclaw-run测试）。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望为 QClaw 构建自定义技能，但尚未掌握其开发规范与插件机制，则可能是由于对 skill.yaml 结构、main.py 执行契约或依赖注入方式理解不足。以下是完成技能开发与机制解析的系统性步骤：
一、理解 Skill 的标准目录结构
QClaw 技能必须遵循统一的文件组织规范，该结构是技能被识别、校验和加载的前提。缺失任一关键文件将导致 skill-vetter 审查失败或运行时 ImportError。
1、创建根目录，命名为符合 Python 包命名规则的技能名（如 pdf_to_word）。
2、在根目录下新建 skill.yaml 文件，用于声明元信息与接口契约。
3、添加 main.py 文件，作为技能唯一可执行入口，必须包含 run() 函数且接收 dict 类型 input 参数。
4、编写 requirements.txt，仅列出 runtime 依赖项（禁止包含 torch、tensorflow 等大体积库，除非确需）。
5、提供 README.md，至少包含“用途”“输入示例”“输出说明”三部分。
二、编写 skill.yaml 配置文件
skill.yaml 是 QClaw 调度器匹配用户指令的核心依据，其 description 字段参与语义向量检索，input/output 定义决定参数自动注入是否成功。
1、使用 UTF-8 编码保存文件，禁止 BOM 头。
2、name 字段须为 ASCII 字符，长度不超过 32 位，不得含空格或特殊符号。
3、description 字段应包含不少于 20 字的自然语言描述，并嵌入至少两个典型触发词，例如：“将 PDF 文档转换为可编辑 Word 格式”。
4、input 字段中每个参数需明确 type（string / number / boolean / array / object）、required（true / false）及 example 值。
5、output 字段必须指定 schema，且顶层字段名与 main.py 中 return 字典的键严格一致。
三、实现 main.py 的执行逻辑
main.py 是技能的实际执行单元，QClaw 在调用时会以子进程方式启动该脚本，并通过标准输入传入 JSON 格式的 input 数据。run() 函数返回值将被序列化为 JSON 并传递给后续流程。
1、在文件顶部添加标准 shebang 行：#!/usr/bin/env python3。
2、定义 def run(input: dict) -> dict: 函数，禁止修改函数签名或添加额外参数。
商业LOGO设计技能：依据用户描述，使用阿里云百炼千问图像模型(qwen‑image‑2.0‑pro)生成专业商业LOGO图片。适用场景：设计公司/品牌LOGO、生成商业标识图标、创建品牌视觉符号、按描述生成logo图片。支持自定义尺寸、风格、负面提示词等。
3、所有 I/O 操作必须限定在 input 中指定的路径范围内，禁止硬编码绝对路径。
4、若需调用外部命令，必须使用 subprocess.run(..., timeout=30, check=True)，并捕获 CalledProcessError。
5、成功时返回包含 status: "success" 和 result 键的字典；失败时返回 status: "error" 与 message 键，message 值不可为空字符串或纯空格。
四、配置依赖与环境隔离
QClaw 使用 PEP 517 兼容的构建后端为每个技能创建独立虚拟环境，requirements.txt 的内容直接影响环境初始化成败及安全扫描结果。
1、仅允许指定 PyPI 上公开可索引的包名与精确版本号，格式为 package_name==1.2.3。
2、禁止使用 git+https:// 或 file:// 等非 PyPI 源地址。
3、若依赖 C 扩展，须在 comments 中注明 # [requires-binary: true]，否则 skill-vetter 将拒绝安装。
4、所有包必须满足 manylinux2014 兼容性要求，macOS 用户需额外验证 arm64/x86_64 双架构支持。
5、requests 库默认已预装，不得重复声明；openai、qwen、dashscope 等模型 SDK 需显式声明版本。
五、本地调试与 vetting 流程验证
在提交至 SkillHub 前，必须通过本地 vetting 工具链验证技能合规性，避免因元数据错误或执行异常被市场自动拒收。
1、确保已安装 qclaw-devkit：pip install qclaw-devkit==0.9.7。
2、进入技能根目录，执行 qclaw-vet --strict，检查 skill.yaml 语法、路径合法性及依赖可解析性。
3、运行 qclaw-run --input '{"src_path": "/test/sample.pdf", "dst_path": "/test/out.docx"}'，观察 stdout 是否输出合法 JSON。
4、手动触发一次失败场景（如传入不存在的 src_path），确认 error 状态返回且 message 字段含具体原因。
5、vetting 输出中出现 [CRITICAL] 或 [BLOCKER] 级别提示时，必须修复后重新运行，不可跳过。
