diff --git a/skills/discourse-engineering-writing-style/SKILL.md b/skills/discourse-engineering-writing-style/SKILL.md new file mode 100644 index 000000000..435aa0db8 --- /dev/null +++ b/skills/discourse-engineering-writing-style/SKILL.md @@ -0,0 +1,37 @@ +--- +name: discourse-engineering-writing-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 + +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. +- 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. +- When identifying a problem or disagreement, state it plainly and pivot toward clarification, resolution, criteria, or next steps. +- 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 + +- 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 + +- 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..d145d16f7 --- /dev/null +++ b/skills/discourse-engineering-writing-style/agents/openai.yaml @@ -0,0 +1,9 @@ +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: + - "CHAT" + - "CODEX" + allow_implicit_invocation: true