| 1 | --- |
| 2 | name: markdown-documents |
| 3 | description: Use when creating or editing Markdown documents, notes, reports, briefs, drafts, or other editable writing where Markdown should be the primary artifact format. |
| 4 | version: "1.0.0" |
| 5 | author: "Agent Zero Core Team" |
| 6 | tags: ["markdown", "md", "documents", "writing", "notes", "reports", "briefs", "editor"] |
| 7 | triggers: |
| 8 | - "markdown" |
| 9 | - "md" |
| 10 | - "note" |
| 11 | - "brief" |
| 12 | - "draft" |
| 13 | - "report" |
| 14 | - "editable writing" |
| 15 | allowed_tools: |
| 16 | - text_editor |
| 17 | --- |
| 18 | |
| 19 | # Markdown Documents |
| 20 | |
| 21 | Markdown is the default document format for normal writing, notes, reports, briefs, drafts, and collaborative text work unless the user explicitly asks for a binary office file. When they do ask for a LibreOffice office file, prefer ODF: ODT for Writer, ODS for Spreadsheet/Calc, and ODP for Presentation/Impress. Use DOCX, XLSX, or PPTX only for explicit OOXML compatibility. |
| 22 | |
| 23 | The Editor surface is user-owned UI. Create or update the saved Markdown file, but never open the Editor automatically. Set `open_in_canvas: true` only when the user explicitly asks to open the canvas/Editor; otherwise already-open Editor sessions refresh automatically. Keep the final response to the saved/updated result and path; do not write faux UI action labels such as "Open document" or "Download file", and do not add a note saying the canvas was not opened automatically unless the user explicitly asks about UI behavior. |
| 24 | |
| 25 | ## Workflow |
| 26 | |
| 27 | 1. Decide whether a saved editable artifact is useful. Create one for substantial, reusable, or collaborative writing; do not create one for tiny one-shot edits or answers that can be completed cleanly in chat. |
| 28 | 2. Create Markdown with `text_editor` using `action: "write"` and an explicit `.md` path. |
| 29 | 3. For edits to an existing Markdown file, read first when content matters, then use `patch` for targeted changes or `write` for deliberate full replacement. |
| 30 | 4. Report the saved file path briefly. Do not say it was opened unless the user explicitly opened it. |
| 31 | |
| 32 | Minimal create: |
| 33 | |
| 34 | ```json |
| 35 | { |
| 36 | "tool_name": "text_editor", |
| 37 | "tool_args": { |
| 38 | "action": "write", |
| 39 | "path": "/a0/usr/workdir/Project Brief.md", |
| 40 | "content": "# Project Brief\n\nDraft text here." |
| 41 | } |
| 42 | } |
| 43 | ``` |
| 44 | |
| 45 | Practical rules: |
| 46 | |
| 47 | - Prefer Markdown over ODT/DOCX for writing unless a binary Writer/Word file is explicitly needed. |
| 48 | - Keep agent-only cleanup simple: if the user asks to fix a typo, update the file and finish; do not force a document-editor workflow. |
| 49 | - Use clear headings and Markdown tables when they improve editability. |
| 50 | - The Markdown Editor surface is available through the response file card. |