gpsaggese/helpers / .claude/skills/markdown.simplify
markdown.simplify
VerifiedSimplify markdown text with ASD-STE100 and plain language, keep format
Goal
- Rewrite the text of a markdown file in ASD-STE100 Simplified Technical English and ISO 24495-1 plain language
- Change only the words inside each line
- Keep the format of the file: headers, bullets, nesting, bold and italic tags, code blocks, tables, links, and blank lines
- Write the result back to the same file
Conventions
- Follow the markdown conventions in
.claude/skills/markdown.rules.md - Follow the bullet-list conventions in
.claude/skills/text.rules.md
Workflow
Save the Original
- Copy the input file
<FILE>to a temporary file<ORIG_FILE>> cp <FILE> <ORIG_FILE> - Use
<ORIG_FILE>in# Verification, then delete it
Find What to Keep
- Mark every element that the rewrite must not change
- Headers: text and level
- Fenced code blocks: the whole block, including the language tag
- Inline code, URLs, link targets, file paths, and math
- Tables: structure and separator rows
- YAML front matter and HTML comments
- Proper names, product names, and technical terms
- Technical names are allowed in ASD-STE100 even if they are not in the dictionary
- Bold labels at the start of a bullet (e.g.,
**Goal**)- Simplify the text after the label
- Quoted text and bibliographic references
Rewrite the Text
- Process the file line by line, bullet by bullet
- Rewrite the text of each bullet or paragraph in place with the writing rules below
- Keep one bullet as one bullet
- Never merge two bullets
- Never split a bullet into two bullets
- Never turn a bullet into a paragraph or a paragraph into a bullet
- Keep the nesting level and the list marker of every bullet
- Keep
-as-,1.as1., and- [ ]as- [ ]
- Keep
- Keep the order of bullets, paragraphs, and sections
- Keep the information
- Do not add facts, do not remove facts, and do not change numbers
- Delete a word only if the word has no meaning (filler, vague modifier)
Wrap the Lines
- Wrap the rewritten prose at 85 characters
- Indent the continuation lines to align with the text after the list marker
- Do not change the wrapping of lines that the rewrite did not touch
Clean Up
- Delete
<ORIG_FILE>
Writing Rules
One Word, One Meaning
- Use only the primary, literal meaning of a word
- Use the same word for the same concept in the whole file
- Never use a synonym for variety
- Bad: "Start the server. Launch the service. Boot the daemon."
- Good: "Start the server. Start the service. Start the daemon."
- Replace an idiom or a metaphor with a literal statement
- Bad: "This step is the backbone of the pipeline."
- Good: "The pipeline needs this step."
Active Voice
- Write every sentence in active voice
- Bad: "The cache is cleared by the script."
- Good: "The script clears the cache."
- Start a step with a direct imperative verb
- Bad: "The valve should be turned."
- Good: "Turn the valve."
- Keep the passive voice only if the actor is unknown and no active form exists
Sentence Length
- Keep a procedural step under 20 words
- Keep a descriptive sentence under 25 words
- Write one instruction per sentence
- Bad: "Open the file, delete the header, and save the result."
- Good: "Open the file. Delete the header. Save the result."
- Do not use semicolons
- Write two sentences instead
- Write contractions in full
- E.g., write "do not", not "don't"
- Split a long sentence inside the same bullet
- Keep the sentences in one bullet
- Never create a new bullet to hold the split part
Paragraph Length
- Keep a paragraph at 6 sentences or fewer
- If a prose paragraph has more than 6 sentences, split it with one blank line
- Do this only for a prose paragraph
- Do not split a bullet into paragraphs
- Keep an existing list as a list
- Do not convert an inline series (e.g., "A, B, and C") into a new bullet list
- Do not convert a bullet list into prose
Noun Clusters
- Never stack more than three nouns without a preposition
- Bad: "main pump control panel assembly"
- Good: "control panel for the main pump"
- Rewrite a longer cluster with prepositions or a relative clause
- Bad: "user session timeout error handler"
- Good: "handler for the error when the user session times out"
No Filler
- Delete a conversational opening
- E.g., "Let's take a look at", "In this section, we will"
- Delete a vague modifier
- E.g., "very", "quite", "somewhat", "various", "a number of"
- Delete a hedge
- E.g., "it seems that", "might possibly", "in some cases"
- Replace a long phrase with a short one
- Bad: "in order to"
- Good: "to"
Constraints
- Do not change the format of the file
- The count and the order of headers, bullets, code blocks, and tables must stay the same
- Do not change the meaning of a sentence to make it shorter
- If a rewrite loses information, keep the original sentence
- Do not rewrite a line that already follows the writing rules
- Write only the file. Do not add a summary, a comment, or a note to the file
- Do not commit the changes
Examples
- Bad (changes the format: merges the sub-bullets into one line)
becomes- **Cache** - The cache is cleared by the script when it is started - Various settings can be configured in order to change the size- **Cache**: The script clears the cache at start and you can set the size. - Good (changes only the words: same bullets, same nesting, same label)
- **Cache** - The script clears the cache at start - Set the size in the config file
Verification
- The structure is unchanged
- The markers of headers, bullets, and fences are the same as in
<ORIG_FILE> - The command prints no output when the structure is the same
> diff \ <(grep -oE '^ *(#+ |[-*+] |[0-9]+\. |```)' <ORIG_FILE>) \ <(grep -oE '^ *(#+ |[-*+] |[0-9]+\. |```)' <FILE>)
- The markers of headers, bullets, and fences are the same as in
- Fenced code blocks, inline code, URLs, and headers are unchanged
- No sentence has more than 25 words
- No step has more than 20 words
- No paragraph has more than 6 sentences
- No line is longer than 85 characters, except in code blocks and tables
- The output is in the same file
<FILE> -
<ORIG_FILE>is deleted
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |