From 963257423b5b105951f0d25f58ba526dfdce7bd8 Mon Sep 17 00:00:00 2001
From: Stephen Walsh <868017+stphnwlsh@users.noreply.github.com>
Date: Sun, 8 Nov 2026 17:43:47 +0000
Subject: [PATCH] Allow a dry line on guide and reference pages in
 docs-and-voice

The skill said reference pages get no humour, but the docs keep one dry line in the prose of guides and reference pages, troubleshooting included. Steps, commands, tables and error messages stay plain.
---
 .agents/skills/docs-and-voice/SKILL.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/.agents/skills/docs-and-voice/SKILL.md b/.agents/skills/docs-and-voice/SKILL.md
index 8b11570..f10804a 100644
--- a/.agents/skills/docs-and-voice/SKILL.md
+++ b/.agents/skills/docs-and-voice/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: docs-and-voice
-description: Where documentation lives (README, docs/RUN.md, the Lean Mean Clean Apps docs site) and the house voice - professional with a dry sense of humour, Australian spelling, no humour in reference or steps. Use when writing a README, docs page, release note, issue reply or pull request description.
+description: Where documentation lives (README, docs/RUN.md, the Lean Mean Clean Apps docs site) and the house voice - professional with a dry sense of humour, Australian spelling, humour in prose but never in steps, commands or tables. Use when writing a README, docs page, release note, issue reply or pull request description.
 metadata:
   scope: repository
 ---
@@ -22,7 +22,8 @@ The voice is a small team that knows its stuff and doesn't take itself too serio
 | Kind of writing | Humour |
 | --- | --- |
 | Home pages, introductions, explanations, contributing guides | Yes, lightly, one line at a time |
-| Reference tables, steps, commands, error messages, skills | None |
+| Guides and reference pages, troubleshooting included | Yes, one dry line in an introduction or a section's prose |
+| Steps, commands, tables, error messages, skills | None |
 
 The templates are always listed in the same order: Minimal API, MCP, GraphQL, Web API, Lambda Function.
 
@@ -37,7 +38,7 @@ The templates are always listed in the same order: Minimal API, MCP, GraphQL, We
 ## Don't
 
 - Use marketing words ("blazing fast", "revolutionary", "seamless").
-- Put jokes in steps, tables or error messages.
+- Put jokes in steps, commands, tables or error messages, or let one bend a fact.
 - Duplicate a guide from the docs site in the README.
 - Write in the first person singular; it's "we" and "the team".