Skip to content

chore: add a docs-style skill with RomM's house writing rules - #170

Merged
gantoine merged 3 commits into
mainfrom
docs/style-skill
Oct 5, 2026
Merged

gantoine merged 3 commits into
mainfrom
docs/style-skill

Conversation

@gantoine

@gantoine gantoine commented Oct 5, 2026 •

Copy link
Copy Markdown
Member

Adds .claude/skills/docs-style/SKILL.md, a companion to the vendored humanizer that holds RomM's own house style. It captures the edits made by hand on #168, plus earlier ones:

  1. Don't restate context the page, heading or list intro already gives ("Email notification channels, which users add to get their notifications by email")
  2. Don't use "RomM" as a filler subject ("RomM seeds two groups" → "Two groups are seeded"). Keep it where another actor is involved.
  3. Don't cram clauses ("which an upgrade from a release before permission groups also uses")
  4. Merge choppy sentence runs into one sentence, but keep separate points apart
  5. Cross-references go in "(see [link])" parentheticals
  6. No em dashes or semicolons in prose
  7. Describe current behavior. History belongs in the upgrade guide.
  8. No UI walkthroughs in using/, and no provider UI prose in install/
  9. Keep each fact on the page that owns it (defaults, image contents, password rules)
  10. Short front-matter descriptions and short warnings
  11. Terms and facts: Valkey, what the slim image runs, and checking claims against the source

Each rule has before/after examples from real PRs. The skill also ends with three grep checks over the diff. The skill is model-invocable, so it loads whenever docs prose is written or reviewed, not only at PR time.

humanize-docs now applies docs-style after the humanizer. Where the two disagree, docs-style wins, for example on the passive voice from rule 2.

.gitignore now uses the same .claude rules as rommapp/romm. Skills, hooks and settings.json are tracked, and everything else under .claude/ (such as settings.local.json and worktrees/) stays local.

🤖 Generated with Claude Code

gantoine and others added 3 commits October 5, 2026 13:31
Captures the edits maintainers kept making by hand on docs PRs
(restated context, "RomM" as a filler subject, crammed clauses,
choppy sentence runs, history outside the upgrade guide, UI
walkthroughs, facts duplicated across pages) so they're applied
while drafting. humanize-docs now applies it after the humanizer.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Mirrors rommapp/romm's .gitignore: skills, hooks and settings.json are
tracked, everything else under .claude stays local.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@gantoine
gantoine merged commit 5267bba into main Oct 5, 2026
4 checks passed
@gantoine
gantoine deleted the docs/style-skill branch October 5, 2026 23:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant