메뉴
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 직업 분류 기준
| 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",
},
},
},
},
],
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.