palimpsest-ai-writing

Palimpsest AI Writing Guidance

Purpose

This skill guides the AI when writing or editing articles for the Palimpsest writing plugin. It ensures consistent quality, proper use of MDX features, and effective diff visualization.

Before You Write: Determine Direction

Always clarify these four points before generating content:

1. Topic and scope — What is the article about? What is explicitly out of scope?
2. Target audience — Technical depth, assumed knowledge, language preference
3. Tone and style — Formal, casual, tutorial, reference, narrative?
4. Structure — Estimated sections, need for diagrams, code examples

If any of these are unclear, ask the user. Do not start writing with an ambiguous direction.

Prefer MDX Components Over Plain Markdown

Palimpsest articles are MDX, not plain Markdown. Leverage this:

• Use JSX for callouts, asides, and styled containers instead of plain blockquotes

  <div className="p-4 bg-amber-50 border-l-4 border-amber-400 rounded-r-md">
    <p className="text-amber-800 font-medium">Note</p>
    <p className="text-amber-700 text-sm mt-1">Important clarification here.</p>
  </div>
  

• Use inline JSX for interactive-looking elements — badges, labels, styled spans

• Reference src/mdx-components/CLAUDE.md for the full list of available components and their usage patterns

When to Use Components vs. Plain Markdown

Use plain Markdown	Use MDX components
Standard paragraphs	Callout boxes, warnings, tips
Simple lists	Interactive or styled lists
Basic code blocks	Code blocks with custom styling
Standard headings	Headings with anchor links or badges
Blockquotes	Styled alert/notice containers

Built-in Mermaid Support

Mermaid diagrams are natively supported. Use fenced mermaid code blocks:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Mermaid Best Practices

• Keep diagrams simple — Complex diagrams render poorly in diff view
• Use descriptive node labels — Helps readers understand the diagram even in text form
• Prefer graph TD or graph LR for flowcharts — Most widely supported
• Avoid very long diagram source — Diff mode shows raw text; brevity aids readability
• Limit one diagram per section unless the topic demands more

Supported Diagram Types

• graph / flowchart — flowcharts (most common)
• sequenceDiagram — sequence diagrams
• classDiagram — class diagrams
• stateDiagram — state diagrams
• erDiagram — entity-relationship diagrams
• gantt — Gantt charts
• pie — pie charts

Writing Discipline

1. One section at a time — Write, confirm, then proceed. Keeps diffs meaningful.
2. Let the PreToolUse hook handle backups — Never manually copy to previous.mdx
3. Only edit article.mdx — The hook blocks previous.mdx edits
4. Confirm the outline first — Present structure, get approval, then write
5. Test in the browser — After each section, verify rendering at http://localhost:5173/?article={article-id}

Common Pitfalls

Pitfall	Correction
Writing entire article in one tool call	Break into sections, write sequentially
Using plain Markdown everywhere	Use MDX components for richer presentation
Forgetting Mermaid is available	Add diagrams for architecture, flow, or relationships
Complex Mermaid diagrams	Simplify; diff view shows raw text
Not checking src/mdx-components/CLAUDE.md	Review available components before writing
Manual backup to previous.mdx	Let the PreToolUse hook handle it automatically