Skip to content

jackson2w/claude-code-skills / better-documents

better-documents

Verified

Apply communication best practices when generating or reviewing any document, presentation, report, memo, slide deck, proposal, or email. Use this skill when asked to write, create, draft, or generate a document or presentation — apply the principles at generation time, not as an afterthought. Also use when asked to "review my doc," "look at this deck," "does this make sense," "is this clear," "improve this proposal," "check this before I send it," "make this more effective," or any request to evaluate whether a document will land with its audience. Use this skill even when the request seems minor — a "quick look" or a "short memo" is exactly when these principles matter most.

FileKindSize
BLOG-NOTES.mdmarkdown4.5 KB
LICENSEother34.3 KB
README.mdmarkdown3.2 KB
SKILL.mdskill md12.9 KB
document-design.mdmarkdown6.5 KB

document-design.md

View on GitHub
# Document Design Guidelines

*Distilled from [Make better documents.](https://www.anildash.com/2024/03/10/make-better-documents/) by Anil Dash. Original post © Anil Dash.*

---

## 1. Know your audience and your goals

Before writing a single word, answer these:

- **Who is reading this?** What's their day like? What else is competing for their attention?
- **What do they need from this document?** What question are they trying to answer?
- **What context are you assuming they have?** Is your framing culturally and historically appropriate for them?
- **Are you asking for something?** If so, make it unmistakably clear. Lay out options with explicit pros and cons.
- **Is a decision required?** Name the stakeholders, surface the counter-arguments, and state the timeline — and explain *why* that timeline matters to *them*, not just to you.

> The most common failure: starting from deep inside your own head rather than from your reader's perspective. Don't open with a recitation of your own anxieties or insecurities.

**The right structure:** Start from common ground → name the shared goal → acknowledge where you already are on that path → identify what remains → close by asking for their help.

---

## 2. Stop over-formatting

Most formatting is noise. Default to restraint.

- **Bold**: use sparingly, for genuinely important things.
- **Italics**: use rarely, for emphasis.
- **Underline**: don't. It signals a clickable link and confuses readers.
- **Color**: pick one (maybe two, max). Use shades if needed. Apply across the *entire* document, including charts.
- **Fonts**: one, or two at most.
- **Borders**: remove them. Use white space instead (see below).

Combining bold + italic + underline + color on the same text communicates only one thing: you don't know what's important.

---

## 3. Use white space

White space does the heavy lifting that over-formatting tries (and fails) to do.

- Give content room to breathe. Increase margins and spacing around headings and sections.
- Use **bullet points** to make content skimmable, force concision, and reveal whether items actually belong in the same category.
- **Avoid filler images.** A blank space is better than a stock photo or clip art that has no specific relevance to your point. Visual noise costs the reader attention.

---

## 4. Learn and use your tools consistently

- Use **styles** (heading levels, paragraph styles) so spacing and formatting are applied uniformly, not manually.
- Inconsistent formatting — different fonts, sizes, or colors across slides or sections — signals to readers that there's a *reason* for the change. They'll spend time looking for meaning that isn't there.
- When pulling in content from other sources (copied slides, embedded charts), do a formatting pass to make everything consistent before sharing.

---

## 5. Sequence by importance, not by creation order

- Front-load key points. Don't make readers dig.
- Within a page or slide, most important information goes **at the top**.
- If you're *not* ordering by importance (e.g., chronologically or by category), **say so explicitly** in the document — otherwise half your audience will be lost.

---

## 6. State your conclusion first

This is not a murder mystery. Don't build to a dramatic reveal.

- Open with the key conclusion, request, or question.
- Then walk through the supporting logic and context.
- Restate the conclusion at the end to drive toward your goal.

**Critical:** Put the important points *on the page*. Do not plan to "speak to" the most vital information verbally alongside the document. If a key stakeholder is absent or distracted, they'll read the document and miss your point entirely. Don't bury central conclusions in speaker notes or appendices.

---

## 7. Give people wayfinding

Help readers know where they are in the story.

- A brief outline or progress indicator at the start (or recurring throughout a long document) reduces cognitive load.
- If you have distinct sections, assign them a color from your limited palette and use it *consistently* — this builds a mental map.
- **Summarize data in chart/table titles.** Don't make readers interpret a chart cold. A short "here's what this shows" in the title sets the right frame before they engage with the numbers.

---

## 8. Ask answerable questions

If your document drives toward a decision, frame questions so they can actually be answered.

- ❌ "How can we do better?" — philosophical, not actionable
- ✅ "Do we go with Option A (higher cost, faster) or Option B (lower cost, slower)?" — a choice with defined tradeoffs

Constrained choices produce constructive responses. Open-ended questions produce paralysis or deflection.

---

## 9. Close by restating mission and shared goals

End by reminding your audience of alignment — on purpose, on values, on what you're collectively working toward.

- If you're persuading: it gives them psychological permission to trust your intent.
- If you're deciding: it gives them confidence to move forward.
- If you're informing: it invites clarifying questions from a place of shared investment.

---

## 10. Name files and documents well

The title of a document is itself a critical piece of information.

- **Think about how your audience will search for it later.** If they're at another org, they'll search by your name/org — include it. If you're on the same team, include the project and goal.
- **Include the date and topic in the filename.** This helps recipients know if they have the latest version without opening it.
- **For versions:** dates in the filename beat sequential numbers. `_final_final` is not a versioning strategy.
- **For meetings:** name the invite after the purpose of the conversation, not after the participants. "Meeting with Sam" is useless on Sam's calendar.

---

## Quick reference

| Do | Don't |
|---|---|
| Use white space to separate content | Add borders to tables and sections |
| State your conclusion at the top | Build to a reveal |
| Summarize charts in their titles | Make readers interpret data cold |
| Use one consistent color palette | Apply multiple colors for variety |
| Put key decisions in the document | Plan to "speak to" them verbally |
| Name files with date + topic + context | Use `v2_final_FINAL` |
| Use bullets to force concision | Use dense prose where lists work better |
| Apply heading styles for consistency | Manually format titles on each slide |

---

*Source: [anildash.com/2024/03/10/make-better-documents](https://www.anildash.com/2024/03/10/make-better-documents/) — last accessed May 2026.*
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall