GuGuData Skills

面向 AI Agent 的工程化数据 Skills

每个公开 Skill 使用 SKILL.md 明确定义激活条件、必选输入、可执行流程、参数交接、输出契约、失败边界与可追溯的 API 参考。

Agent 可以先按业务目标发现能力,再按需加载完整说明,稳定选择、可靠执行、可验证交付。

接口调用仍以详情页的参数、响应、价格和开通状态为准;AppKey 只通过安全配置提供,不写入 Skill。

20个公开 Skills
SKILL.md标准入口文件
按需加载渐进式上下文
可追溯版本与来源清晰
标准结构

一个合格的 Skill,不只是一份提示词

GuGuData Skills 遵循 Agent Skills 开放规范:用轻量元数据完成发现,在命中业务场景后加载完整说明,只在确有需要时引用附加资源。

01

发现

Agent 先读取 namedescription,判断能力边界、适用场景和触发关键词。

02

激活

命中场景后再读取完整 SKILL.md,校验必选输入、调用顺序、参数来源和使用边界。

03

执行

按确定性流程调用公开 API,记录数据口径和来源;失败时停止猜测,并按恢复策略处理。

SKILL.md 公开标准示例
---
name: gaokao-admission-research
description: "当用户需要组合高考公开 API,完成院校、专业、分数线或录取概率分析时使用。"
compatibility: "需要访问 GuGuData HTTPS API;执行接口前需开通对应服务。"
metadata:
  author: "GuGuData"
  version: "1.0.0"
---

# 高考志愿与教育数据 Skill

## 何时使用
## 用户输入
## 推荐工作流
## 失败处理与恢复
## 数据校验与使用边界
scripts/可执行辅助脚本,可选
references/按需加载的参考资料,可选
assets/模板与输出资源,可选

当前公开 Skills 以自包含 SKILL.md 为主;只有存在真实复用价值时才增加可选目录,避免无效上下文和不必要复杂度。

Skill 目录

找到与业务目标匹配的 Skill

按业务场景、Skill 名称、标签或 API 能力检索;每个条目同时提供可读页面和原始 SKILL.md。

20 个公开 Skills

接口数量与开通状态以各 Skill 页面和接口详情页为准

工程化流程

从发现到生产使用的完整路径

每一步都应可审计、可回滚、可复用。Skill 负责业务执行说明,接口详情页负责准确的请求与响应契约。

01

发现 Skill

按业务目标匹配名称、描述与触发条件,避免把全部文档一次性塞入上下文。

02

校验输入

补齐必选参数、时间范围、地区口径和业务限制;信息不足时先询问。

03

执行流程

按固定步骤组合 API,明确上一步输出如何成为下一步输入。

04

处理失败

区分权限、限流、网络和服务异常;只对安全且幂等的请求重试。

05

验证输出

记录接口、条件、时间和数据口径;高风险场景保留权威来源与人工复核。

06

版本评审

在版本控制中评审变更,校验 frontmatter、链接、流程和兼容性后再发布。

本地规范校验 使用官方参考工具检查目录与 SKILL.md 基础格式。
skills-ref validate ./my-skill 查看校验工具
上线检查

进入生产前,至少检查这 8 项

规范校验只能确认基础结构;可靠的生产使用还需要输入、权限、失败恢复、输出和版本治理。

01命名与目录一致

name 使用小写字母、数字和连字符,并与 Skill 目录名一致。

02触发条件清晰

description 同时说明做什么、何时使用以及关键触发词。

03输入契约明确

参数名、类型、必选项、取值范围、默认值和来源均可确认。

04流程可复现

步骤顺序确定,参数交接清楚,外部依赖与前置条件可检查。

05引用按需加载

附加资料保持单层引用,避免深层跳转和重复文档占用上下文。

06凭据安全隔离

AppKey 不写入 Skill、代码仓库、URL、日志或对话正文。

07失败边界覆盖

权限、限流、网络、服务异常与数据缺失都有明确处理策略。

08校验与版本评审

格式校验通过,链接可访问,变更已进入版本控制并完成评审。

allowed-tools 仍属于实验性字段,是否生效取决于客户端实现,不应作为跨客户端权限保证。

常见问题

关于 Skill 标准与生产使用

这些 Skill 可以直接安装吗?

可以把对应的 SKILL.md 保存到客户端支持的 Skill 目录,并确保目录名与 frontmatter 中的 name 一致。不同 Agent 产品的目录位置、启用方式和兼容字段可能不同,请同时核对客户端文档。

SKILL.md 会包含 AppKey 吗?

不会。公开 Skill 只描述业务流程、参数关系与使用边界。AppKey 应通过环境变量、凭据管理系统或客户端安全配置注入,不应出现在 Skill、代码仓库、URL、日志或对话正文中。

scripts、references 和 assets 是必需的吗?

不是。SKILL.md 是必需入口,其余目录都是可选项。当前公开 Skills 以自包含文档为主,只有确定能提升复用性、可验证性或输出一致性时才增加附加资源。

如何确认 Skill 符合开放规范?

先检查 frontmatter 中的 namedescription,再使用官方 skills-ref validate 做基础校验。生产使用前还需人工评审触发条件、链接、输入输出、失败边界和客户端兼容性。

Skill 是否会替代接口文档或改变购买方式?

不会。Skill 负责业务组合、调用顺序和校验思路;接口详情页负责准确的请求参数、响应结构、价格和购买入口。现有单接口购买、订单和授权方式保持不变。

一个业务可以同时使用多个 Skill 吗?

可以。例如内容站运营可能同时使用网站增长、AI 内容、文档处理和资讯工具类 Skill。组合前应明确每个 Skill 的输入输出边界,避免重复调用和口径冲突。

Agent 在接口失败时应该怎么做?

先区分 AppKey 或权限错误、限流、网络异常、服务端错误和数据缺失。只对幂等请求采用有限次数重试;仍然失败时返回已确认信息、失败原因和待补证据,不得臆造结果。

结果可以直接用于高风险决策吗?

不建议。高考、金融、医疗、法律、公共安全等场景需要结合官方来源、业务规则和人工复核。Skill 会提示数据边界,但不能替代专业判断。

开始使用

先选一个真实业务目标,再把数据能力交给 Agent

从公开 Skill 开始,核对接口契约与权限;需要直接连接 AI 客户端时,也可以继续使用 GuGuData Remote MCP。