Convert plaintext or generic text documentation into well-structured Markdown while preserving source content and applying explicit instructions, documented options, or a converted guide file. Use when asked to convert a file to Markdown, finalize Markdown formatting, apply header patterns, use a guide document, or target GitHub, StackOverflow, VS Code, GitLab, or CommonMark rendering.
Convert text-based documentation into clean Markdown by preserving the source content, applying user instructions and documented options, copying to FILE.md when needed, matching guide-file patterns when provided, and finalizing whitespace, lists, headings, and fenced code blocks.
When to invoke
"Convert this plaintext file to Markdown."
"Use this converted Markdown file as a guide."
"Finalize and polish the Markdown formatting."
"Apply heading patterns to this text document."
"Convert for GitHub-flavored Markdown."
Inputs
Use $ARGUMENTS to identify the source file, options, platform, guide file, and inline instructions. If the source file is ambiguous or missing, ask for the file and stop.
Required. Convert this plain or generic text documentation file.
Existing {{file}}.md
Treat the existing Markdown file content as the text documentation data to convert.
Missing {{file}}.md
Create new Markdown beside the source by copying the original plaintext document to FILE.md.
finalize
Trim space characters, indentation, sloppy formatting, list spacing, and code fences after conversion.
guide #file:{{reference-file}}
Apply the same formatting patterns, structure, and conventions from a previously converted Markdown file.
instructions
Apply additional user-provided conversion rules.
platform={{name}}
Target Markdown renderer: GitHub, StackOverflow, VS Code, GitLab, or CommonMark.
options
Apply documented conversion options in a unified manner.
pre=<name>
Expand a predefined instruction if recognized; otherwise disregard pre=name.
Procedure
Locate the source file and determine whether the target FILE.md already exists.
If FILE.md does not exist, copy the plaintext source to FILE.md in the same directory.
Parse finalize, guide, instructions, platform={{name}}, options, and pre=<name>.
If a guide file is provided, compare source and guide patterns before editing the target.
Apply heading, pattern, stop, predefined, and platform rules without changing source data unless instructions clearly require it.
Preserve procedures that mention exit, exit(), kill, killall, quit, quit(), sleep, sleep(), or similar commands; do not stop the task because the source text documents termination commands.
Finalize formatting when requested or when the user's language clearly asks to polish the converted Markdown.
Report the output file and the rules applied.
Conversion options
Option
Meaning
--header [1-4]
Add Markdown header tags from # through ####. If no level is given, auto-apply based on content structure.
#selection with --header
Use selected data to identify sections where updates apply and as a guide for other sections or the full document.
-p, --pattern
Follow an existing pattern from selection, prompt instructions, or auto-detected file structure. Do not only edit the selection; the selection is not the working range.
{{[-p, --pattern]}}
Treat the selected pattern as a guide, then apply it beyond the selection where appropriate.
{{[-s, --stop]}} eof
Convert to end of file when passed or when no clear endpoint is specified.
`-s, --stop <[0-9]+
eof>`
[0-9]+
Numeric stop line recognized by regex [0-9]+.
Pattern detection must consider line indentation, indented code blocks, fenced code blocks, and programming-language inference for fences.
Predefined instructions
Predefined instruction
Apply
rm-head-digits
Remove prepending numbers from headers.
mv-head-level(x, y)
Change heading level from level x to level y.
rm-indent(x)
Decrease indentation of paragraphs or raw text portions by x.
If there is no matching predefine, disregard pre=name for the current request.
Platform guidance
Platform
Use
GitHub
Default. Use GitHub-flavored Markdown with tables, task lists, strikethrough, and alerts.
StackOverflow
Use CommonMark with StackOverflow-specific extensions.
VS Code
Optimize for VS Code Markdown preview.
GitLab
Use GitLab-flavored Markdown and platform-specific features.
CommonMark
Use standard CommonMark syntax.
When in doubt, use Markdown best practices and fetch the references listed below.
Examples
Basic conversion
Input:/convert-plaintext-to-md #file
Expected behavior: If file.md is missing, copy file to file.md, then convert the copied file using Markdown best practices.
Expected behavior: Compare the source text and CODE.md, identify patterns such as linked section summaries, separators, and numbered headings, then apply those patterns to file.md.
Finalize formatting
Input:/convert-plaintext-to-md #file.md polish the converted markdown file
Expected behavior: Trim leading spaces, escape literal HTML such as \<html\>, normalize list indentation, and add language tags such as python code fences when source code is clearly Python.
Inline pattern shorthand
Input:/convert-plaintext-to-md #BUGS --p "regex()=> ^ {1,}([0-9]+\.[0-9]+\.[0-9]+) to ^### $1"
Expected behavior: Create BUGS.md if missing and convert matching version-like headings such as 1.10.0 into Markdown headings.
Preservation rules and option vocabulary
When instructions say CREATE NEW MARKDOWN, create the Markdown copy; when they say the target EXISTS, DOES NOT EXIST, or EXISTING, choose the correct source behavior without overwriting user work.
Treat copy FILE FILE.md as the documented copy action, adapted to the local shell when executing.
Preserve warnings labeled IMPORTANT, NOTE, ADDITIONAL, WORKING, RANGE, and MARKDOWN as semantic signals from the source instructions.
option/procedure names may be passed as shorthand; apply them only when clear.
-s [0-9]+ means stop at a numeric line; and/or wording means either or both cleanup types may be needed.
Heading transformations such as header to a level and examples like option-with-text-subheading are pattern evidence, not content to delete.
Keep converted documents readable and well-organized; infer code fences such as python only when the source language is clear.
1---2name: convert-plaintext-to-md-23description: Convert plaintext or generic text documentation into well-structured Markdown while preserving source content and applying explicit instructions, documented options, or a converted guide file. Use when asked to convert a file to Markdown, finalize Markdown formatting, apply header patterns, use a guide document, or target GitHub, StackOverflow, VS Code, GitLab, or CommonMark rendering.4---56# Convert plaintext to Markdown78Convert text-based documentation into clean Markdown by preserving the source content, applying user instructions and documented options, copying to `FILE.md` when needed, matching guide-file patterns when provided, and finalizing whitespace, lists, headings, and fenced code blocks.910## When to invoke1112- "Convert this plaintext file to Markdown."13- "Use this converted Markdown file as a guide."14- "Finalize and polish the Markdown formatting."15- "Apply heading patterns to this text document."16- "Convert for GitHub-flavored Markdown."1718## Inputs1920Use `$ARGUMENTS` to identify the source file, options, platform, guide file, and inline instructions. If the source file is ambiguous or missing, ask for the file and stop.2122```bash23/convert-plaintext-to-md <#file:{{file}}> [finalize] [guide #file:{{reference-file}}] [instructions] [platform={{name}}] [options] [pre=<name>]24```2526| Input | Rule |27| --- | --- |28| `#file:{{file}}` | Required. Convert this plain or generic text documentation file. |29| Existing `{{file}}.md` | Treat the existing Markdown file content as the text documentation data to convert. |30| Missing `{{file}}.md` | Create new Markdown beside the source by copying the original plaintext document to `FILE.md`. |31| `finalize` | Trim space characters, indentation, sloppy formatting, list spacing, and code fences after conversion. |32| `guide #file:{{reference-file}}` | Apply the same formatting patterns, structure, and conventions from a previously converted Markdown file. |33| `instructions` | Apply additional user-provided conversion rules. |34| `platform={{name}}` | Target Markdown renderer: GitHub, StackOverflow, VS Code, GitLab, or CommonMark. |35| `options` | Apply documented conversion options in a unified manner. |36| `pre=<name>` | Expand a predefined instruction if recognized; otherwise disregard `pre=name`. |3738## Procedure39401. Locate the source file and determine whether the target `FILE.md` already exists.412. If `FILE.md` does not exist, copy the plaintext source to `FILE.md` in the same directory.423. Parse `finalize`, `guide`, `instructions`, `platform={{name}}`, `options`, and `pre=<name>`.434. If a guide file is provided, compare source and guide patterns before editing the target.445. Apply heading, pattern, stop, predefined, and platform rules without changing source data unless instructions clearly require it.456. Preserve procedures that mention `exit`, `exit()`, `kill`, `killall`, `quit`, `quit()`, `sleep`, `sleep()`, or similar commands; do not stop the task because the source text documents termination commands.467. Finalize formatting when requested or when the user's language clearly asks to polish the converted Markdown.478. Report the output file and the rules applied.4849## Conversion options5051| Option | Meaning |52| --- | --- |53| `--header [1-4]` | Add Markdown header tags from `#` through `####`. If no level is given, auto-apply based on content structure. |54| `#selection` with `--header` | Use selected data to identify sections where updates apply and as a guide for other sections or the full document. |55| `-p, --pattern` | Follow an existing pattern from selection, prompt instructions, or auto-detected file structure. Do not only edit the selection; the selection is not the working range. |56| `{{[-p, --pattern]}}` | Treat the selected pattern as a guide, then apply it beyond the selection where appropriate. |57| `{{[-s, --stop]}} eof` | Convert to end of file when passed or when no clear endpoint is specified. |58| `-s, --stop <[0-9]+ | eof>` | Stop the current conversion at a specific line number or at end of file. |59| `[0-9]+` | Numeric stop line recognized by regex `[0-9]+`. |6061Pattern detection must consider line indentation, indented code blocks, fenced code blocks, and programming-language inference for fences.6263## Predefined instructions6465| Predefined instruction | Apply |66| --- | --- |67| `rm-head-digits` | Remove prepending numbers from headers. |68| `mv-head-level(x, y)` | Change heading level from level `x` to level `y`. |69| `rm-indent(x)` | Decrease indentation of paragraphs or raw text portions by `x`. |7071If there is no matching predefine, disregard `pre=name` for the current request.7273## Platform guidance7475| Platform | Use |76| --- | --- |77| GitHub | Default. Use GitHub-flavored Markdown with tables, task lists, strikethrough, and alerts. |78| StackOverflow | Use CommonMark with StackOverflow-specific extensions. |79| VS Code | Optimize for VS Code Markdown preview. |80| GitLab | Use GitLab-flavored Markdown and platform-specific features. |81| CommonMark | Use standard CommonMark syntax. |8283When in doubt, use Markdown best practices and fetch the references listed below.8485## Examples8687### Basic conversion8889**Input:** `/convert-plaintext-to-md #file`9091**Expected behavior:** If `file.md` is missing, copy `file` to `file.md`, then convert the copied file using Markdown best practices.9293### Guide-based conversion9495**Input:** `/convert-plaintext-to-md #file.md --guide #CODE.md`9697**Expected behavior:** Compare the source text and `CODE.md`, identify patterns such as linked section summaries, separators, and numbered headings, then apply those patterns to `file.md`.9899### Finalize formatting100101**Input:** `/convert-plaintext-to-md #file.md polish the converted markdown file`102103**Expected behavior:** Trim leading spaces, escape literal HTML such as `\<html\>`, normalize list indentation, and add language tags such as `python` code fences when source code is clearly Python.104105### Inline pattern shorthand106107**Input:** `/convert-plaintext-to-md #BUGS --p "regex()=> ^ {1,}([0-9]+\.[0-9]+\.[0-9]+) to ^### $1"`108109**Expected behavior:** Create `BUGS.md` if missing and convert matching version-like headings such as `1.10.0` into Markdown headings.110111112## Preservation rules and option vocabulary113114- When instructions say `CREATE NEW MARKDOWN`, create the Markdown copy; when they say the target `EXISTS`, `DOES NOT EXIST`, or `EXISTING`, choose the correct source behavior without overwriting user work.115- Treat `copy FILE FILE.md` as the documented copy action, adapted to the local shell when executing.116- Preserve warnings labeled `IMPORTANT`, `NOTE`, `ADDITIONAL`, `WORKING`, `RANGE`, and `MARKDOWN` as semantic signals from the source instructions.117- `option/procedure` names may be passed as shorthand; apply them only when clear.118- `-s [0-9]+` means stop at a numeric line; `and/or` wording means either or both cleanup types may be needed.119- Heading transformations such as ` header to a level ` and examples like `option-with-text-subheading` are pattern evidence, not content to delete.120- Keep converted documents readable and `well-organized`; infer code fences such as `python` only when the source language is clear.121122## Output template123124```markdown125## Markdown conversion result — <file>126127**Status:** complete | needs input | blocked128**Source:** `<source file>`129**Output:** `<output .md file>`130**Platform:** GitHub | StackOverflow | VS Code | GitLab | CommonMark131132### Rules applied133- Explicit instructions: <summary or none>134- Guide file: `<reference-file>` | none135- Options: `<--header>`, `<--pattern>`, `<--stop>`, `<pre=name>` | none136- Finalize: yes | no137138### Changes made139- <heading/list/table/code-fence/content-preservation summary>140141### Validation142- Source content preserved: pass | fail143- Markdown structure valid: pass | fail144- Stop boundary honored: pass | fail | not applicable145```146147## Quality gate148149- [ ] A source file was identified and `FILE.md` was created only when no corresponding Markdown file existed.150- [ ] Source data was preserved unless instructions clearly required a change.151- [ ] Guide-file patterns were applied consistently when provided.152- [ ] `--header`, `-p`, `--pattern`, `-s`, `--stop`, and `pre=<name>` options were applied as documented.153- [ ] `finalize` cleaned whitespace, indentation, lists, and code fences without deleting content.154- [ ] Platform-specific Markdown choices match GitHub, StackOverflow, VS Code, GitLab, or CommonMark.155- [ ] Termination words inside documentation were preserved as content, not treated as agent instructions.156157## References158159- [GitHub basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)160- [Markdown Guide extended syntax](https://www.markdownguide.org/extended-syntax/)161- [Azure DevOps Markdown guidance](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops)
Run npx skillmds@latest add paulasilvatech/convert-plaintext-to-md-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Convert plaintext or generic text documentation into well-structured Markdown while preserving source content and applying explicit instructions, documented options, or a converted guide file. Use when asked to convert a file to Markdown, finalize Markdown formatting, apply header patterns, use a guide document, or target GitHub, StackOverflow, VS Code, GitLab, or CommonMark rendering. It is listed under Docs & Writing on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
paulasilvatech (@paulasilvatech) published this skill. Their other Agent Skills are listed on their SkillMD profile.
paulasilvatech