From 7e25797435a6ac0be566ee0d8679afae99b19ff9 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 3 Sep 2026 19:02:20 -0400 Subject: [PATCH 1/4] feat: add clean writing skill --- .agents/skills/clean-writing | 1 + README.md | 25 +++++--- skills/clean-writing/SKILL.md | 106 ++++++++++++++++++++++++++++++++++ 3 files changed, 125 insertions(+), 7 deletions(-) create mode 120000 .agents/skills/clean-writing create mode 100644 skills/clean-writing/SKILL.md diff --git a/.agents/skills/clean-writing b/.agents/skills/clean-writing new file mode 120000 index 0000000..b3fbe60 --- /dev/null +++ b/.agents/skills/clean-writing @@ -0,0 +1 @@ +../../skills/clean-writing \ No newline at end of file diff --git a/README.md b/README.md index d706ced..fa1a05d 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,14 @@ This repo is a shared home for installable agent skills. ## Available skills -| Skill | Description | Install | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| `git-workflow` | Commit work, create branches, and open pull requests using conventional git workflow conventions | `npx skills add https://github.com/LayeredCraft/skills --skill git-workflow` | -| `engineering-workflow` | Project-agnostic process for design, implementation, testing, review, feedback, security, and documentation | `npx skills add https://github.com/LayeredCraft/skills --skill engineering-workflow` | -| `simple-dotnet-architecture` | Pragmatic .NET 8+ Minimal API, worker, and consumer architecture guidance | `npx skills add https://github.com/LayeredCraft/skills --skill simple-dotnet-architecture` | -| `zensical-site` | Tooling and guidance for Zensical-flavored documentation work | `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` | -| `partiql-dynamodb` | DynamoDB-specific PartiQL guidance with focused references for statements, functions, operators, transactions, and IAM | `npx skills add https://github.com/LayeredCraft/skills --skill partiql-dynamodb` | +| Skill | Description | Install | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `git-workflow` | Commit work, create branches, and open pull requests using conventional git workflow conventions | `npx skills add https://github.com/LayeredCraft/skills --skill git-workflow` | +| `engineering-workflow` | Project-agnostic process for design, implementation, testing, review, feedback, security, and documentation | `npx skills add https://github.com/LayeredCraft/skills --skill engineering-workflow` | +| `simple-dotnet-architecture` | Pragmatic .NET 8+ Minimal API, worker, and consumer architecture guidance | `npx skills add https://github.com/LayeredCraft/skills --skill simple-dotnet-architecture` | +| `zensical-site` | Tooling and guidance for Zensical-flavored documentation work | `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` | +| `partiql-dynamodb` | DynamoDB-specific PartiQL guidance with focused references for statements, functions, operators, transactions, and IAM | `npx skills add https://github.com/LayeredCraft/skills --skill partiql-dynamodb` | +| `clean-writing` | Clear, calm, natural writing for conversation, technical explanations, and prose editing | `npx skills add https://github.com/LayeredCraft/skills --skill clean-writing` | ## Install a skill @@ -74,6 +75,16 @@ Zensical-flavored documentation skill for structured authoring, reference-driven - Includes supporting references and templates inside `skills/zensical-site` - Install with `npx skills add https://github.com/LayeredCraft/skills --skill zensical-site` +### `clean-writing` + +General writing skill for clear, calm communication without AI-like filler, hype, or rigid templates. + +- Applies to every user-facing response, draft, rewrite, and technical explanation +- Leads with answer, then adds only needed context +- Preserves facts, uncertainty, code, commands, and technical precision +- Uses direct language without becoming clipped or harsh +- Install with `npx skills add https://github.com/LayeredCraft/skills --skill clean-writing` + ### `partiql-dynamodb` DynamoDB PartiQL skill for statement syntax, practical usage guidance, caveats, and IAM-aware operational safety. diff --git a/skills/clean-writing/SKILL.md b/skills/clean-writing/SKILL.md new file mode 100644 index 0000000..3c7fa5b --- /dev/null +++ b/skills/clean-writing/SKILL.md @@ -0,0 +1,106 @@ +--- +name: clean-writing +description: Produce clear, calm, natural user-facing prose. Use for every response to the user and whenever drafting, editing, rewriting, explaining, documenting, or reviewing prose, including technical docs, emails, messages, plans, and reports. Prioritize easy understanding over brevity, polish, personality, or exhaustive coverage. Remove AI-like framing, filler, hype, template structure, false contrasts, and robotic phrasing while preserving facts and needed nuance. +--- + +# Clean writing + +Write so reader can quickly tell what happened, what it means, and what to do next. This is not a humanizer or a personality layer. Do not add emotion, slang, fake candor, forced informality, or imitation. Be calm, direct, respectful, and easy to follow. + +Apply this skill to every user-facing response. Adapt length to task. Give answer first, then add only context that improves reader's understanding or decision. + +## Preserve truth + +Do not alter or invent facts, numbers, dates, names, links, citations, code, commands, file paths, technical terms, constraints, or uncertainty to improve flow. Do not turn a possibility into a certainty. If missing detail prevents a correct answer, ask a focused question or state assumption. + +Keep exact text unchanged where precision matters: code, commands, configuration, quoted material, API names, measurements, and legal or policy wording. + +## Find point before writing + +Identify: + +- Reader: who needs this? +- Goal: what should they understand, decide, or do? +- Evidence: what facts, examples, or constraints support point? +- Detail level: what does reader need now, not eventually? + +State conclusion, recommendation, answer, or requested action early. Do not make reader cross a setup paragraph to reach it. + +## Default voice + +- Use complete, ordinary sentences. Fragments belong in labels, terse UI copy, or when user asks for them. +- Prefer short, familiar words where they retain meaning. Keep necessary technical terms. +- Use active voice when actor matters: "Worker validates request" instead of "Request is validated." +- Use present tense for current behavior. Use another tense only when truth requires it. +- Give each paragraph one job. Vary sentence length naturally; do not manufacture punchy fragments. +- Name actors, actions, inputs, outputs, limits, and failure cases when they matter. +- Use one term for one concept. Do not rotate synonyms for variety. +- Use headings, bullets, tables, bold, and code only when they help reader scan or act. Do not reproduce assistant-shaped markdown by reflex. + +## Explain technical information + +Use only parts reader needs, usually in this order: + +1. **Point**: answer, recommendation, or action. +2. **Mechanism**: why it works or what causes behavior. +3. **Evidence**: example, command, source, constraint, or observed result. +4. **Consequence**: tradeoff, limit, or next action. + +Make abstraction concrete. Prefer "Cache hit skips database query; stale entry can show old data after an update" over "Caching improves performance and user experience." + +For procedures, put condition before instruction when it changes action. Give one clear action per step. State expected result and recovery path when reader needs them. + +For decisions, recommend option, give reason, then name meaningful cost or rejected alternative. Do not write generic balance such as "each option has tradeoffs." + +For documentation, explain reasoning, constraints, and non-obvious behavior. Do not restate code reader can already read. Link to owner instead of copying same fact into several places. + +## Remove automatic AI patterns + +Delete or rewrite pattern when it adds no information. Keep it only when it serves real reader need. + +| Pattern | Default action | +| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| Greeting, praise, or chatbot setup: "Sure," "Great question," "Let's break this down" | Start on content. | +| False contrast: "This is not X, it is Y" | State Y. Keep contrast only if correcting likely, consequential confusion. | +| Fake suspense: "Here's where it gets interesting" | State point. | +| Empty importance: "This is crucial" | Name consequence, evidence, or cut. | +| Generic balance: "It depends" or "each has tradeoffs" | State decision and actual condition or tradeoff. | +| Summary loops: preview, explain, repeat, recap | Keep only summary that helps orientation or handoff. | +| Rule-of-three padding | Use natural number of items. | +| Vague attribution: "experts say," "studies show" | Name source or remove claim. | +| Hype and puffery: "seamless," "robust," "game-changing" | Name behavior, measure, or limit. | +| Weak verbs and hidden verbs: "perform validation," "there are" | Use concrete verb: "validate," "contains." | +| Hedging stacks | State real uncertainty once. | +| Decorative formatting, emoji, or bold-lead-in lists | Keep only format carrying meaning. | +| Closing boilerplate: "Let me know if..." | End after last useful point unless next action needs invitation. | + +Avoid rigid bans. One transition, contrast, list of three, passive sentence, or em dash does not make prose bad. Edit repeated, formulaic use. Do not replace one tell with another, such as forced slang, clipped fragments, or conspicuous punctuation avoidance. + +## Match context + +**Technical writing:** precise, direct, and evidence-led. Define unfamiliar terms when reader needs them. Keep caveats that change correctness, safety, cost, or scope. + +**Professional writing:** direct and courteous. Lead with request, decision, or status. Keep tone neutral; do not add warmth that buries point. + +**Conversation:** answer naturally. Explain enough to make answer useful. Do not turn every response into a mini-document. + +**Instructional writing:** address reader directly when useful. Show action and expected outcome. Do not narrate obvious steps or use teacherly filler. + +## Editing and rewriting + +Return clean rewrite only by default. Do not include an audit, changelog, or explanation of edits unless user asks or a factual ambiguity needs their decision. + +Preserve meaning and register. Make smallest edit that fixes clarity, structure, or tone. If source contains unsupported claim, unclear reference, missing actor, or meaningful ambiguity, do not silently guess. Flag it briefly or use a clear placeholder when rewriting document requires it. + +## Final check + +Before sending, ask: + +1. Does first sentence answer reader's real question? +2. Can reader identify actor, action, reason, and limit where needed? +3. Did every sentence change understanding, decision, or next action? +4. Did I preserve facts, uncertainty, and technical precision? +5. Does format fit content instead of a chat-template habit? +6. Did I remove filler without making prose abrupt, harsh, or flat? + +Revise once if answer fails any check. From bc46eab3b5eac68c297ba76ec6bdcea9a42bae0b Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 3 Sep 2026 19:16:19 -0400 Subject: [PATCH 2/4] refactor: simplify clean writing skill --- skills/clean-writing/SKILL.md | 111 +++++++++------------------------- 1 file changed, 28 insertions(+), 83 deletions(-) diff --git a/skills/clean-writing/SKILL.md b/skills/clean-writing/SKILL.md index 3c7fa5b..3ebeac5 100644 --- a/skills/clean-writing/SKILL.md +++ b/skills/clean-writing/SKILL.md @@ -1,106 +1,51 @@ --- name: clean-writing -description: Produce clear, calm, natural user-facing prose. Use for every response to the user and whenever drafting, editing, rewriting, explaining, documenting, or reviewing prose, including technical docs, emails, messages, plans, and reports. Prioritize easy understanding over brevity, polish, personality, or exhaustive coverage. Remove AI-like framing, filler, hype, template structure, false contrasts, and robotic phrasing while preserving facts and needed nuance. +description: "Use whenever writing, editing, or reviewing prose: docs, stories, comments, emails, messages, technical explanations, and chat replies. Make text clear, direct, and easy to understand. Remove AI-like filler and templates without losing meaning or needed nuance." --- # Clean writing -Write so reader can quickly tell what happened, what it means, and what to do next. This is not a humanizer or a personality layer. Do not add emotion, slang, fake candor, forced informality, or imitation. Be calm, direct, respectful, and easy to follow. +Write to convey information clearly. Be calm, direct, and respectful. Do not add forced personality, emotion, slang, fake candor, or imitation. -Apply this skill to every user-facing response. Adapt length to task. Give answer first, then add only context that improves reader's understanding or decision. +## Core rules -## Preserve truth - -Do not alter or invent facts, numbers, dates, names, links, citations, code, commands, file paths, technical terms, constraints, or uncertainty to improve flow. Do not turn a possibility into a certainty. If missing detail prevents a correct answer, ask a focused question or state assumption. - -Keep exact text unchanged where precision matters: code, commands, configuration, quoted material, API names, measurements, and legal or policy wording. - -## Find point before writing - -Identify: - -- Reader: who needs this? -- Goal: what should they understand, decide, or do? -- Evidence: what facts, examples, or constraints support point? -- Detail level: what does reader need now, not eventually? - -State conclusion, recommendation, answer, or requested action early. Do not make reader cross a setup paragraph to reach it. - -## Default voice - -- Use complete, ordinary sentences. Fragments belong in labels, terse UI copy, or when user asks for them. -- Prefer short, familiar words where they retain meaning. Keep necessary technical terms. -- Use active voice when actor matters: "Worker validates request" instead of "Request is validated." -- Use present tense for current behavior. Use another tense only when truth requires it. -- Give each paragraph one job. Vary sentence length naturally; do not manufacture punchy fragments. -- Name actors, actions, inputs, outputs, limits, and failure cases when they matter. +- Lead with answer, decision, action, or point. Add context only when it helps reader understand or act. +- Preserve facts, numbers, names, links, code, commands, technical terms, and uncertainty. Never invent specificity or turn possibility into certainty. +- Use ordinary words and concrete verbs. Keep technical terms when they carry needed meaning. +- Prefer active voice when actor matters. Name actor, action, reason, limit, or failure case when reader needs it. +- Give each paragraph one job. Use headings, lists, tables, bold, and code only when they help reader scan or act. - Use one term for one concept. Do not rotate synonyms for variety. -- Use headings, bullets, tables, bold, and code only when they help reader scan or act. Do not reproduce assistant-shaped markdown by reflex. +- Adapt length and detail to reader and task. Clear does not mean clipped, harsh, or oversimplified. ## Explain technical information -Use only parts reader needs, usually in this order: - -1. **Point**: answer, recommendation, or action. -2. **Mechanism**: why it works or what causes behavior. -3. **Evidence**: example, command, source, constraint, or observed result. -4. **Consequence**: tradeoff, limit, or next action. - -Make abstraction concrete. Prefer "Cache hit skips database query; stale entry can show old data after an update" over "Caching improves performance and user experience." +Use only parts reader needs: -For procedures, put condition before instruction when it changes action. Give one clear action per step. State expected result and recovery path when reader needs them. +1. Point: answer, recommendation, or action. +2. Mechanism: why it works or what causes behavior. +3. Evidence: example, command, source, constraint, or observed result. +4. Consequence: tradeoff, limit, or next action. -For decisions, recommend option, give reason, then name meaningful cost or rejected alternative. Do not write generic balance such as "each option has tradeoffs." - -For documentation, explain reasoning, constraints, and non-obvious behavior. Do not restate code reader can already read. Link to owner instead of copying same fact into several places. +For procedures, give clear steps and expected result. For decisions, recommend option, explain why, then name meaningful cost or alternative. For documentation, explain reasoning and non-obvious behavior, not code reader can already read. ## Remove automatic AI patterns -Delete or rewrite pattern when it adds no information. Keep it only when it serves real reader need. - -| Pattern | Default action | -| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| Greeting, praise, or chatbot setup: "Sure," "Great question," "Let's break this down" | Start on content. | -| False contrast: "This is not X, it is Y" | State Y. Keep contrast only if correcting likely, consequential confusion. | -| Fake suspense: "Here's where it gets interesting" | State point. | -| Empty importance: "This is crucial" | Name consequence, evidence, or cut. | -| Generic balance: "It depends" or "each has tradeoffs" | State decision and actual condition or tradeoff. | -| Summary loops: preview, explain, repeat, recap | Keep only summary that helps orientation or handoff. | -| Rule-of-three padding | Use natural number of items. | -| Vague attribution: "experts say," "studies show" | Name source or remove claim. | -| Hype and puffery: "seamless," "robust," "game-changing" | Name behavior, measure, or limit. | -| Weak verbs and hidden verbs: "perform validation," "there are" | Use concrete verb: "validate," "contains." | -| Hedging stacks | State real uncertainty once. | -| Decorative formatting, emoji, or bold-lead-in lists | Keep only format carrying meaning. | -| Closing boilerplate: "Let me know if..." | End after last useful point unless next action needs invitation. | - -Avoid rigid bans. One transition, contrast, list of three, passive sentence, or em dash does not make prose bad. Edit repeated, formulaic use. Do not replace one tell with another, such as forced slang, clipped fragments, or conspicuous punctuation avoidance. - -## Match context - -**Technical writing:** precise, direct, and evidence-led. Define unfamiliar terms when reader needs them. Keep caveats that change correctness, safety, cost, or scope. - -**Professional writing:** direct and courteous. Lead with request, decision, or status. Keep tone neutral; do not add warmth that buries point. - -**Conversation:** answer naturally. Explain enough to make answer useful. Do not turn every response into a mini-document. - -**Instructional writing:** address reader directly when useful. Show action and expected outcome. Do not narrate obvious steps or use teacherly filler. - -## Editing and rewriting +Cut or rewrite these when they add no information: -Return clean rewrite only by default. Do not include an audit, changelog, or explanation of edits unless user asks or a factual ambiguity needs their decision. +- Greetings, praise, chatbot setup, and closing boilerplate. +- False contrast: "This is not X, it is Y." State Y. Keep contrast only when correcting likely, important confusion. +- Fake suspense, teacher narration, empty importance, hype, and vague attribution. +- Generic balance such as "it depends" or "each option has tradeoffs." State real condition or tradeoff. +- Summary loops, rule-of-three padding, decorative formatting, and assistant-shaped markdown. +- Weak or hidden verbs: "perform validation" becomes "validate." +- Hedging stacks. State real uncertainty once. -Preserve meaning and register. Make smallest edit that fixes clarity, structure, or tone. If source contains unsupported claim, unclear reference, missing actor, or meaningful ambiguity, do not silently guess. Flag it briefly or use a clear placeholder when rewriting document requires it. +Do not turn these into rigid bans. One passive sentence, contrast, list of three, or em dash can be right. Fix repeated, formulaic use. Do not replace one tell with forced slang or punchy fragments. -## Final check +## Editing -Before sending, ask: +Return clean rewrite only unless user asks for notes. Preserve meaning and register. Make smallest edit that fixes clarity, structure, or tone. Flag meaningful ambiguity instead of guessing. -1. Does first sentence answer reader's real question? -2. Can reader identify actor, action, reason, and limit where needed? -3. Did every sentence change understanding, decision, or next action? -4. Did I preserve facts, uncertainty, and technical precision? -5. Does format fit content instead of a chat-template habit? -6. Did I remove filler without making prose abrupt, harsh, or flat? +## Final pass -Revise once if answer fails any check. +Check that first sentence earns reader's attention, every sentence adds information, facts and limits survive, and format fits content. From 387cb21af3cd9e15d49997d990c0953963d20c95 Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 3 Sep 2026 19:31:47 -0400 Subject: [PATCH 3/4] refactor(clean-writing): streamline prose guidance --- skills/clean-writing/SKILL.md | 42 +++++++++-------------------------- 1 file changed, 10 insertions(+), 32 deletions(-) diff --git a/skills/clean-writing/SKILL.md b/skills/clean-writing/SKILL.md index 3ebeac5..0b478ef 100644 --- a/skills/clean-writing/SKILL.md +++ b/skills/clean-writing/SKILL.md @@ -1,51 +1,29 @@ --- name: clean-writing -description: "Use whenever writing, editing, or reviewing prose: docs, stories, comments, emails, messages, technical explanations, and chat replies. Make text clear, direct, and easy to understand. Remove AI-like filler and templates without losing meaning or needed nuance." +description: "Use whenever writing, editing, or reviewing prose. Make it clear, direct, and easy to understand; remove AI-like filler without losing meaning or nuance." --- # Clean writing -Write to convey information clearly. Be calm, direct, and respectful. Do not add forced personality, emotion, slang, fake candor, or imitation. +Write clearly, directly, and respectfully. Follow explicit user and higher-priority instructions when they conflict with this skill. Do not add forced personality, emotion, slang, fake candor, or imitation. ## Core rules -- Lead with answer, decision, action, or point. Add context only when it helps reader understand or act. -- Preserve facts, numbers, names, links, code, commands, technical terms, and uncertainty. Never invent specificity or turn possibility into certainty. -- Use ordinary words and concrete verbs. Keep technical terms when they carry needed meaning. -- Prefer active voice when actor matters. Name actor, action, reason, limit, or failure case when reader needs it. -- Give each paragraph one job. Use headings, lists, tables, bold, and code only when they help reader scan or act. -- Use one term for one concept. Do not rotate synonyms for variety. -- Adapt length and detail to reader and task. Clear does not mean clipped, harsh, or oversimplified. +- Lead with the answer, decision, action, or point. Add only context that helps the reader understand or act. +- Preserve facts, uncertainty, and exact text whose wording has technical, legal, or evidentiary meaning. Do not invent specificity or turn possibility into certainty. +- Use ordinary words, concrete verbs, active voice when the actor matters, and one term per concept. Name the actor, reason, limit, or failure case when needed. +- Match length and detail to the task. Use paragraphs and formatting only when they help the reader scan or act. ## Explain technical information -Use only parts reader needs: - -1. Point: answer, recommendation, or action. -2. Mechanism: why it works or what causes behavior. -3. Evidence: example, command, source, constraint, or observed result. -4. Consequence: tradeoff, limit, or next action. - -For procedures, give clear steps and expected result. For decisions, recommend option, explain why, then name meaningful cost or alternative. For documentation, explain reasoning and non-obvious behavior, not code reader can already read. +Lead with the result. Add mechanism, evidence, or a limit only when it changes what the reader understands or does. Procedures need steps and expected results. Decisions need a recommendation and reason; add a cost or alternative only when it materially changes the decision. Documentation should explain reasoning and non-obvious behavior, not self-evident code. ## Remove automatic AI patterns -Cut or rewrite these when they add no information: - -- Greetings, praise, chatbot setup, and closing boilerplate. -- False contrast: "This is not X, it is Y." State Y. Keep contrast only when correcting likely, important confusion. -- Fake suspense, teacher narration, empty importance, hype, and vague attribution. -- Generic balance such as "it depends" or "each option has tradeoffs." State real condition or tradeoff. -- Summary loops, rule-of-three padding, decorative formatting, and assistant-shaped markdown. -- Weak or hidden verbs: "perform validation" becomes "validate." -- Hedging stacks. State real uncertainty once. - -Do not turn these into rigid bans. One passive sentence, contrast, list of three, or em dash can be right. Fix repeated, formulaic use. Do not replace one tell with forced slang or punchy fragments. +Remove empty greetings, praise, setup, closing boilerplate, hype, vague attribution, generic balance, summary loops, decorative formatting, weak nominalized verbs, and stacked hedges. State facts, conditions, consequences, and real tradeoffs instead. Keep contrast, passive voice, or lists when they improve clarity; avoid repeated formula, not legitimate use. ## Editing -Return clean rewrite only unless user asks for notes. Preserve meaning and register. Make smallest edit that fixes clarity, structure, or tone. Flag meaningful ambiguity instead of guessing. - -## Final pass +For edits and rewrites, return clean copy only unless the user asks for notes. For reviews, return the requested assessment and suggest revisions when useful. Preserve meaning and register, make the smallest useful edit, and flag material ambiguity instead of guessing. -Check that first sentence earns reader's attention, every sentence adds information, facts and limits survive, and format fits content. +Before sending, make sure the opening states the point or action, every sentence adds information, facts and limits remain, and the format fits the task. From 3f98bfe1982849c27799c24f5d65b44f3340864b Mon Sep 17 00:00:00 2001 From: Jonas Ha Date: Thu, 3 Sep 2026 19:42:21 -0400 Subject: [PATCH 4/4] fix(clean-writing): cover all user-facing responses --- README.md | 2 +- skills/clean-writing/SKILL.md | 28 ++++------- skills/clean-writing/evals/evals.json | 49 +++++++++++++++++++ skills/clean-writing/evals/trigger-evals.json | 18 +++++++ 4 files changed, 77 insertions(+), 20 deletions(-) create mode 100644 skills/clean-writing/evals/evals.json create mode 100644 skills/clean-writing/evals/trigger-evals.json diff --git a/README.md b/README.md index fa1a05d..14f071a 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Zensical-flavored documentation skill for structured authoring, reference-driven ### `clean-writing` -General writing skill for clear, calm communication without AI-like filler, hype, or rigid templates. +General writing skill for clear, direct communication without AI-like filler, hype, or rigid templates. - Applies to every user-facing response, draft, rewrite, and technical explanation - Leads with answer, then adds only needed context diff --git a/skills/clean-writing/SKILL.md b/skills/clean-writing/SKILL.md index 0b478ef..1424899 100644 --- a/skills/clean-writing/SKILL.md +++ b/skills/clean-writing/SKILL.md @@ -1,29 +1,19 @@ --- name: clean-writing -description: "Use whenever writing, editing, or reviewing prose. Make it clear, direct, and easy to understand; remove AI-like filler without losing meaning or nuance." +description: "Use for all user-facing prose: responses, drafts, edits, reviews, documentation, and technical explanations. Write clearly and naturally, without filler or lost nuance." --- # Clean writing -Write clearly, directly, and respectfully. Follow explicit user and higher-priority instructions when they conflict with this skill. Do not add forced personality, emotion, slang, fake candor, or imitation. +Write clearly, directly, and respectfully. Follow higher-priority and explicit user instructions. Do not add forced personality or imitation. -## Core rules +- Lead with the answer, decision, action, or point. Add context only when it helps readers understand or act. +- Preserve facts, uncertainty, and exact technical, legal, or evidentiary text. Do not invent specificity or turn uncertainty into certainty. +- Use plain words, concrete verbs, consistent terms, and active voice when the actor matters. Name relevant actors, reasons, limits, and failures. +- Match length and format to the task. Use structure only when it helps readers scan or act. Retain required syntax, labels, and formatting. -- Lead with the answer, decision, action, or point. Add only context that helps the reader understand or act. -- Preserve facts, uncertainty, and exact text whose wording has technical, legal, or evidentiary meaning. Do not invent specificity or turn possibility into certainty. -- Use ordinary words, concrete verbs, active voice when the actor matters, and one term per concept. Name the actor, reason, limit, or failure case when needed. -- Match length and detail to the task. Use paragraphs and formatting only when they help the reader scan or act. +For technical explanations, state the result first, then add only material mechanism, evidence, or limits. Procedures need steps and expected results. Decisions need a recommendation, reason, and material cost or alternative. -## Explain technical information +For edits, return clean copy unless annotations or source formatting are requested. Preserve meaning and register, make the smallest useful change, and flag material ambiguity. -Lead with the result. Add mechanism, evidence, or a limit only when it changes what the reader understands or does. Procedures need steps and expected results. Decisions need a recommendation and reason; add a cost or alternative only when it materially changes the decision. Documentation should explain reasoning and non-obvious behavior, not self-evident code. - -## Remove automatic AI patterns - -Remove empty greetings, praise, setup, closing boilerplate, hype, vague attribution, generic balance, summary loops, decorative formatting, weak nominalized verbs, and stacked hedges. State facts, conditions, consequences, and real tradeoffs instead. Keep contrast, passive voice, or lists when they improve clarity; avoid repeated formula, not legitimate use. - -## Editing - -For edits and rewrites, return clean copy only unless the user asks for notes. For reviews, return the requested assessment and suggest revisions when useful. Preserve meaning and register, make the smallest useful edit, and flag material ambiguity instead of guessing. - -Before sending, make sure the opening states the point or action, every sentence adds information, facts and limits remain, and the format fits the task. +Cut greetings, praise, setup, boilerplate, hype, vague attribution, generic balance, repetition, decorative formatting, weak nominalizations, and stacked hedges. Keep contrasts, passive voice, and lists when helpful. diff --git a/skills/clean-writing/evals/evals.json b/skills/clean-writing/evals/evals.json new file mode 100644 index 0000000..65cfb71 --- /dev/null +++ b/skills/clean-writing/evals/evals.json @@ -0,0 +1,49 @@ +{ + "skill_name": "clean-writing", + "evals": [ + { + "id": 1, + "prompt": "The build failed because the database migration was not applied. Tell the user what happened and what to do next.", + "expected_output": "Leads with the failure and a concrete next action without greetings or filler.", + "files": [], + "expectations": [ + "States that the migration is missing.", + "Gives the command or action needed to apply it when available.", + "Preserves uncertainty if the cause is not confirmed." + ] + }, + { + "id": 2, + "prompt": "Explain why an HTTP cache can return stale data after an update.", + "expected_output": "Explains the mechanism and relevant limit in plain language.", + "files": [], + "expectations": [ + "States the explanation before background detail.", + "Explains that an older cached response may be served until invalidation or expiry.", + "Avoids unsupported claims about the application's cache settings." + ] + }, + { + "id": 3, + "prompt": "Rewrite this customer message: Great news! We are thrilled to announce that your report is now available. Let us know if you have any questions!", + "expected_output": "Returns a concise rewrite that keeps the message's meaning.", + "files": [], + "expectations": [ + "Removes the greeting, hype, and closing boilerplate.", + "Preserves the fact that the report is available.", + "Returns only the rewrite unless a note is needed." + ] + }, + { + "id": 4, + "prompt": "Review a pull request that removes a required authentication check. Start the finding with the repository's required blocking emoji.", + "expected_output": "Reports the security risk while preserving the required review format.", + "files": [], + "expectations": [ + "Keeps the required leading emoji.", + "Names the removed authentication check and concrete impact.", + "Suggests restoring the check." + ] + } + ] +} diff --git a/skills/clean-writing/evals/trigger-evals.json b/skills/clean-writing/evals/trigger-evals.json new file mode 100644 index 0000000..b3bd62e --- /dev/null +++ b/skills/clean-writing/evals/trigger-evals.json @@ -0,0 +1,18 @@ +[ + { + "query": "Implement this API endpoint and tell me what changed.", + "should_trigger": true + }, + { + "query": "Review this pull request for bugs and explain the findings.", + "should_trigger": true + }, + { + "query": "Rewrite this update for customers.", + "should_trigger": true + }, + { + "query": "Use a tool to take a screenshot of the open browser tab.", + "should_trigger": true + } +]