CoolSkill Builder

将任意资源转化为标准化、零依赖、跨生态兼容的 Skill 模块。

核心原则

1. 零依赖：impl.py 仅使用 Python 标准库白名单模块（详见 references/spec.md）
2. 极致省 Token：内部变量 1-2 字符，零注释，短路求值，列表推导优先
3. 版本隔离：每个 Skill 全局唯一 ID {domain}-{func}-{rand3}，Semver 递增，历史版本只读
4. 跨生态兼容：manifest.json 声明 OpenAI Function / Claude Tool / HTTP 三种调用格式

6 步工作流

收到资源后，严格按以下顺序执行：

Step 1: 解析资源

提取以下信息，整理为结构化需求：

如果用户提供的是：

• 自然语言描述 → 自行推导输入输出 schema，必要时反问确认
• 代码片段 → 提取函数签名、参数、返回值，转化为 run() 接口
• API 文档 → 将 endpoint 映射为 run() 入参，response 映射为返回值
• GitHub 仓库 → 提取核心逻辑，重写为标准库实现

Step 2: 生成 4 文件

基于解析结果，生成以下文件。详细模板见 references/file-templates.md。

skill.yaml（元数据）

• 键名压缩：v 替代 version, d 替代 description, src 替代 source, pf 替代 platforms, props.dom 替代 domain, props.st 替代 status
• meta.id 使用 scripts/generate_skill_id.py 生成，或按 {domain}-{func}-{rand3} 规则
• meta.src 标记来源：github|registry|custom|api
• schema.in / schema.out 为 JSON Schema 格式
• perms 按需声明：net（网络）、fs（文件系统）、env（环境变量）、exec（执行命令）

impl.py（零依赖实现）

• 固定签名：def run(a): 其中 a 为 dict
• 固定返回：{'s': 'ok|err', 'd': result, 'e': error_string}
• 导入行只保留实际使用的模块
• 内部变量/函数 1-2 字符（_e=raise, _j=json.dumps, _p=json.loads, _h=hash, _t=time, _u=url, _f=file, _s=string, _m=math）
• 零类型提示、零文档字符串、零注释
• 统一单引号；分号连接相关语句；列表推导替代 for
• 字典访问用 d['k']，除非需要默认值才用 .get()
• 错误处理：try/except 包围全部逻辑，r['s']='err';r['e']=str(x)
• 禁止 if __name__=='__main__' 之外的任何 I/O（测试/调试代码除外）

test.py（隔离测试）

• 首行：sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
• 从 impl import run，禁止相对导入其他 Skill
• 测试类 T 提供 a()（断言）、r()（运行并断言）、x()（汇总退出）
• 用例覆盖：t1 正常输入、t2 必填缺失、t3 类型错误、t4 边界值、t5 异常恢复
• 性能测试可选：检查运行时间是否超过阈值

manifest.json（跨生态适配）

• universal: entry=run, input=dict, output=dict
• openai_function: name/description/parameters/strict=true
• claude_tool: name/description/input_schema
• http_api: POST /skill/{skill-id}, headers 含 X-Skill-Version

Step 3: 5 层安全校验

运行 scripts/security_scan.py 执行自动扫描。任一失败则阻断，仅输出修复指令，不写入 Registry。

手工复核要点：

详细规则见 references/security-rules.md。

阻断后行为：

1. 输出失败层级和具体问题
2. 给出修复指令（原生代码重写/安全等价实现/参数化/脱敏）
3. 返回 Step 2 重新生成
4. 不执行 Step 4-6

Step 4: 原生测试

在隔离进程中执行 test.py：

cd registry/{skill-id}/{version} && python test.py

• 失败则阻断，返回修复指令
• 通过标准：ALL_OK 输出，F=0
• 测试进程必须独立，不加载其他 Skill 模块

Step 5: 版本隔离注册

生成/获取 Skill ID

首次生成：

• 运行 python scripts/generate_skill_id.py {domain} {func}
• 或按 {domain}-{func}-{rand3} 规则自行生成

迭代生成：

• 读取 registry/index.json 找到该 ID 的最新版本
• 按规则递增：修复→Patch+1, 功能变更→Minor+1, 破坏性重构→Major+1

写入 Registry

registry/
├── index.json
└── {skill-id}/
    └── v{version}/
        ├── skill.yaml
        ├── impl.py
        ├── test.py
        └── manifest.json

更新 index.json：

• 添加/更新该 skill-id 的 versions 记录
• 更新 latest 指向
• 时间戳使用 ISO8601 格式

详细格式见 references/registry-format.md。

Step 6: GitHub 同步（可选）

检测环境变量：

• GITHUB_TOKEN: GitHub Personal Access Token
• GITHUB_REPO: 格式 owner/repo

若缺失：输出 [CONFIG REQUIRED] 提示，继续本地注册。

若存在：使用 urllib.request + base64 + json 推送 4 文件到 skills/{skill-id}/{version}/。

同步代码模板（零依赖）：

import urllib.request,json,os,base64
GH='https://api.github.com'
G=os.environ.get('GITHUB_TOKEN')
R=os.environ.get('GITHUB_REPO')

输出报告格式

所有 Skill 生成完成后，输出以下报告：

=== SKILL REPORT ===
ID: {skill_id}
Name: {name}
Version: {version}
Domain: {dom}

--- skill.yaml ---
{yaml}

--- impl.py ---
{code}

--- test.py ---
{code}

--- manifest.json ---
{json}

--- SECURITY ---
L1: PASS/FAIL {detail}
L2: PASS/FAIL {detail}
L3: PASS/FAIL {detail}
L4: PASS/FAIL {detail}
L5: PASS/FAIL {detail}

--- TEST ---
P {pass} F {fail}
{case list}

--- REGISTRY ---
Local: registry/{skill_id}/{version}/ (isolated)
Latest: {version}
History: [v1.0.0, v1.0.1, ...]

--- CROSS-PLATFORM CALL ---
Kimi: import ...
OpenAI: function name={skill_name}
Claude: tool name={skill_name}
HTTP: POST /skill/{skill_id}

--- GITHUB ---
Status: PUSHED_or_SKIP
URL: {commit_url_or_none}
=== END ===

内部工具

参考文档

关键约束速查

• 导入白名单：仅 sys,json,os,re,math,random,datetime,itertools,collections,typing,inspect,hashlib,base64,urllib.request,http.client,socket,ssl,time,uuid,string,warnings,traceback,io,csv,html.parser,pathlib,fnmatch,glob,copy,functools,enum,dataclasses,contextlib,builtins
• 固定签名：def run(a): → {'s':'ok|err','d':result,'e':error}
• 版本格式：Semver {major}.{minor}.{patch}，历史版本只读
• Skill ID：{domain}-{func}-{rand3}，全局唯一，生成后固定
• 阻断规则：L1-L5 任一失败、test.py 失败 → 阻断，不写入 Registry
• 生态兼容：必须输出 manifest.json（OpenAI/Claude/HTTP 三种格式）