| name | document |
| description | Generate narrative documentation for computational models and research
software, and select the appropriate documentation framework for a given
model type.
Use this skill when a user wants to:
- document a computational model
- generate documentation from source code
- write an ODD or ODD+2 narrative for an agent-based model
- create model narratives for publication or reuse
- draft narrative workflow documentation
The skill classifies the model type, selects a framework, extracts model
structure from supplied materials, and drafts documentation. It does not
assess or score existing documentation — use the document-review skill for
completeness assessment, gap analysis, or structured review output. For
model-card requests or scientific model specifications, route to omfa.
Inputs may include source code, pseudocode, READMEs, publications,
architecture descriptions, or model metadata.
|
| license | MIT |
| compatibility | Any computational modeling framework or programming language |
| metadata | {"domain":"computational-modeling","category":"documentation","audience":["researchers","modelers","educators","research software engineers"]} |
| maturity | alpha |
Document Skill
Generate narrative documentation for computational models and research software, from source code, pseudocode, publications, or other supplied materials.
The goal is accurate, reusable documentation that describes the model as implemented — not as it was intended or remembered to work.
Core Principles
Documentation must faithfully represent supplied materials, distinguish evidence from inference, and remain consistent with implementation. Prioritize clarity over completeness, and reproducibility over polish.
Never invent entities, parameters, algorithms, equations, workflows, datasets, assumptions, or results. If information is unavailable, mark it Unknown, identify what's missing, and recommend clarification rather than filling the gap.
When generating documentation:
- document the selected framework and why it was chosen
- identify inferred information separately from information observed directly in the source materials
- preserve traceability: a reader should be able to tell which source artifact supports which claim
When To Use / Do Not Use
Use this skill to generate or draft narrative documentation: new narratives, ODD/ODD+2 write-ups, structured model narratives, workflow descriptions, or improvements to existing prose.
This skill is commonly invoked downstream of omfa, which owns lifecycle guidance and required structured artifacts; document owns substantive narrative generation according to the OMF rubric. When invoked this way, use the model type, lifecycle stage, and target audience omfa provides rather than re-deriving them independently (see Workflow step 2 below).
If the request is for artifacts/model-card.md, a model card, or any other scientific model specification, route to omfa instead of drafting it here.
Do not use this skill for documentation review or assessment — gap analysis, completeness scoring, or structured critique of existing docs belongs to the document-review skill, which is intended to share this skill's references/ODD-CHECKLIST.md and references/ODD-METHODOLOGY.md but does not rewrite prose.
Also out of scope: model calibration, sensitivity analysis, statistical analysis, software testing, code generation, peer review, FAIR assessment, and metadata validation.
Do not draft omfa's required lifecycle artifacts — artifacts/model-card.md, artifacts/abm-spec.md, or any other file directly under the artifacts/ root. These are template-driven and owned by the omfa skill even when high prose quality is requested, and even though ODD+2 (this skill's default ABM framework) covers similar ground to abm-spec.md. If a user asks for one of these artifacts by name, or asks for a scientific model specification, defer to omfa rather than drafting it directly.
