Guide · Agent skill
How to use the Convert Plaintext to Markdown agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The convert-plaintext-to-md skill tells an AI agent to restructure a plain text document into clean markdown. It is written for maintainers and technical writers who have old README or plain text files they want to publish in a consistent markdown layout. After this guide you will know what the skill does, how to install it, how to ask for a conversion in plain language, and where its output needs a human check.
Convert Plaintext to Markdowngithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Get the convert-plaintext-to-md ZIP from the page you are reading.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there.
- 4Ask for a conversion. Name your plain text file and describe the markdown result you want.
- 5Add a reference or options if needed. Pass a guide file, a platform, a header level or a predefined instruction to control the output.
- 6Review the output. Read the generated markdown before publishing, since the agent's output may need manual review.
What the skill makes the agent do
When installed, the agent treats a plain text document as something to restructure into markdown. It can follow instructions you give it, a documented set of options, or a previously converted markdown file used as a template.
The skill can add heading levels, apply patterns it finds in the file, trim messy spacing, and target a specific renderer such as GitHub, GitLab or VS Code. The skill describes the conversion process in prose and does not ship any scripts of its own.
- Converts from explicit instructions in your request
- Converts from a documented option or procedure
- Uses a reference markdown file as a formatting template
- Adds header levels with --header [1-4]
- Trims spacing and sloppy formatting when finalize is requested
How to install the convert-plaintext-to-md skill
The skill is distributed as a ZIP from the page you are reading. Download the ZIP and unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for one project.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
You do not need to memorise the command syntax. The source notes that natural language variations are acceptable, so asking the agent in plain words works. Point the agent at the plain text file and say what you want.
The skill's documented command form is shown below. Parameters are optional except for the file itself.
- Convert notes.txt to markdown
- Convert this README.txt to markdown and add level 2 headings
- Convert the plain text file and use OLD.md as a formatting guide
- Polish the converted markdown file to remove extra spaces
/convert-plaintext-to-md <#file:{{file}}> [finalize] [guide #file:{{reference-file}}] [instructions] [platform={{name}}] [options] [pre=<name>]Options, platforms and predefined instructions
The source lists platform targets: GitHub (the default), StackOverflow, VS Code, GitLab and CommonMark. Options include --header [1-4] to add heading tags, and -p, --pattern to follow an existing pattern. The -s, --stop option accepts a line number or eof to limit how far the conversion runs.
Predefined instructions are passed with pre=<name>. The source lists rm-head-digits, mv-head-level(x, y) and rm-indent(x). If the name does not match a predefined instruction, the skill ignores it.
- platform=GitHub (default), StackOverflow, VS Code, GitLab, CommonMark
- --header 1 to 4 adds # through ####
- -s eof or -s [line number] sets where to stop
- pre=rm-head-digits removes leading numbers from headings
- pre=mv-head-level(x, y) changes heading level x to y
- pre=rm-indent(x) decreases indentation by x
Examples of what the agent does
In the basic case, the source shows the agent noticing that no matching file.md exists, copying the plain text file to file.md, and then applying markdown conventions to the copy. When a reference file is supplied, the agent compares the two files, identifies the pattern, and applies the same heading and list style to the new document.
When you ask to finalize, the agent scans the whole document and trims stray spaces, indentation and sloppy list formatting.
/convert-plaintext-to-md #file.md --guide #CODE.mdWhat it needs, and safety notes
The source lists no required dependencies. The skill does not run scripts and does not use the network. Its only file in the package is SKILL.md.
The skill's text does mention using a fetch tool to retrieve reference URLs, so check what the agent fetches if that matters to you. Review any converted file before you publish it.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for better results
Give a reference file when you want consistency across a batch of documents. Name the platform you publish to, because renderers differ. Keep the original text file, since the skill copies it to create the markdown version.
- Use a reference file for batches
- State the target platform explicitly
- Run finalize as a separate pass and review the result
- Keep the original plain text file as a backup
What people use it for
- Turning an old plain text README into a GitHub-ready markdown file
- Converting a batch of text documentation files to one shared layout using a reference file
- Cleaning up spacing and list indentation in a converted file with finalize
- Adding consistent heading levels to a document with --header
Frequently asked questions
How do I install the convert-plaintext-to-md skill?
Download the ZIP from the page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What does the convert-plaintext-to-md skill require?
The source lists no required dependencies. It does not run scripts and does not use the network, and its only file is SKILL.md.
Is the convert-plaintext-to-md skill free?
The skill is licensed under MIT, as stated on this page. Check the licence text in the source repository for the full terms.
Can I use this skill on Markdown files that already exist?
The skill is built for plain text input. For documents that are already markdown and need only minor edits, the source suggests a different approach is more suitable.
Which platforms does the output target?
You can set platform=GitHub (the default), StackOverflow, VS Code, GitLab or CommonMark. Choose the one where your file will be rendered.
Is the output always correct?
No. The agent's output may need manual review, and very large or highly structured files may be better handled by a dedicated converter tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain old README or plain text files and want them in consistent markdown, especially with a reference file to copy formatting from. Pick a dedicated converter tool for very large or highly structured files, or if you need a repeatable, auditable process, and always review the agent's output before publishing.
Download the skill