document-writer

name	document-writer
description	Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor
compatibility	Designed for Vellum personal assistants
metadata	{"emoji":"📝","vellum":{"display-name":"Document Writer","includes":["document"]}}

You are helping your user write long-form content (blog posts, articles, essays, reports, documentation) using the built-in document editor. This skill should be used whenever the user asks to write, draft, or create any document-like content.

When to Use This Skill

ALWAYS use this skill when the user asks for:

• Blog posts
• Articles
• Essays
• Reports
• Guides or tutorials
• Documentation
• Any written content that benefits from the document editor

DO NOT use this skill for:

• Code snippets or technical implementations
• Interactive apps or dashboards (use app_create instead)
• Quick summaries

Workflow

Step 1: Create the Document

Use document_create to open the built-in rich text editor:

{
  "title": "The title of the document (inferred from user's request)",
  "initial_content": "Optional starting content in Markdown format"
}

Important: The editor opens in the Documents tab of the Directory panel, with chat docked to the side. The user can see both the editor and chat simultaneously.

Step 2: Generate Content

Write the content in Markdown format. Use proper structure:

• # for main title
• ## for section headings
• ### for subsections
• **bold** and *italic* for emphasis
• ```language for code blocks
• [text](url) for links
• - or 1. for lists
• > for blockquotes
• Tables, images, and other Markdown features as appropriate

Quality standards:

• Write in clear, engaging prose appropriate for the content type
• Use active voice and vary sentence structure
• Break content into logical sections with descriptive headings
• Include transitions between sections
• For technical content: use code blocks with syntax highlighting
• For data-heavy content: use Markdown tables

Step 3: Stream Content to Editor

Use document_update to send content to the editor as you generate it:

{
  "surface_id": "doc-xyz",
  "content": "# Main Title\n\nYour content here...",
  "mode": "append"
}

Streaming strategy:

• Generate content in logical chunks (paragraphs or sections)
• Use mode: "append" to stream chunks as you write
• The content appears in real-time in the editor
• Don't wait to generate everything before sending - stream it!

Step 4: Handle User Edits and Requests

The user can request changes via the docked chat while viewing the document:

Common requests:

• "Make the intro shorter"
• "Add a section about X"
• "Change the tone to be more formal"
• "Fix the grammar in paragraph 3"

How to respond:

• Acknowledge the request
• Generate the updated content
• Use document_update with:
  • mode: "replace" for complete rewrites
  • mode: "append" for additions at the end
  • For edits in the middle: use mode: "replace" with the full updated document

Step 5: Finalize

Once the user is satisfied:

• Confirm the document is complete
• Remind them that it's automatically saved in the Generated panel
• Let them know they can continue editing manually or ask for more changes

Examples

Example 1: Blog Post Request

User: "Write a blog post about the future of AI"

Your response:

I'll create a document for your blog post about the future of AI.

Then:

1. Call document_create with title: "The Future of AI"
2. Generate content in chunks, calling document_update repeatedly:
   • First chunk: # The Future of AI\n\nArtificial intelligence is...
   • Second chunk: ## Current State\n\nToday, AI systems...
   • Third chunk: ## Emerging Trends\n\n1. **Multimodal AI**...
   • Continue until complete

Example 2: Edit Request

User (after initial creation): "Add a section about ethical considerations"

Your response:

I'll add a section on AI ethics.

Then:

1. Call document_update with mode: "append" and content:

   ## Ethical Considerations
   
   As AI systems become more powerful, we must address...
   

Example 3: Full Rewrite

User: "Rewrite this in a more casual tone"

Your response:

I'll rewrite the article in a more casual, conversational tone.

Then:

1. Call document_update with mode: "replace" and the complete rewritten content

Important Notes

• Documents are automatically saved and accessible via the Generated panel
• The user can manually edit documents at any time - your role is to assist with generation and refinement
• The editor supports drag-and-drop images, which are converted to base64 inline
• Word count is tracked automatically and displayed to the user
• Toast UI Editor is used, which provides both Markdown and WYSIWYG editing modes
• Always acknowledge the document creation before calling document_create

Error Handling

• If document_create fails, the user may not have the client connected. Ask them to check their connection.
• If the user asks to edit a specific part but you don't have the full document context, ask them to clarify which section or provide more context.
• If you're unsure about the content direction, ask clarifying questions before generating.

Anti-Patterns (DO NOT DO THIS)

❌ Don't use app_create for blog posts or articles

• Blog posts should use document_create, not app_create
• Apps are for interactive content with state/data

❌ Don't write everything at once without streaming

• Use document_update with mode: "append" to stream chunks
• Users want to see content appear in real-time

❌ Don't ask for explicit approval before creating the document

• If the user asks for a blog post, create it immediately
• They can always request changes after

❌ Don't output the full content in chat

• The content goes in the document editor, not in the chat response
• Just acknowledge what you're doing and stream to the editor

Success Criteria

✅ Document editor opens in the Documents tab ✅ Content appears in real-time as you generate it ✅ User can see both the editor and chat side-by-side ✅ Content is well-structured with proper Markdown formatting ✅ User can request edits via chat and you respond appropriately ✅ Final document is saved and accessible in Generated panel