Write technical blog post

This skill covers how to write technical blog posts about tldraw's implementation details.

Process

1. Create the workspace

Create an assets folder for this topic:

.claude/skills/write-tbp/assets/<topic>/ ├── research.md # Gathered context and notes └── draft.md # The blog post draft

Use a short, kebab-case name for the topic (e.g., scribbles , arrow-routing , dash-patterns ).

2. Research the topic

Use an Explore subagent to gather all relevant information:

Task (subagent_type: Explore, thoroughness: very thorough)

Find all code, documentation, and context related to [TOPIC] in the tldraw codebase.

Look for:

• Implementation files in packages/editor and packages/tldraw
• Type definitions in packages/tlschema
• Related examples in apps/examples
• Any existing documentation in apps/docs/content
• Tests that reveal behavior
• Comments explaining why things work the way they do

For each relevant file, note:

• What it does
• Key functions/classes
• Interesting implementation details
• Any "why" comments or non-obvious decisions

Output a comprehensive summary of how [TOPIC] works. This document will be read by another agent. No need to over-optimize for human readability.

Save the research output to assets/<topic>/research.md .

3. Identify the interesting angle

Before writing, answer these questions from the research:

• What problem does this solve? Not "what does it do" but "what would go wrong without it?"

• What's surprising or unintuitive? The obvious approach that doesn't work, or the hidden complexity.

• What's the key insight? The "aha" that makes the solution work.

• What did we try first? Any journey or iteration visible in the code or comments.

If you can't find an interesting angle, the topic may not be suitable for a technical blog post.

4. Write the draft

Create assets/<topic>/draft.md following the blog-guide structure:

• Frame the problem — Hook the reader with context and tension

• Show the insight — The key idea that makes it work

• Walk through the implementation — Code and explanation, building complexity

• Wrap up — Where it lives, tradeoffs, links to files

Target 800-1500 words.

5. Self-evaluate

Check the draft against the blog-guide checklist:

• Opening — Does it frame a problem before diving into solution?

• Insight — Is there a clear "aha" moment or key idea?

• Specificity — Is this grounded in tldraw's actual implementation?

• Code — Do examples build understanding, not just show syntax?

• Tone — Warm and personal, but not rambling?

• Links — Points to actual code in the repo?

• Length — Appropriate depth for the topic?

Revise the draft to address any gaps.

6. Output

Present the final draft to the user for review. The draft remains in assets/<topic>/draft.md until the user is satisfied, at which point they can move it to the appropriate location.

References

• Style guide: See ../shared/blog-guide.md for voice, tone, and structure.

• Writing guide: See ../shared/writing-guide.md for general writing conventions.