企业官网建设流程全解析

SkillCorpus 是一个开源的 agent 技能语料库基础设施，它把散落在各仓库里的SKILL.md文件汇聚成经过安全、许可、质量审校的可检索技能库。本文聚焦它的线上服务 SkillHub 提供的三级检索 API：Discover（发现）、Read（读取）、Download（下载），带你用最低成本把精准的"技能"喂给 agent——前两级只拿元数据和正文，第三级才下载可执行脚本，大多数场景读第二级就够了。

🎯 为什么是"三级"：成本从低到高

绝大多数技能都是纯指令型（一份写好的SKILL.md），agent 只需要读它的内容，根本不需要下载文件。SkillHub 因此把接口按成本切成三级，逐级加深（详见 docs/integrations.md）：

其中{ref}既可以是 UUID 形式的id，也可以是原始的skill_id字符串，两个都认。

🔍 第一级：发现——最低成本拿到候选清单

curl "https://skillhub.evermind.ai/openapi/v1/skills?q=extract+tables+from+a+PDF"

这一步背后跑的是与开源仓库同款的双阶段检索：查询先被 bi-encoder 向量化做向量近似匹配（ANN）召回候选，再由 cross-encoder 重排序，端点直接返回头部命中，没有过滤参数、没有分页。

返回的result.items每条包含id、skill_id、name、description、source、category、quality_score、tags、license、download_url等字段——但不含正文，这正是它便宜的原因（docs/integrations.md）。

📖 第二级：读取——把skill_md正文注入 agent

GET /openapi/v1/skills/{ref}

在发现级字段之上，这一级新增的关键字段（docs/integrations.md）：

• skill_md：完整的SKILL.md正文，这就是你要注入 agent 提示词的东西；
• files：包内附带的相对路径列表；
• subscores：utility / robustness / safety三维子分（0–10），可用于二次筛选；
• safety_flags：审计标签，如["no_steps"]。

一个极简的"提示词注入"做法就是——把正文包进标签、拼到任务前面，这正是示例脚本 examples/skillhub_demo.py 中build_prompt()的全部工作：

blocks = "\n\n".join(f'<skill name="{s["name"]}">\n{s["skill_md"]}\n</skill>' for s in skills) prompt = f"You have been given the following skills…\n\n{blocks}\n\nTask: {task}"

任何能改系统提示词的 harness 都可以照抄这一招，不需要任何 SDK。

📦 第三级：下载——只为"可执行"技能取脚本

curl -o skill.zip "https://skillhub.evermind.ai/openapi/v1/skills/<id>/download?source=cli"

与前两级不同，下载端点返回的是原始 zip 字节（不套 JSON 包）。source参数可选，取值为raven/everme/cli/web之一，用于记录安装事件；其他值会被60002拒绝。

zip 内所有文件统一包在一个<skill-name>/目录下。⚠️解压时务必校验路径——不要盲信包内的相对路径，示例脚本对越界/绝对路径条目会直接跳过（examples/skillhub_demo.py）；官方插件客户端同样内置了单文件 8 MiB、总量 64 MiB 的防御性上限（skillcorpus_plugin/engine-python/skillsearch/hub_client.py）。

🚀 一个脚本跑通三级检索

不想手写请求？仓库自带 examples/skillhub_demo.py：纯标准库、无需安装依赖、无需 API key，一条命令走完"搜索 → 读正文 →（可选）下载 →（可选）交给 LLM 执行"。

git clone https://gitcode.com/gh_mirrors/sk/SkillCorpus && cd SkillCorpus # 搜索 + 读正文 python examples/skillhub_demo.py "extract tables from a scanned PDF invoice" # 把第一名技能的脚本包下载到 ./skills python examples/skillhub_demo.py --install ./skills "convert a PDF to images" # 检索并直接把任务喂给任意 OpenAI 兼容 LLM export OPENAI_API_KEY=... python examples/skillhub_demo.py --ask "extract tables from a scanned PDF invoice"

运行效果大致如下，可以看到三级是逐步深入的：

[1/2] search → 2 hit(s), metadata only 1. ocr-and-documents q=0.808 DOC-PROC MIT [2/2] detail → fetching skill_md for 2 skill(s) ocr-and-documents: 4916 chars u=8 r=7 s=9 files=4 → built a prompt of 36,742 chars with the skill bodies injected

🔀 两种"喂法"：提示词注入 vs skills 目录

• 提示词注入型 harness：直接用第二级的skill_md拼进系统提示词，跳过下载，是最轻量的方案；
• skills 目录型 harness（如 OpenClaw、Hermes 等）：用第三级把技能包下载进各家的技能目录即可，例如~/.claude/skills、~/.hermes/skills、~/.openclaw/workspace/skills。

官方插件层更进一步：在 docs/plugin-multi-source-retrieval-design.md 中可以看到，插件会并行搜索本地技能、SkillHub、ClawHub、skillhub.cn 四个来源，用加权 RRF 融合（只比较来源内排名，不跨平台比原始分数），再经过可选的 LLM gate 精选，最终只保留 0–2 条注入上下文——"宁缺毋滥"避免了提示词被无关技能灌水。

⚠️ 错误码、限流与健康检查速查

除/health和 zip 下载外，所有响应都套统一信封{"error", "requestId", "status", "result"}，status == 0表示成功，失败时result为null：

限流按 IP 计算：发现 + 读取合计120 次/分钟，下载30 次/分钟——这也侧面说明接口设计者在鼓励你"少下载、多读正文"。服务存活检查用GET /health。

✅ 小结

给 agent 喂技能的黄金路径只有三步：① 发现拿元数据 → ② 读取拿skill_md注入提示词 → ③ 仅在技能带可执行脚本时才下载 zip。记住三点就能用好这套 API：{ref}两种写法都行；status == 0才是成功；下载解压永远要校验路径。完整端点文档见 docs/integrations.md，语料字段契约见 docs/corpus-schema.md，想自己搭建语料库和检索模型则可参阅 README.md 的 "Build your own corpus" 与 "Self-host the models" 章节。