Skip to content

DexForce/EmbodiChain / .agents/skills/update-api-docs

update-api-docs

Verified

Generate or update EmbodiChain Sphinx API documentation for public Python exports. Use when the API docs checker or CI reports missing __all__ exports, after adding or changing public APIs, or when asked to fill, generate, or synchronize API-reference pages and their descriptions.

FileKindSize
SKILL.mdskill md3.4 KB
agents/openai.yamlconfig228 B
---
name: update-api-docs
description: Generate or update EmbodiChain Sphinx API documentation for public Python exports. Use when the API docs checker or CI reports missing __all__ exports, after adding or changing public APIs, or when asked to fill, generate, or synchronize API-reference pages and their descriptions.
---

# Update API Docs

Generate useful API documentation for every public export reported by the
read-only checker. Treat static ``__all__`` declarations as the public API
contract and preserve existing hand-written documentation.

## Workflow

1. Run the checker in machine-readable mode:

   ```bash
   python docs/scripts/check_api_docs.py --format json
   ```

   Exit status 1 is expected when exports are missing. Read the JSON report; if
   ``missing_count`` is zero, report that the docs are aligned and stop.

2. Group missing entries by module. Read each reported source file and inspect
   the exported definition, signature, type annotations, and docstring. Locate
   existing API pages with:

   ```bash
   rg -n "automodule:: <module>|currentmodule:: <module>" docs/source/api_reference
   ```

3. Choose the documentation location:

   - Add the export to an existing curated module page when one exists. Follow
     that page's headings, autosummary groups, and detailed autodoc directives.
   - Document a package-level re-export under its public import path, not only
     under the implementation module.
   - If no suitable curated page exists, add or extend the module section in
     ``docs/source/api_reference/public_api.rst``. This file is an
     agent-maintained fallback, not checker output. Keep fallback module
     headings sorted by import path and entries in their declared ``__all__``
     order to minimize diff churn.

4. Write documentation that explains the API:

   - Add the export to the appropriate ``autosummary`` block.
   - Add the matching ``autoclass``, ``autofunction``, ``autodata``, or other
     detailed directive when the surrounding page provides detailed entries.
   - Add a concise section overview when names alone do not explain the group.
   - If the source docstring is missing or too vague for autodoc, improve it
     with a meaningful summary and Google-style ``Args``, ``Returns``, and
     ``Raises`` sections where applicable.
   - Derive descriptions from the implementation and tests. Do not invent
     behavior, examples, guarantees, or parameter semantics.

5. Keep the change scoped to documentation. Do not alter runtime behavior,
   signatures, or ``__all__`` merely to silence the checker. Do not replace
   curated prose with generic generated text or add placeholders such as
   "part of the public API."

6. Rerun the checker until it reports zero missing exports:

   ```bash
   python docs/scripts/check_api_docs.py
   ```

7. Run Black on every changed Python file, then validate the documentation
   workflow:

   ```bash
   pytest tests/docs/test_check_api_docs.py -q --confcutdir=tests/docs
   python -m sphinx -b dummy docs/source docs/build/api-docs-check
   ```

   When source docstrings were changed, also run focused tests for those
   modules. Fix new Sphinx warnings caused by the edit; distinguish them from
   unrelated pre-existing warnings.

## Completion Report

Report the documented import paths, the pages or docstrings updated, and the
validation results. If an export cannot be documented accurately from the
repository, identify the exact missing semantic information instead of
guessing.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall