Say whether a task's documentation should use Markdown headings

[seebi]

The finding

The plugin-documentation skill says documentation is rendered as Markdown and
names what works - "backticks, **bold** and links" - then prescribes "Four
beats, in this order" without saying how those beats should be marked. The
enumeration omits headings and lists, and the model it points at renders as one
run of paragraphs, so the skill reads as a nudge toward unbroken prose without
ever deciding the question.

Generated projects have split on it: some mark the beats with ## headings and
write the caveats as a list, others keep prose throughout. Both are defensible
readings of the same skill, which is the problem - a user meets two different
documentation styles in one workspace, and every author re-decides it.

It matters most where it is least visible. A short block reads fine either way;
a block covering two output shapes, several caveats and a schema rule does not,
and that is exactly the block where an author is least likely to stop and
reconsider the markup.

Why this generalises

Any plugin whose documentation grows past roughly twenty lines faces it, and the
answer should come from the skill rather than from whichever sibling project the
author happened to read first.

Which part of the template

src/{{ '.claude' }}/skills/{% if project_type == 'plugin' %}plugin-documentation{% endif %}/SKILL.md

Suggested change

• Extend the "rendered as Markdown" sentence to name headings and lists, so the
  enumeration stops implying they are unavailable.
• Say when to reach for them: prose while the block is short, ## headings
  marking the beats once it is not, with heading names that follow the beats.
• Note that the caveats beat reads well as a list with the claim in bold at the
  front of each item.

Environment

Template version: v9.7.0
project_type: plugin
github_page answered: yes
pypi answered: yes (true)