DexForce/EmbodiChain / .agents/skills/update-api-docs
update-api-docs
VerifiedGenerate 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| agents/openai.yaml | config | 228 B |
SKILL.md
View on GitHub---
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |