Description Review Skill

Introduction

The Description Guidelines define how description and comment fields shall be written. To make it easy to follow them, the repository contains an agent skill named vss-description-review in .github/skills/vss-description-review/. The skill lets an AI coding assistant check and fix descriptions in *.vspec files.

Contributions that add or change descriptions shall follow the Description Guidelines. Using the skill is the recommended way to check this before submitting. Contributions that do not follow the guidelines may be rejected.

What the skill does and does not do

The skill does one thing: it reviews descriptions in your working tree.

  • It rewrites description and comment fields that do not comply with the guidelines.
  • It adds a # Human check of description required: <reason> comment above entries that are too vague to fix without guessing, so that a person familiar with the signal can decide.
  • It reports what it changed and which entries were flagged.

The skill never creates branches, commits, pushes, or opens or comments on pull requests. You review the resulting changes and decide what to commit and submit, as described in CONTRIBUTING.md.

Getting started

Prerequisites

  • An AI coding assistant that supports agent skills, for example GitHub Copilot in agent mode in VS Code. Skills in .github/skills/ are discovered automatically.
  • uv, which runs the helper script of the skill and installs its dependency (PyYAML) automatically.
  • To verify your changes: vss-tools, see BUILD.md. Create a Python virtual environment and run scripts/install_vss_tools.sh.

Run a review

  1. Create a branch and make your changes to the *.vspec files as usual.
  2. Open the repository in your editor and start a chat with the assistant in agent mode.
  3. Ask it to use the skill, for example:
    • Review the descriptions of the changed *.vspec files in my branch with the vss-description-review skill.
    • Review the descriptions in spec/Cabin/SingleDoor.vspec with the vss-description-review skill.
    • Audit the descriptions of Vehicle.Cabin.Door with the vss-description-review skill.
  4. If the scope is unclear, for example a request for the whole catalog, the assistant asks you before it starts.

Check the result

  1. Inspect the changes, for example with git diff. The skill only edits description and comment text.
  2. Resolve every # Human check of description required comment: clarify the description yourself or ask someone who knows the signal, then remove the comment.
  3. Verify the result before submitting, as for any other change (see BUILD.md):
    • make mandatory_targets
    • pre-commit run --all-files
  4. Commit with sign-off (git commit -s) and open the pull request yourself.

How it works

The assistant runs .github/skills/vss-description-review/scripts/vspec_desc_tool.py:

  • scan extracts every entry with its description, comment, parent branch and mechanically detectable problems (for example boolean casing or instance names in a description). The assistant reasons over this output.
  • apply writes the agreed edits into the *.vspec files and changes nothing else in the file.

The tool does not use git or network access. The full workflow is described in SKILL.md.

Limitations

  • The result is generated by an AI model. Always review it; the model is instructed to flag entries it cannot fix without guessing, but it can still be wrong.
  • The skill checks descriptions only. Datatypes, units, allowed values, and node names are never changed.