write-tbp

# 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:

1. **Frame the problem** — Hook the reader with context and tension
2. **Show the insight** — The key idea that makes it work
3. **Walk through the implementation** — Code and explanation, building complexity
4. **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.