# Cloud API Recipe Authoring

Author or revise a cloud-api-operations recipe...

- Repository: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit (1153 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill cloud-api-recipe-authoring -g -a claude-code -y`
Codex: `npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill cloud-api-recipe-authoring -g -a codex -y`
Cursor: `npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill cloud-api-recipe-authoring -g -a cursor -y`
Gemini CLI: `npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill cloud-api-recipe-authoring -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add TencentCloudBase/CloudBase-AI-Toolkit`

## Description

Author or revise a cloud-api-operations recipe (config/source/skills/cloud-api-operations/references/recipes/). Encodes why the long tail of control-plane capabilities is deliberately NOT wrapped as MCP/CLI tools, the API-first admission test for whether a capability deserves a recipe, the negative and positive lists, the fixed recipe structure, the writing rules distilled from writing-for-agents, the user-facing copy red lines, and the product regeneration/verification pipeline. Also routes contributors (and their agents) to the contribution flow and the pre-PR self-test protocol in references/contributing.md. Use when adding a recipe, judging whether a scenario belongs in the recipe set, updating the recipes index, re-checking existing recipes against the admission test, or onboarding someone who wants to submit one.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Cloud API Recipe Authoring

目标：让**「AI 可以 100% 操作云开发」**可验证, , 每个高频管控面场景都有一篇能照着跑通的 recipe，且每篇都建立在**公开 API** 之上。

## When to use

- 新增一篇 recipe，或修改现有一篇
- 判断某个能力**该不该**进 recipe 集（准入）
- 更新 `config/source/skills/cloud-api-operations/references/recipes/README.md` 的目录表与状态列
- 复核已有 recipe 是否仍满足准入（Action 是否已公开、是否已被专用 MCP 工具覆盖）
- 有人（或他的 Agent）要提交一篇 recipe, , 把 `./references/contributing.md` 给他

## 为什么不全部封装进 MCP / CLI（分工原则）

产品排期里「对外开放 API」通常不优先，于是有一个固定落差：**控制台上了功能，AI 却操作不了**。因果链是单向的, , 没有公开 API，CLI / MCP 就无从封装，AI 只能用鼠标。

补齐落差有两条路，我们不走「全都封装」那条：

| 做法 | 代价 |
| --- | --- |
| 把能力都补成 API、再全部封装成工具 | 工具面持续膨胀：模型选错工具的概率上升，工具描述吃掉上下文预算，每个工具都要跟 API 变更一起维护 |
| **只封装核心，长尾走 recipe** | 要多维护一份文档，但工具面稳定，长尾能力照样能被 AI 操作 |

**核心能力已经封装过了**（`query*` / `manage*` 工具家族 + CLI），剩下的大量接口**不需要**封装。一个能力该去哪：

| 能力形态 | 归属 |
| --- | --- |
| 有公开 API + 高频核心 | 已在 MCP / CLI 工具里, , 直接用，不要另写 recipe |
| 有公开 API + 长尾（串联多 Action、有非平凡前置、有踩坑或回查义务） | **写 recipe**（本 skill） |
| 有公开 API + 单接口、读文档即可调 | 既不封装也不写 recipe, , agent 现场查索引 |
| **没有公开 API**（只在控制台可见） | 谁也封装不了, , **产品缺口**，推产品先开放 API；这里也没有 recipe 可写 |

最后一行是硬约束：**没有公开 API，能力对 AI 的可用性就是 0**，这不是「我们封装得不够」的问题。

## 准入：API first（硬门槛，先过这一关再动笔）

三条必须同时满足：

1. **有公开云 API**：目标 Action 已列入公开 API 概览 / 接口文档（`https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/api-reference.md` 或产品官方文档）。
2. **语言无关可调用**：云 API 直调 / 官方 SDK / CLI / MCP 任一条通路都行, , 但必须是**公开 API 的封装**，不能反过来「只有某个语言的 SDK 封装、没有公开 Action」。
3. **写操作能由使用者独立完成**：含签名、必要的前置查询与加解密。若关键步骤依赖客户端拿不到的内部配置，就不合格。

不满足时的处理：

- **不要**写进 `config/source/skills/`（那是对外发布面）
- 同时当**产品缺口**反馈：请官方把这些 Action 列入公开概览，或给出语言无关的调用路径
- 归档：维护者放 `specs/cloud-api-skill/pending-recipes/`（内部目录，不进版本控制），正文顶部写清「为什么未通过 + 解封条件」；外部贡献者不提 PR，按 `./references/contributing.md` 开 Issue 说明

踩过的实例见下文「反面 case」, , 驳回后不进公开集，也不要把归档内容抄回来。

## 负向清单（不该写 recipe）

- 读公开 API 概览 + 单个接口文档就能直接调的（单个 Action、参数可查、无需串联）→ 让 agent 走 `SKILL.md §1` 的发现流程现场查
- 已有专用 MCP 工具覆盖的（`query*` / `manage*` 家族）→ 路由到工具，不写文档
- 纯参数含义 / 概念说明 → 属于官方文档，路由过去
- 只对某个 SDK 语言成立的用法（除该 SDK 外没有语言无关通路）

## 正向清单（必须写 recipe）

The rest: https://github.com/TencentCloudBase/CloudBase-AI-Toolkit/blob/HEAD/skills/cloud-api-recipe-authoring/SKILL.md