Use semantic line breaks in skills

[ppkarwasz]

What should happen

Apache Magpie should use semantic line breaks (https://sembr.org) to make changes in the skills easier to review.

Why

Most programming language styles use one statement per line. Since Magpie is a written in a new programming language called “English”, it should probably adhere to the same convention.

Semantic line breaks (https://sembr.org) allow to make single sentence changes without rewrapping the entire paragraph.

Which layer

Other / unsure

Boundary conditions (optional)

No response

Out of scope (optional)

No response

References (optional)

No response

[onlyarnav]

Hey, I took a stab at this using Claude Code, it made changes to these 4 files to establish SemBr as the convention going forward:

AGENTS.md

added a rule under "Writing and editing documentation" requiring semantic line breaks

docs/editorial-guidelines.md

added a full section on SemBr with the rules (one sentence per line, break at clause boundaries, no arbitrary hard-wrap)

CONTRIBUTING.md

tied it into the "English as code" rationale

skills/write-skill/SKILL.md

added SemBr to the skill authoring guidelines

But, there are 70+ existing SKILL.md files under skills/ that are still in the old format.
Was the intent to reformat all of those too?
That would be a big diff and would basically reset git blame on every skill file, but it'd make the whole repo consistent in one shot.

Please let me know if you'd prefer the full reformat or if gradual adoption is fine

[ppkarwasz]

But, there are 70+ existing SKILL.md files under skills/ that are still in the old format.
Was the intent to reformat all of those too?

Of course not: the purpose is to minimize changes, so going forward we can split all wrapped paragraphs in one sentence per line.

[onlyarnav]

Thank you for the clarification, I have put up a PR, could you please confirm if expectations are met. Thanks :)