| name | document-package |
| description | Generate or update ROS 2 package documentation (README and API docs) by reading source code. Enforces the documentation verification workflow. |
Document Package
Usage
/document-package [<package-path>]
If no path is given, use the current directory.
Overview
Lifecycle position: Utility — use after audit-project flags documentation
gaps, or when asked to "document a package", "update the README", or "write
API docs".
Generates both user-facing package documentation (README with nodes, topics,
parameters) and developer-facing API documentation (class/function reference)
by reading the actual source code. Merges what were previously two separate
skills (ros-documentation and ros-code-documentation).
Cardinal rule: No fact without reading the source. Every parameter name,
topic name, message type, and default value must come from the code, not
assumptions. See .agent/knowledge/documentation_verification.md.
Steps
1. Inventory the package
cat <package_path>/package.xml
find <package_path> -name '*.py' -o -name '*.cpp' -o -name '*.hpp' -o -name '*.h' | sort
find <package_path> -name '*.msg' -o -name '*.srv' -o -name '*.action' | sort
find <package_path> -name '*.launch.py' -o -name '*.launch.xml' -o -name '*.launch.yaml' | sort
Record name, description, maintainer, license, and dependencies from
package.xml.
2. Extract facts from source
Follow the command cookbook in .agent/knowledge/documentation_verification.md
to grep for every:
- Parameter:
declare_parameter / declare_parameters
- Publisher:
create_publisher
- Subscriber:
create_subscription
- Service server/client:
create_service / create_client
- Action server/client:
rclcpp_action::create_server / create_client
Record each finding with its file path and line number.
3. Analyze launch files
Read every launch file. Note:
DeclareLaunchArgument entries (name, default, description)- Topic remappings
- Parameter overrides
- Node composition
4. Analyze API (libraries and modules)
For C++ libraries (headers in include/<package_name>/):
- Public class definitions
- Public methods and their signatures
- Type definitions (
struct, enum, typedef)
For Python modules (in <package_name>/ or src/<package_name>/):
- Class definitions and
__init__ signatures
- Public methods
- Module-level functions
5. Generate package README
Use the template at .agent/templates/package_documentation.md:
- Fill in each section from the facts gathered in steps 1–3.
- Omit sections that don't apply (no empty tables).
- If a README already exists, preserve custom sections (e.g., "Theory of
Operation") while standardizing the nodes/API/usage sections.
6. Generate API documentation (if applicable)
If the package contains libraries or modules with public APIs (not just
ROS nodes):
- Create
docs/API.md in the package root.
- Document each public class with its constructor, public methods, and
usage example.
- Include type definitions and enums.
Skip this step if the package only contains ROS node executables with no
reusable library code.
7. Self-review
Run through the verification checklist from
.agent/templates/package_documentation.md:
References
.agent/knowledge/documentation_verification.md — Verification workflow
and command cookbook.agent/templates/package_documentation.md — README template with
verification checklist
Guidelines
- Read before writing — complete steps 1–4 before generating any text.
- Omit, don't leave empty — if a package has no services, remove the
services section entirely.
- Preserve existing work — if a README exists, update rather than replace.
Keep custom sections that add value.
- One package at a time — don't batch across packages. Each package gets
its own focused documentation pass.
- Cite line numbers — when documenting a parameter or topic, note the
source file and line so reviewers can verify.
