From c3046a5e93366fb67d0ad4edb37c145472cc2155 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Thu, 6 Aug 2026 16:26:14 -0600 Subject: [PATCH 1/5] ENG-2105 Add shared engineering writing style skill --- .../SKILL.md | 32 +++++++++++++++++++ .../agents/openai.yaml | 11 +++++++ 2 files changed, 43 insertions(+) create mode 100644 skills/discourse-engineering-writing-style/SKILL.md create mode 100644 skills/discourse-engineering-writing-style/agents/openai.yaml diff --git a/skills/discourse-engineering-writing-style/SKILL.md b/skills/discourse-engineering-writing-style/SKILL.md new file mode 100644 index 000000000..f179f093f --- /dev/null +++ b/skills/discourse-engineering-writing-style/SKILL.md @@ -0,0 +1,32 @@ +--- +name: discourse-engineering-writing-style +description: Draft and revise engineering emails, chat messages, requests, follow-ups, status updates, PR comments, issue reports, release notes, and other short-form team writing in the shared Discourse Graphs style. Use whenever a Discourse Graphs engineer asks to write, rewrite, phrase, shorten, clarify, or polish a message, unless they request a different style. +--- + +# Discourse Engineering Writing Style + +Write in a direct, concise, plainspoken style that preserves important context and qualification. + +## Core style + +- Lead with the relevant point and move quickly to the concrete question, request, or action. +- Prefer the shortest version that remains clear and preserves necessary nuance. +- Use natural contractions and everyday wording. Avoid corporate jargon, inflated phrasing, and generic professional filler. +- Avoid em dashes as sentence-level punctuation. Use a period, comma, colon, semicolon, or parentheses to separate thoughts instead. Preserve em dashes only when they appear in exact quotations, titles, source text, or technical content supplied by the requester. +- Keep warmth light: use a brief greeting, thanks, or friendly closing when appropriate, without extended pleasantries. +- When identifying a problem or disagreement, state it plainly and pivot toward clarification, resolution, criteria, or next steps. +- Use short paragraphs. Use bullets only when several distinct items genuinely scan better as a list. +- Ask one clear question when one will do. Combine related questions only when separating them would add needless length. + +## Adapt to the channel + +- For a quick reply or chat message, omit the greeting and sign-off when they add no value. +- For technical issues, describe the observed behavior, the relevant contrast or expectation, and the requested clarification or next step. + +## Drafting rules + +- Preserve facts, commitments, dates, names, links, and technical meaning supplied by the requester. +- Do not invent availability, decisions, commitments, or emotional language. +- Treat explicit directions such as "shorter," "warmer," "more forceful," "broader," or "one sentence" as overrides for the current draft. +- When the requester asks for alternatives, vary the framing or emphasis rather than making superficial synonym swaps. +- Return a ready-to-use draft first. Add explanation only when requested or when an ambiguity materially affects the wording. diff --git a/skills/discourse-engineering-writing-style/agents/openai.yaml b/skills/discourse-engineering-writing-style/agents/openai.yaml new file mode 100644 index 000000000..1bba7ce72 --- /dev/null +++ b/skills/discourse-engineering-writing-style/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Discourse Engineering Writing Style" + short_description: "Draft concise, direct engineering team messages" + default_prompt: "Use $discourse-engineering-writing-style to draft a concise engineering team message." +policy: + products: + - "chatgpt" + - "codex" + - "api" + - "atlas" + allow_implicit_invocation: true From b8885fe46ab19ac055df79025fe6a99a65995092 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Thu, 6 Aug 2026 16:56:47 -0600 Subject: [PATCH 2/5] ENG-2105 Fix skill product metadata --- .../discourse-engineering-writing-style/agents/openai.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/skills/discourse-engineering-writing-style/agents/openai.yaml b/skills/discourse-engineering-writing-style/agents/openai.yaml index 1bba7ce72..d145d16f7 100644 --- a/skills/discourse-engineering-writing-style/agents/openai.yaml +++ b/skills/discourse-engineering-writing-style/agents/openai.yaml @@ -4,8 +4,6 @@ interface: default_prompt: "Use $discourse-engineering-writing-style to draft a concise engineering team message." policy: products: - - "chatgpt" - - "codex" - - "api" - - "atlas" + - "CHAT" + - "CODEX" allow_implicit_invocation: true From 9ddeb3bc19e27dd4b98d49efd1aaf046ae317557 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Mon, 10 Aug 2026 12:01:06 -0600 Subject: [PATCH 3/5] review comments --- skills/discourse-engineering-writing-style/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/discourse-engineering-writing-style/SKILL.md b/skills/discourse-engineering-writing-style/SKILL.md index f179f093f..d5f92cd93 100644 --- a/skills/discourse-engineering-writing-style/SKILL.md +++ b/skills/discourse-engineering-writing-style/SKILL.md @@ -11,11 +11,11 @@ Write in a direct, concise, plainspoken style that preserves important context a - Lead with the relevant point and move quickly to the concrete question, request, or action. - Prefer the shortest version that remains clear and preserves necessary nuance. +- Identify wording or missing context that is ambiguous or could be misconstrued. Resolve it when the intended meaning is clear; otherwise, flag it and ask for clarification. - Use natural contractions and everyday wording. Avoid corporate jargon, inflated phrasing, and generic professional filler. - Avoid em dashes as sentence-level punctuation. Use a period, comma, colon, semicolon, or parentheses to separate thoughts instead. Preserve em dashes only when they appear in exact quotations, titles, source text, or technical content supplied by the requester. -- Keep warmth light: use a brief greeting, thanks, or friendly closing when appropriate, without extended pleasantries. - When identifying a problem or disagreement, state it plainly and pivot toward clarification, resolution, criteria, or next steps. -- Use short paragraphs. Use bullets only when several distinct items genuinely scan better as a list. +- Prefer bullets for distinct points. When prose reads more naturally, keep paragraphs and sentences short; avoid run-on sentences. - Ask one clear question when one will do. Combine related questions only when separating them would add needless length. ## Adapt to the channel From 08f6a05b69284ae3475b449c5863818f6bb6c36d Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Mon, 10 Aug 2026 12:01:25 -0600 Subject: [PATCH 4/5] ASD-STE100 --- skills/discourse-engineering-writing-style/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/skills/discourse-engineering-writing-style/SKILL.md b/skills/discourse-engineering-writing-style/SKILL.md index d5f92cd93..21dbbe126 100644 --- a/skills/discourse-engineering-writing-style/SKILL.md +++ b/skills/discourse-engineering-writing-style/SKILL.md @@ -22,6 +22,11 @@ Write in a direct, concise, plainspoken style that preserves important context a - For a quick reply or chat message, omit the greeting and sign-off when they add no value. - For technical issues, describe the observed behavior, the relevant contrast or expectation, and the requested clarification or next step. +- For engineering tickets and technical documentation, apply these ASD-STE100-inspired principles: + - Use one term consistently for each concept. Do not alternate between synonyms. + - Put one primary action or idea in each sentence. + - Prefer active voice when the actor is important. + - Replace vague verbs such as "handle," "support," or "improve" with the specific behavior or result. ## Drafting rules From 5efd1a71a62def3bedc29d38bb516536162a33be Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Mon, 10 Aug 2026 12:44:21 -0600 Subject: [PATCH 5/5] Update engineering writing style skill description to include technical documentation and clarify usage for team communication. --- skills/discourse-engineering-writing-style/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/discourse-engineering-writing-style/SKILL.md b/skills/discourse-engineering-writing-style/SKILL.md index 21dbbe126..435aa0db8 100644 --- a/skills/discourse-engineering-writing-style/SKILL.md +++ b/skills/discourse-engineering-writing-style/SKILL.md @@ -1,6 +1,6 @@ --- name: discourse-engineering-writing-style -description: Draft and revise engineering emails, chat messages, requests, follow-ups, status updates, PR comments, issue reports, release notes, and other short-form team writing in the shared Discourse Graphs style. Use whenever a Discourse Graphs engineer asks to write, rewrite, phrase, shorten, clarify, or polish a message, unless they request a different style. +description: Draft and revise engineering emails, chat messages, requests, follow-ups, status updates, engineering tickets, PR comments, issue reports, release notes, technical documentation, and other team writing in the shared Discourse Graphs style. Use whenever a Discourse Graphs engineer asks to write, rewrite, phrase, shorten, clarify, or polish team communication or documentation, unless they request a different style. --- # Discourse Engineering Writing Style