create-markdown
Generate Markdown files for technical documentation in code repositories. Supports auto table of contents, YAML frontmatter, and full markdown syntax for GitHub-ready content.
Instructions
Create a Markdown (.md) file for technical/code content that lives in a repo. USE for READMEs, API docs, specs, runbooks, changelogs, integration guides, code-heavy content — anything for GitHub/developers. NOT for stakeholder-facing or printable deliverables (→ create-doc / create-pdf) or tabular data (→ create-excel). MARKDOWN SUPERPOWERS: set toc: true to auto-generate an anchor-linked Table of Contents from the H2/H3 headings; pass frontmatter: {...} to emit YAML frontmatter (title, date, tags[]) for static-site generators (Hugo/Jekyll/Astro). Simplest usage: put the whole body in the content string. Supported markdown: '# H1' '## H2' '### H3' headings; 'bold'; 'italic'; 'code'; '- ' or '1. ' lists; '> ' blockquotes; '---' horizontal rule; fenced code blocks; '| a | b |' GitHub tables (with a '|---|---|' separator row); 'text' links. The title becomes the H1, so start content at '## '. Title MUST be specific. Response includes formattingQuality. Use dryRun: true for preview.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| toc | No | Auto-generate an anchor-linked Table of Contents from the H2/H3 headings, inserted under the title. Great for long READMEs/guides. | |
| tags | No | Tags for registry search and discovery. | |
| title | Yes | Specific descriptive title (becomes H1; rejected if generic). | |
| dryRun | No | Return a preview without writing (default: false). | |
| content | No | PREFERRED. The entire document body as ONE markdown string. Supported markdown: '# H1' '## H2' '### H3' headings; '**bold**'; '*italic*'; '`code`'; '- ' or '1. ' lists; '> ' blockquotes; '---' horizontal rule; ```fenced code blocks```; '| a | b |' GitHub tables (with a '|---|---|' separator row); '[text](https://url)' links. The title is added as the document H1 automatically, so start the body at '## '. EXAMPLE content: "## Overview\nThis report covers **Q2** results.\n\n### Highlights\n- Revenue up *18%*\n- Two new markets\n\n| Metric | Value |\n|---|---|\n| MRR | $42k |\n| Churn | 1.2% |\n\n> Next review: July." Use this instead of `paragraphs` unless you need per-paragraph style objects. | |
| docType | No | Tone and depth of the documentation. | |
| category | No | Document category for subfolder organization. | |
| uploadUrl | No | OPTIONAL. HTTPS URL of a receiver that will accept a JSON envelope `{data:base64, filename, mimeType, size}` POSTed with this Bearer auth. If you have NOT been given an uploadUrl in your context, OMIT this field and the tool just writes the file locally. Single-use semantics — do not retry on 4xx. Works with any compliant receiver (CogniRunner attachment-upload web trigger is the reference implementation, but the contract is generic). | |
| clientHint | No | How the response should be shaped. 'interactive' = polished one-line message for end-users (no chatty registry/lineage notes). 'agent' = verbose response with all metadata for AI consumption. 'auto' (default) = detect from input shape or MCP_CLIENT_TYPE env var, falling back to 'agent'. | |
| outputPath | No | Optional. Default: derived from title, placed under docs/<category>/. | |
| paragraphs | No | ALTERNATIVE to `content`. Body as markdown strings or { text, headingLevel } objects. Prefer the single `content` string. | |
| description | No | Brief description stored in the registry. | |
| frontmatter | No | Optional YAML frontmatter emitted at the very top, e.g. { title, date, tags: [...] } — for static-site generators (Hugo/Jekyll/Astro). | |
| uploadFilename | No | OPTIONAL. Filename to put in the upload envelope. Defaults to the local file's basename. Useful when the local file got auto-suffixed (e.g. duplicate prevention) and you want a clean name on the receiver side. | |
| uploadAuthHeader | No | OPTIONAL. Authorization header value for uploadUrl (e.g. 'Bearer abc123'). REQUIRED when uploadUrl is set; ignored otherwise. Never logged. | |
| enforceDocsFolder | No | If false, allow output outside docs/. Default: true. | |
| preventDuplicates | No | If false, allow same-title duplicates. Default: true. |