一键导入
update-api-docs
Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
菜单
Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Write PR titles and descriptions the way a staff engineer would. Use when drafting or editing a pull request title and body, before running `gh pr create`, or any time the user asks for a PR description, summary, or release-notes-style writeup of a change. Apply this skill from the start, not as a cleanup pass after a generic first draft.
Use this skill to create and publish changelog announcements for new features, improvements, or bug fixes. This skill handles the complete workflow - creating detailed changelog documentation pages, adding sidebar announcement cards, and ensuring everything follows project standards. Use when the user mentions adding changelog entries, documenting new features, creating release notes, or announcing product updates.
Where to put frontend code (package vs app layer) and how to use the @agenta/* packages. Use when authoring or moving code in web/packages, choosing between @agenta/ui, @agenta/entities, @agenta/entity-ui, @agenta/shared, @agenta/playground, using molecules, loadable/runnable bridges, the EntityPicker, or writing package unit tests.
Use when writing or editing documentation pages (concept pages, how-to guides, API reference prose, tutorials) under docs/. Provides the writing style, voice, and structural rules for Agenta docs. Apply this skill before drafting any new docs page, and include it in the brief for any subagent tasked with writing docs.
Audit and update the supported LLM model list in assets.py against litellm's registry (models.litellm.ai). Use when adding new models, pruning outdated ones, or verifying the list is correct.
Sync the findings record against local review artifacts and optionally a GitHub PR. Accept optional `path` and GitHub PR `url`; when `url` is provided, sync against both remote PR state and local state, otherwise default to local-only sync. Default to `path=infer`. Confirm effective variables before starting.
| name | update-api-docs |
| description | Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs |
This skill guides you through updating the API reference documentation from the production OpenAPI specification.
The API documentation is generated from an OpenAPI spec using docusaurus-plugin-openapi-docs. The workflow involves:
openapi.json from production| Purpose | Path |
|---|---|
| OpenAPI spec (source) | docs/docs/reference/openapi.json |
| Generated API docs | docs/docs/reference/api/*.api.mdx |
| Generated sidebar | docs/docs/reference/api/sidebar.ts |
| Docusaurus config | docs/docusaurus.config.ts |
The wrapper script at docs/scripts/update-api-docs.sh downloads the OpenAPI
spec, replaces the local file, and regenerates the docs in one step.
cd docs
# Default — fetch from production (live cloud API)
pnpm update-api-docs
# Explicit live cloud API
pnpm update-api-docs:live
# From a locally running API (http://localhost/api/openapi.json)
pnpm update-api-docs:local
# From an explicit local file
pnpm update-api-docs:file /path/to/openapi.json
The script writes the spec to docs/docs/reference/openapi.json and then
runs npm run clean-api-docs -- agenta followed by
npm run gen-api-docs -- agenta. The agenta argument refers to the OpenAPI
config ID defined in docusaurus.config.ts.
If this is a fresh clone or dependencies haven't been installed:
cd docs
npm install
This generates:
.api.mdx files for each endpoint.tag.mdx files for API categoriessidebar.ts for navigationOptionally, start the dev server to preview:
cd docs
npm run start
Then visit http://localhost:5000/docs/reference/api to verify the API docs render correctly.
When committing these changes:
First commit - API docs update:
docs(api): update OpenAPI spec from production
Include all changed files:
docs/docs/reference/openapi.jsondocs/docs/reference/api/*.api.mdxdocs/docs/reference/api/*.tag.mdxdocs/docs/reference/api/sidebar.tsThe clean and generate commands require the config ID. Use:
npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta
Run npm install in the docs/ directory first.
This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.
The OpenAPI plugin is configured in docs/docusaurus.config.ts:
[
"docusaurus-plugin-openapi-docs",
{
id: "openapi",
docsPluginId: "classic",
config: {
agenta: {
specPath: "docs/reference/openapi.json",
outputDir: "docs/reference/api",
downloadUrl: "https://raw.githubusercontent.com/Agenta-AI/agenta/refs/heads/main/docs/docs/reference/openapi.json",
sidebarOptions: {
groupPathsBy: "tag",
categoryLinkSource: "tag",
},
},
},
},
],