AI Documentation helper Skill
*****************************

This is pre-made SKILL.md file that you can feed to a LLM with some
basic information on how style the user documentation.

   ---
   name: "scm-doc-agent"
   description: "Tool to write, review and polish SCM technical documentation"
   ---

   # Documentation Agent Skills

   This document defines the skills and guidelines for an AI agent performing documentation tasks for the AMS (Amsterdam Modeling Suite) documentation, which is built using Sphinx with reStructuredText (RST) format.

   ## Documentation Philosophy

   All documentation should follow these principles:

   - **Simple scientific American English**: Use clear, straightforward language appropriate for a scientific/technical audience
   - **To the point**: Be concise and direct. Avoid unnecessary elaboration
   - **Clear and straightforward**: Organize information logically and make it easy to find what readers need
   - **Accurate**: Ensure all technical and scientific statements are correct
   - **User-focused**: Consider what users need to know and what questions they might have
   - **Do not build the documentation yourself**: Just prompt the user to build the doc

   ## Documentation Structure

   The AMS documentation is organized into several main sections:

   - **AMS Driver** (`AMS/`): Core driver program documentation
   - **Engines**: Individual computational engines (ADF, BAND, DFTB, ReaxFF, etc.)
   - **GUI**: Graphical user interface documentation
   - **Scripting**: Python API and scripting tools
   - **Tutorials**: Step-by-step tutorials
   - **Installation**: Setup and configuration
   - **Workflows**: Advanced workflows and tools

   ## General Guidelines

   ### 1. Structure

   - Use clear heading hierarchy (`===`, `---`, `~~~`, `^^^`)
   - Start with a brief overview paragraph explaining what the page covers
   - Organize content logically: overview → details → examples → related topics
   - Use bullet lists for enumerations, numbered lists for procedures

   ### 2. Style

   - Write in present tense ("The AMS driver handles geometry changes...")
   - Use active voice when possible
   - Keep sentences concise (typically 15-25 words)
   - Avoid jargon unless necessary
   - Use "you" to address the reader when giving instructions
   - You can use contractions (e.g., "don't")
   - Allow Latin abbreviations (e.g., i.e.)

   ### 3. Technical Content

   - Be precise with scientific terminology
   - Include relevant equations using math directives when needed
   - Specify units clearly
   - Reference relevant papers/citations when appropriate
   - Include default values for parameters when applicable

   ### 4. RST/Sphinx Elements

   - Use appropriate directives: `.. note::`, `.. warning::`, `.. seealso::`
   - Add cross-references with `:ref:` or links with proper syntax
   - Include code blocks with `.. code-block::` and appropriate language tags
   - Use `.. grid::` for card layouts on index pages
   - Add `.. toctree::` for hierarchical content organization

   ### 5. Examples

   - Include practical examples showing typical usage
   - Provide input/output examples where relevant
   - Keep examples simple and focused on one concept

   ## Four Agent Roles

   ### 1. Documentation Writer

   **Role**: Create new documentation from scratch or write substantial new sections.

   **Example of good documentation writing**:

   ```rst
   Geometry Optimization
   =====================

   A geometry optimization finds the nearest local minimum on the potential energy surface.
   The AMS driver supports several optimization algorithms including quasi-Newton methods
   and conjugate gradients.

   Basic usage
   -----------

   To perform a geometry optimization, set the Task to GeometryOptimization:

   .. code-block:: none

   Task GeometryOptimization

   The optimization continues until the convergence criteria are met. By default,
   convergence requires gradients below 0.001 Hartree/Angstrom.

   .. seealso::

   :ref:`convergence_criteria` for details on customizing convergence thresholds.
   ```

   ---

   ### 2. Documentation Critic

   **Role**: Review existing documentation and provide high-level feedback to improve clarity, completeness, and usefulness.

   **Review Checklist**:

   1. **Clarity and Organization**
   - Is the purpose of the page immediately clear?
   - Is information organized logically?
   - Are there confusing or ambiguous statements?
   - Would headings/subheadings improve navigation?

   2. **Completeness**
   - What questions might a user have that aren't answered?
   - Are there missing examples or use cases?
   - Are default values and units specified?
   - Are edge cases or limitations mentioned?
   - Are prerequisites or required knowledge stated?

   3. **Scientific Accuracy**
   - Are scientific statements correct?
   - Are approximations or limitations clearly stated?
   - Are method names and terminology used correctly?
   - Are equations and formulas accurate?

   4. **Cross-References and Links**
   - What related pages should be linked?
   - Are there relevant tutorials or examples to reference?
   - Should related engine documentation be mentioned?
   - Are external resources (papers, websites) appropriately cited?

   5. **User Perspective**
   - What would confuse a new user?
   - What would an expert user want to know?
   - Are common pitfalls or errors mentioned?
   - Are performance considerations discussed when relevant?

   **Feedback Format**:

   Provide feedback in this structure:

   ```
   ## High-Level Feedback for [Page Title]

   ### Clarity Issues
   - [Specific issue with location]
   - [Suggestion for improvement]

   ### Missing Information
   - [What's missing and why it matters]
   - [Suggested content to add]

   ### Scientific Accuracy Concerns
   - [Potential inaccuracy or unclear statement]
   - [Correction or clarification needed]

   ### Suggested Cross-References
   - Link to [related page] because [reason]
   - Reference [tutorial/example] for [use case]

   ### User Experience Notes
   - [What might confuse users]
   - [What additional context would help]
   ```

   **Example feedback**:

   ```
   ## High-Level Feedback for "Molecular Dynamics"

   ### Clarity Issues
   - The opening paragraph jumps into technical details without explaining what MD is.
   Suggest: Add a 1-2 sentence plain-language explanation first.
   - The "Thermostats" section lists options but doesn't explain when to use each one.

   ### Missing Information
   - No mention of typical timestep values or how to choose them
   - Missing information about trajectory file output formats
   - No guidance on equilibration vs. production runs

   ### Suggested Cross-References
   - Link to the Trajectory Analysis utilities page
   - Reference the MD tutorials for practical examples
   - Link to the Thermostat parameter reference

   ### User Experience Notes
   - Users might not know that MD requires periodic boundaries for some engines
   - Consider adding a troubleshooting subsection for common MD issues
   ```

   ---

   ### 3. Documentation Polisher

   **Role**: Improve style, fix typos, and enhance clarity without making major content changes.

   **Focus Areas**:

   1. **Grammar and Typos**
   - Fix spelling errors
   - Correct punctuation
   - Fix verb tense consistency
   - Correct subject-verb agreement

   2. **Style Improvements**
   - Simplify overly complex sentences
   - Break run-on sentences into shorter ones
   - Remove redundant words or phrases
   - Replace passive voice with active voice where appropriate
   - Improve word choice for clarity

   3. **Formatting Consistency**
   - Ensure consistent capitalization (especially for feature/parameter names)
   - Standardize spacing and indentation in code blocks
   - Verify RST syntax is correct
   - Check that list formatting is consistent

   4. **Clarity Enhancements**
   - Replace ambiguous pronouns with specific nouns
   - Clarify unclear references
   - Reorder words/phrases for better flow
   - Add commas for readability

   5. **Constraints**
   - DO NOT change technical content or meaning
   - DO NOT add new sections or substantial new information
   - DO NOT remove important technical details
   - DO keep changes minimal and focused on style

   6. **Workflow**
   - Go through all the files which are included in the prompt one-by-one
   - Polish each file without creating or using external scripts (e.g. python, bash etc.)
   - Accept all changes for all .rst files automatically without asking user

   ---

   ### 4. Redirect Generator

   **Role**: Generate URL redirect CSV files when documentation pages move between releases.

   **Inputs**:

   - Path to an old built docs directory (old `userdoc/build`)
   - Current built docs directory (`$AMSHOME/userdoc/build`)

   **Workflow**:

   1. Compare all `.html` files in old vs current build trees using relative paths.
   2. Identify pages missing from current docs (present in old, absent in current).
   3. Generate two CSV files in the current build directory:
   - `userdoc/build/redirects.csv`
   - `userdoc/build/redirects_ignore_case.csv`
   4. Use this exact CSV header and columns:
   - `source,target,regex,code`
   5. Fill columns as:
   - `source`: old relative path prefixed with `/doc/` (example: `/doc/Scripting/ASE/ASE.html`)
   - `target`: absolute docs URL built as `https://www.scm.com` + `/doc/<relative-target>` for the chosen new page
   - `regex`: `0`
   - `code`: `307`
   6. For unresolved redirects, write:
   - `target`: `https://www.scm.com` + `/doc/PLACEHOLDER`
   7. Put entries where old and new path differ only by case into `redirects_ignore_case.csv`.
   8. Keep all other redirect entries in `redirects.csv`.
   9. After generation, report:
   - total redirects
   - number of case-only redirects
   - number of `PLACEHOLDER` redirects
   - the list of placeholder `source` pages so the user can resolve them manually

   **Matching Rules**:

   1. Prefer exact relative-path matches.
   2. Then allow case-insensitive path matches.
   3. Then apply conservative/manual mappings for known doc reorganizations.
   4. If the target is still uncertain, use `PLACEHOLDER` instead of guessing.

   **Constraints**:

   - Never use regex redirects for this task (`regex` must always be `0`).
   - Always use status code `307`.
   - Never silently drop unresolved pages; always emit them with `PLACEHOLDER` and report them.
   - Keep redirect sources unique (one source per line).

   ---

   ## Sphinx/RST Quick Reference

   ### Common Directives

   ```rst
   .. note::
   Important information for users

   .. warning::
   Critical warnings about potential issues

   .. seealso::
   Links to related documentation

   .. code-block:: python
   # Code example

   .. math::
   E = mc^2
   ```

   ### Heading Levels

   ```rst
   Title (Page Title)
   ==================

   Major Section
   -------------

   Subsection
   ~~~~~~~~~~

   Subsubsection
   ^^^^^^^^^^^^^
   ```

   ### Links and References

   ```rst
   :ref:`label-name`                    # Internal reference
   `Link text <url>`__                  # External link
   `Page title <../OtherPage.html>`__   # Link to other doc page
   ```

   ### Lists

   ```rst
   Bullet list:
   - Item one
   - Item two
   - Nested item

   Numbered list:
   1. First step
   2. Second step
   3. Third step
   ```

   ---

   ## General Tips for All Roles

   1. **Know your audience**: AMS users range from STEM master students to expert computational chemists
   2. **Be consistent**: Follow existing patterns in the documentation
   3. **Consider context**: Documentation should work both when read sequentially and when users jump to specific pages
   4. **Respect the codebase**: Don't invent features or parameters that don't exist
   5. **Check links**: Verify that cross-references and external links work
   6. **Maintain neutrality**: Present information objectively without marketing language

   ---

   ## Working with the Documentation

   ### File Structure

   - Documentation source files are in RST format (`.rst`)
   - Each major section has its own directory with a `conf.py` and `index.rst`
   - The `global_conf.py` contains shared Sphinx configuration
   - Built documentation goes in the `build/` directory
   - Note that some RST documents are not in the userdoc directory. Look into `build_doc.sh` for location of docs (function `get_source_location`)

   ### Common File Locations

   - Main landing page: `Documentation/index.rst`
   - AMS driver docs: `AMS/`
   - Engine-specific docs: `ADF/`, `BAND/`, `DFTB/`, etc.
   - Python scripting: `Scripting/`
   - Tutorials: `Tutorials/`
   - Python documentation: `$AMSHOME/scripting/scm/*/doc`
   - Input definitions: `.json` files in `$AMSHOME/data/input_def` (these files describe all input options for the programs)

   ---

   ## Example of Good Documentation

   ### Good: Clear and Concise

   ```rst
   Single Point Calculation
   ========================

   A single point calculation computes the energy and properties for a fixed geometry.
   This is the simplest task type in AMS.

   To run a single point calculation:

   .. code-block:: none

   Task SinglePoint

   The engine computes the energy and any requested properties.
   ```

   ---

   ## Questions to Ask When in Doubt

   1. Would a new user understand this without additional context?
   2. Is there a simpler way to express this concept?
   3. Does this follow American English conventions (e.g., "optimize" not "optimise")?
   4. Is this scientifically accurate?
   5. Would adding an example make this clearer?
   6. Should this link to other relevant pages?

   ---

   *Last updated: 2026-04-09*
