All skills
kmaida avatar

/deslop-writing

@70237e1
by Kim Maidakmaida/deslop-skills10 stars
2

A style guide that removes the clichéd writing patterns common in AI-generated drafts, including habits specific to ChatGPT, Claude, Gemini, and others, in favor of clear, concrete, readable prose. Activates on any writing task: tweets, emails, articles, bios, captions, reports, copy, messages, LinkedIn posts, cover letters, README files, or any content that should read as clear, natural writing. Also activates in detect mode when the user asks whether a draft reads like generic AI prose, or asks to audit, scan, check, or flag a draft for slop patterns without rewriting it. Enforces banned vocabulary, structural variety, punctuation discipline, accuracy rules, and voice calibration. Technical documentation (product docs, guides, references, READMEs, help text) additionally follows the Apple Style Guide. Use when the user says "deslop" about any text or writing, or says "write," "draft," "rewrite," "tighten this," "make this sound natural," "anti-slop," or any variation of wanting clean, readable output.

Demo

Recorded with OpenCode, zai-coding-plan/glm-5.3

PromptRewrite these Markdown documents to remove AI writing tells and make them clear and natural. Preserve all facts, uncertainty, code, links, identifiers, and useful document structure. Return only the requested documents, without review notes. Documents: {"reading-list.md":"# Keeping a reading list that works for you\n\nIn today's fast-paced digital landscape, managing a reading list has become an increasingly important part of staying informed. Indeed, it goes without saying that by leveraging a thoughtful approach, you can transform a simple collection of links into a valuable resource for learning and growth.\n\n## A streamlined approach\n\nIt's worth noting that a reading list doesn't need to be complicated. Our fictional reading-list app, Margin, offers a streamlined approach that truly delivers. Margin stores a title, URL, and category for each link. Furthermore, you can filter by category and bookmark items you want to return to. Everything stays in your browser. It's important to note that there is no account or cloud sync, which keeps things refreshingly straightforward.\n\n## Building better habits\n\nMoreover, a weekly review can help you navigate the ever-growing collection of articles. Remove links you no longer want to read. Keep the ones that connect to a project you are working on. This simple habit can make a world of difference over time.\n\nUltimately, the goal is to create a seamless reading experience that empowers you to make the most of your time. At the end of the day, a small, focused list can be more useful than an extensive collection you never open.","README.md":"# Margin\n\nMargin is a fictional TypeScript package designed to streamline the management of reading lists. It provides a robust yet intuitive API for organizing links by category, enabling developers to create seamless reading experiences.\n\n## Getting started\n\nTo begin leveraging Margin, simply import `filterLinks` and pass your links and the desired category. It's worth noting that the function returns matching links in their original order. Furthermore, passing an empty category returns all links.\n\n```ts\nimport { filterLinks } from 'margin'\n\nconst links = [\n { title: 'CSS notes', url: 'https://example.com/css', category: 'CSS' },\n { title: 'TypeScript notes', url: 'https://example.com/ts', category: 'TypeScript' },\n]\n\nconst cssLinks = filterLinks(links, 'CSS')\n```\n\n## Important considerations\n\nIt's important to note that category matching is case-sensitive. Moreover, the function does not modify the input array. It's also worth highlighting that Margin does not fetch URLs or store links. Ultimately, Margin is solely a filtering function, making it a valuable addition to your toolkit.","pr.md":"# Add category filtering to the reading list\n\nThis pull request introduces a streamlined category filtering experience to our fictional reading-list app, Margin. By leveraging the existing category field, users can now navigate their saved articles with greater ease and efficiency.\n\nPreviously, the list displayed every saved link regardless of the selected category. With this enhancement, selecting a category displays only matching links. It's worth noting that selecting All displays the complete list.\n\nFurthermore, filtering preserves the original order of links and does not change bookmarks. It's important to note that the selected category resets when the page reloads. Moreover, search and saved filter preferences are outside the scope of this change.\n\nUltimately, this improvement provides a more focused and intuitive reading experience while maintaining the simplicity of the existing interface."} Return one JSON object with exactly these keys: "reading-list.md", "README.md", "pr.md". Each value is the complete Markdown document as a JSON string. No outer Markdown fence or commentary.

FolderAI-generated original Markdown and a shared no-Skill rewrite. Three documents about the fictional Margin app and package.

Keep a reading list that works

A pile of saved links only becomes a reading list once you can sort it. The links you keep should be the ones you'll actually return to, and structure is what makes that possible.

What Margin does

Margin, our fictional reading-list app, stores three things for each link: a title, URL, and category. You can filter by category and bookmark items you want to come back to. Everything stays in your browser; there's no account and no cloud sync, which keeps things simple.

A weekly review

Go through the list once a week. Remove the links you no longer want to read, and keep the ones tied to a project you're working on. A small, focused list beats a big collection you never open.

Markdown
# Keep a reading list that works

A pile of saved links only becomes a reading list once you can sort it. The links you keep should be the ones you'll actually return to, and structure is what makes that possible.

## What Margin does

Margin, our fictional reading-list app, stores three things for each link: a title, URL, and category. You can filter by category and bookmark items you want to come back to. Everything stays in your browser; there's no account and no cloud sync, which keeps things simple.

## A weekly review

Go through the list once a week. Remove the links you no longer want to read, and keep the ones tied to a project you're working on. A small, focused list beats a big collection you never open.
Run it yourself All demos
Use this Skill: https://skilld.dev/gh/kmaida/deslop-skills/deslop-writing

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesapple-style-tech-docs.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Apple Style Guide for technical documentation

Authority for technical documentation style: the Apple Style Guide at https://support.apple.com/guide/applestyleguide/welcome/web (PDF: https://help.apple.com/pdf/applestyleguide/en_US/apple-style-guide.pdf).

This file summarizes the conventions that come up constantly. The live guide is authoritative; when a specific term, capitalization, or usage question isn't covered here or the answer matters, fetch the relevant A–Z page and check. Entry pages follow the pattern https://support.apple.com/guide/applestyleguide/<letter>-<id>/web; start from the welcome page's table of contents, or search the guide. Don't guess on terminology in published docs.

Scope

Applies to technical documentation: product docs, reference material, how-to guides, tutorials, API docs, READMEs written as documentation, in-product help text, error messages. Does not apply to blog posts, social posts, emails, talks, or marketing copy; those follow the user's writing guide or writing skills and the base deslop rules.

Precedence

  1. Hard bans always win, even in tech docs: no em dashes ever, no banned-list vocabulary, plus any hard rules in the user's writing guide. Where the Apple guide would use an em dash, use a colon, comma, parentheses, or a new sentence.
  2. Apple Style Guide governs everything else in tech docs: terminology, capitalization, numbers, UI interaction verbs, punctuation conventions, code notation.
  3. Base deslop rules fill any gap the Apple guide doesn't address.
  4. Blog posts override all of the above in favor of the user's writing guide or writing skills, even when a post is deeply technical.

Voice and grammar

  • Second person, present tense, active voice. "You can revoke the token" not "The token may be revoked."
  • Imperative mood for instructions: "Click Save." Never "Please click Save"; don't use please in instructions.
  • Can for capability, might for possibility, may for permission. Don't use may when you mean can.
  • Contractions are fine and encouraged where they sound natural (don't, can't, it's, you're). Avoid stiff or ambiguous ones (there'd, it'll, should've).
  • Don't use wish or desire; use want. Don't use simply or easy to describe steps; if it were easy the reader wouldn't be in the docs.
  • Serial (Oxford) comma, always.
  • Don't use Latin abbreviations in body text: for example not e.g., that is not i.e., and so on not etc. (etc. is acceptable in tight table cells).
  • Don't use above or below for cross-references; use precise links or "earlier in this section."
  • Avoid abort, kill, execute, hit, invalid user framings when a neutral verb works: stop, end, run, press, unrecognized user. Exception: keep the literal term when it names a command or API (kill -9, execute() stays code font, unchanged).
  • Inclusive terms: allowlist/denylist not whitelist/blacklist, primary/replica not master/slave, placeholder or sample data with diverse example names. Don't use grayed out; use dimmed.

UI interaction verbs

  • Click for pointer interfaces, tap for touch, press for physical keys and buttons.
  • Choose for menu commands ("Choose File > Export"); select for highlighting items, checkboxes, radio buttons, and text.
  • Enter when the user can type or paste a value; type only when they literally type.
  • Turn on / turn off for settings when addressing users; reserve enable/disable for developer-facing feature flags and API parameters where that's the literal name.
  • Sign in / sign out, never log in / log out / login. Login only as an adjective in developer contexts where the platform uses it (a login endpoint named login stays login).

Numbers

  • Spell out zero through nine in body text; numerals for 10 and up.
  • Always numerals with units of measure, versions, percentages, ports, HTTP codes, and UI values: 5 GB, 3%, port 8080, HTTP 401, version 2.
  • Don't start a sentence with a numeral; recast the sentence.
  • Numerals in the same category stay consistent within a passage: "5 tokens across 12 workloads," not "five tokens across 12 workloads."

Capitalization and headings

  • Sentence case for all headings and titles.
  • Product, feature, and protocol names keep their official capitalization: OAuth, macOS, iPhone (never at sentence start with lowercase mangled), RFC 8693, Cedar, MCP.
  • UI element names match the interface exactly, capitalized as shown, no quotation marks: Click Save. Choose Settings > Access.
  • internet, web, website, email, online are lowercase, no hyphens.

Technical notation

  • Code font for code: commands, functions, parameters, values the user types, file paths, API names, JSON keys, environment variables. Never quotation marks around code.
  • Placeholders in italic or angle brackets per the doc system's convention, described at first use: keycard tokens create <workload-id>.
  • Don't bend the surrounding sentence grammar around code; write so the code term reads as a noun.
  • Error messages and UI strings quoted exactly as they appear.

Structure conventions for docs

  • Numbered steps for sequences the reader performs; one action per step. A step can carry a short result clause ("Click Save. The policy takes effect immediately.").
  • Conventional doc headings are correct here, not slop: Prerequisites, Installation, Configuration, Troubleshooting, Reference.
  • Notes and warnings sparingly, and only when skipping the information causes failure or data loss.
  • Consistency beats variety in docs. The base deslop rules against parallel structure and uniform rhythm relax inside procedural content: steps, parameter tables, and reference entries should be parallel and predictable. Keep the variety rules for conceptual and overview prose.

Source: SKILL.md on GitHub

Skill behaviors

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

Third-party checks

1 warning17d3 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill is a writing style guide designed to remove common AI writing patterns. It includes a Python script for automated slop detection and references the official Apple Style Guide. No security issues were detected.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at 70237e1. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 weeks ago

README badge

README badge for kmaida/deslop-skills/deslop-writing