1. Mental model — three surfaces, one toolbox​

You have three ways to reach Claude. Pick based on the task, not habit.

Key insight: Claude Code's memory is a different system from claude.ai/Cowork memory. They do not share a profile. You set them up separately. Skills, by contrast, are portable — write a skill once and it can work across all three surfaces.

2. Memory — stop repeating yourself​

Memory is what carries context across sessions so you don't re-introduce your stack, conventions, and preferences every time.

2A. Claude Chat / Cowork memory​

These share the same memory system on claude.ai.

Turn it on (2 minutes):

1. Go to Settings → Capabilities.
2. Enable "Search and reference chats" — lets Claude look back through past conversations.
3. Enable "Generate memory from chat history" — lets Claude extract and store what matters (your role, stack, recurring projects, preferences).
4. (Optional) Import memory from ChatGPT / Gemini / Grok if you've built context elsewhere — Settings → Capabilities → Memory Import. Processing takes ~24 hours.

How it behaves:

• A synthesis of key insights is rebuilt roughly every 24 hours and injected into every new standalone chat.
• Project memory is separate. Each Cowork/Chat project has its own isolated memory space and project summary. Context from your "Payments Service" project won't bleed into your "Mobile App" project. This is exactly what you want as an engineer juggling repos.
• It deliberately stores work context (role, tools, conventions, project details) and avoids secrets like passwords or account numbers.

Managing it:

• Ask directly: "What do you remember about me?" to audit.
• Say "Remember that we migrated from REST to gRPC" or "Forget the old deploy process" mid-conversation.
• Pause (keeps memories, stops creating new ones) vs Reset (permanent wipe, including project memories) in Settings.
• Use Incognito chat (ghost icon) for one-off conversations you don't want saved.
• Do a monthly memory check-up: scan Settings, delete anything stale.

Project instructions vs. memory: In each Cowork project, also fill in the project's custom instructions field. Memory is learned; instructions are declared. Put hard rules there (e.g., "This repo uses pnpm, Vitest, and conventional commits. Never edit files in /generated.").

⚠️ Confidentiality note: don't store client-identifiable or regulated data (HIPAA, privileged, etc.) in memory. Use Incognito/temporary chats for those.

2B. Claude Code memory — CLAUDE.md (highest ROI for engineers)​

If you adopt one new habit from this guide, make it this. CLAUDE.md becomes part of Claude's system prompt and loads automatically at the start of every Code session. One hour writing a good one saves countless hours of re-explanation.

The hierarchy (all levels concatenate; more specific files effectively win on conflicts):

How loading works (important nuances):

• Claude walks up the directory tree from where you launch, loading every CLAUDE.md it finds.
• Nested/subdirectory CLAUDE.md files (e.g., packages/auth/CLAUDE.md) are not loaded at launch. They load on demand only when Claude reads a file in that subtree. This keeps startup lean — great for monorepos.
• The root project CLAUDE.md survives /compact (Claude re-reads it from disk). Nested ones reload only when next touched. If an instruction "disappeared," it was probably given only in chat, never written to a file.

What to put in it (keep it tight — aim for ~80–120 lines, hard ceiling ~200): Models reliably follow ~150–200 instructions; Code's own system prompt eats ~50. Every wasted line competes with the rules that matter. Include:

• Build / test / lint / migration commands (exact, runnable)
• Tech stack and key conventions ("2-space indent", "early returns over nesting >3 deep")
• Project layout ("API handlers live in src/api/handlers/")
• "Always do X" rules and a Human Approval Required checklist for risky actions
• Mark critical rules with IMPORTANT: or YOU MUST

What to leave out: personality fluff ("be a senior engineer", "think step by step" — it already does), anything Claude learns in one session, and any secrets/tokens.

Authoring shortcuts:

• Type # at the start of an input → Claude prompts you to save that line to a memory file.
• Run /memory → opens memory files in your editor and shows exactly what's loaded (your #1 debugging tool when Claude "ignores" a rule — often the rule lives in a nested file that hasn't loaded yet).
• Use @path/to/file.md imports to modularize (e.g., @docs/coding-standards.md). Note: imports organize but don't save context — imported files still load at launch. Don't import your whole docs site.

Path-scoped rules (.claude/rules/): For instructions that should only apply to certain files, put them in .claude/rules/ with path globs (e.g., src/**/*.{ts,tsx}). They load only when Claude works on matching files — keeps API rules out of context during frontend work.

Auto memory: Claude Code also writes its own learnings (from your corrections and preferences) into a MEMORY.md, loaded at session start. Treat the split as: CLAUDE.md = your requirements, auto memory = what Claude observed about you. Browse/edit it via /memory.

Pro tip: Commit CLAUDE.md to git. git checkout CLAUDE.md lets you experiment with instructions and roll back.

3. Skills — turn repeated workflows into reusable expertise​

A Skill is a folder containing a SKILL.md (instructions + metadata) and optional scripts/templates. Claude loads only the name+description at startup, then reads the full skill only when relevant (progressive disclosure). Unlike a prompt (one-off) or CLAUDE.md (always-on background), a skill is on-demand expertise Claude reaches for when the task matches.

Think: CLAUDE.md is for "nouns" (what/where things are, always loaded). Skills are for "verbs" (how to perform a specific procedure, loaded when triggered).

3A. Pre-built skills (use immediately, zero setup)​

Anthropic ships skills for PowerPoint, Excel, Word, and PDF. They already work behind the scenes when you ask Claude to create those documents — no action needed. (Useful when you need to generate a report, design doc, or spreadsheet from your data.)

3B. Where custom skills live, per surface​

A skill authored once works across surfaces with minimal change, as long as the environment provides what it needs.

3C. Anatomy of a SKILL.md​

---
name: pr-description-writer
description: >
  Generates a structured pull-request description from a git diff.
  Use this when the user asks to "write a PR description", "summarize
  my changes for a PR", or prepares to open a pull request.
---

# PR Description Writer

## Instructions

1. Run `git diff main...HEAD` to read the actual changes.
2. Group changes by area (feature, fix, refactor, tests, docs).
3. Produce sections: **Summary**, **Changes**, **Testing**, **Risk/rollback**.
4. Flag any change touching auth, billing, or migrations under **⚠️ Needs review**.
5. Keep it under 300 words. Use imperative mood.

## Examples

- Input: a diff adding rate limiting → output highlights the new middleware,
  config flags, and a testing checklist.

Rules that matter:

• name: lowercase, numbers, hyphens only; max 64 chars; can't contain "anthropic"/"claude".
• description: this is a trigger, not a summary. Write "Use this when the user wants to X", including the phrases you'd actually type. This single field decides whether Claude picks the skill. Max 1024 chars.
• Keep SKILL.md concise. Move long reference material into a references/ folder and link to it (progressive disclosure keeps your context window clean).
• Bundling scripts is more powerful than instructions alone — offload deterministic work (exact API calls, formatting, parsing) to code so Claude does the planning and the script does the precise part.

3D. The fastest way to build one: let Claude build it​

You don't need to memorize the format. Two options:

1. In Claude Code: there's a skill-creator skill — ask Claude to scaffold a new skill and it generates the SKILL.md and structure. Live changes to SKILL.md take effect within the session (no restart) as long as the skills directory existed at launch.
2. The Claude-A / Claude-B loop (the recommended refinement method):
   • Work through a task without a skill, noticing the context you keep providing.
   • Ask one Claude ("A") to capture that into a SKILL.md.
   • Give the skill to a fresh Claude ("B") on real tasks; watch where it struggles.
   • Bring the observation back to A ("B forgot to exclude test accounts even though the skill mentions it") and refine — e.g., promote "always filter" to "MUST filter."
   • Repeat. You're tuning against real behavior, not assumptions.

3E. Distribution & control (for teams)​

• Project skills: commit .claude/skills/ to version control so the whole team gets them.
• Personal skills: keep in ~/.claude/skills/.
• Control which skills Claude may auto-invoke via /permissions (e.g., Skill(commit), deny Skill(deploy *)).
• As an org scales, an internal plugin marketplace beats checking every skill into every repo (each loaded skill adds a little context cost).

4. Your concrete setup plan (do these in order)​

Day 1 — Memory foundation (~20 min)

1. claude.ai → Settings → Capabilities → enable both memory toggles. Optionally import from your other AI tools.
2. In each Cowork project, fill the project instructions with hard rules (package manager, test runner, commit style, no-touch directories).
3. Ask Claude "What do you remember about me?" to confirm it's working.

Day 1–2 — CLAUDE.md for your main repo (~1 hr) 4. In your repo root, create CLAUDE.md. Start small: stack, build/test/lint commands, 5–10 conventions, project layout, a "Human Approval Required" list. Keep under ~100 lines. 5. Create ~/.claude/CLAUDE.md for personal cross-project prefs (communication style, "show diffs not whole files", "run tests after changes"). 6. Commit the project CLAUDE.md. Run /memory to verify it loaded. 7. For a monorepo, add lightweight nested CLAUDE.md files per package (they load on demand).

Week 1 — First skills 8. Use the pre-built docx/xlsx/pdf skills once (e.g., "turn this benchmark CSV into an Excel report") to see them work. 9. Build your first custom skill for a workflow you repeat. Use skill-creator or the A/B loop. 10. Commit it to .claude/skills/ so your team benefits. Iterate when it triggers wrongly (tune the description).

Ongoing 11. When you correct Claude on something durable, write it into the right file (# shortcut, or update CLAUDE.md/project instructions). If it only matters for one task, skip it. 12. Monthly: audit memory and CLAUDE.md for staleness — outdated rules are worse than none.

5. Skills worth building as an engineer​

Start with whatever you explain to Claude most often. Common high-value ones:

• pr-description-writer — diff → structured PR body (example above).
• commit-message — staged changes → conventional-commit message.
• test-generator — generate tests matching your framework, fixtures, and naming conventions.
• code-review — apply your team's review checklist (security, error handling, logging) to a diff.
• run-skill-generator (exists in Code) — captures how to build/launch your app from a clean env and records it so /run and /verify follow the recipe instead of re-discovering it.
• migration-scaffold — generate DB migration boilerplate with your project's patterns.
• new-service — scaffold a new handler/service with the natural-language choices baked in ("async or sync?").

The best skills start tiny — a few lines plus one "gotcha" — and grow as Claude hits new edge cases. Capture the first failure, add one script, share it, iterate.

6. Cheat sheet​

Sources to bookmark​

• Skills overview: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• Skills in Claude Code: https://code.claude.com/docs/en/skills
• Claude Code memory (CLAUDE.md): https://code.claude.com/docs/en/memory
• Chat search & memory: https://support.claude.com/en/articles/11817273
• Skills authoring best practices: https://www.claudeskills.org/docs/agent-skills/best-practices

Feature availability and UI evolve quickly — if a menu path differs, check the linked docs for the current version.

In the developer community, we often have a "Not Invented Here" syndrome. We feel that to truly own our personal brand, we need to build our websites from the ground up—hand-coding every div, managing our own routing, and sweating over the perfect dark mode implementation.

But lately, I’ve shifted my philosophy. For my blog and documentation, I’ve moved to Docusaurus. Here is why I believe it’s the superior choice over a "from scratch" React or Next.js build.

1. Speed to Production (Easy to Use & Deploy)​

Building from scratch means you are the architect, the plumber, and the decorator. You have to handle:

• Route management.
• Theme switching (Dark/Light mode).
• Mobile responsiveness.
• Asset optimization.

With Docusaurus, you get a "Fast Track" to deployment. It’s a specialized static site generator (SSG) that comes with these features out of the box. You can go from npx create-docusaurus@latest to a live site on Vercel, Netlify, or GitHub Pages in under 10 minutes.

2. The Power of MDX: Markdown with "Superpowers"​

The biggest selling point for me is the content format. Most developers love Markdown for its simplicity, but it can be limiting when you want to show off an interactive demo.

Docusaurus uses MDX (Markdown + JSX). This means I can write my technical articles in clean Markdown, but when I need a live code editor, an interactive chart, or a custom React component, I can just drop it right into the text.

# My Awesome Component

Check out this interactive button I built:

import MyCustomButton from "@site/src/components/MyCustomButton";

<MyCustomButton onClick={() => alert("Hello from MDX!")} />

3. "Docs-as-Code" Best Practices​

Docusaurus isn't just a blog; it’s a documentation engine. It follows the industry’s best practices for content structure:

Versioning: Perfect if you’re documenting an Open Source project or a library.

Sidebar & Breadcrumbs: Automatic navigation that makes long-form technical content readable.

SEO by Default: It generates static HTML for every route, ensuring your blog posts actually show up on Google.

4. A Rich Plugin Ecosystem (Algolia & More)​

When you build from scratch, adding a search bar is a project in itself. You have to index your content, manage a search engine, and build the UI.

In Docusaurus, adding world-class search is as simple as a configuration change. The Algolia DocSearch plugin is the gold standard for technical sites. Once configured, you have a lightning-fast, keyboard-accessible search bar that "just works."

Final Thoughts​

Building from scratch is great for learning, but Docusaurus is for shipping. As a developer, I want my time spent on writing high-quality content and building cool React components, not debugging the "Active" state of a sidebar link for the 10th time.

If you want a site that is professional, accessible, and incredibly easy to maintain, Docusaurus is the way to go.

We've all been there. You're building a web page, and you reach for the trusty <div> tag. Again. And again. Before you know it, your HTML looks like a sea of meaningless boxes. While divs aren't inherently bad, overusing them is one of the most common mistakes in modern web development.

Semantic HTML is about choosing the right element for the job—elements that convey meaning about their content, not just how they look. Let's explore why this matters and how to do it right.

Why Semantic HTML Matters​

1. Accessibility​

Screen readers and assistive technologies rely on semantic elements to help users navigate your site. When you use <nav> instead of <div class="navigation">, screen readers can identify it as a navigation landmark, allowing users to jump directly to it.

<!-- ❌ Non-semantic -->
<div class="header">
  <div class="navigation">
    <div class="nav-item">Home</div>
    <div class="nav-item">About</div>
  </div>
</div>

<!-- ✅ Semantic -->
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</header>

2. SEO Benefits​

Search engines use semantic HTML to better understand your content structure. A <main> element tells crawlers where your primary content lives, while <article> and <section> help organize information hierarchically.

3. Code Readability​

Semantic HTML is self-documenting. Compare these two examples:

<!-- ❌ Div soup -->
<div class="wrapper">
  <div class="content">
    <div class="post">
      <div class="post-header">...</div>
      <div class="post-body">...</div>
    </div>
  </div>
</div>

<!-- ✅ Clear semantic structure -->
<main>
  <article>
    <header>...</header>
    <section>...</section>
  </article>
</main>

The second version immediately communicates the page structure without requiring you to parse class names.

4. Better Browser Support​

Semantic elements come with built-in keyboard navigation and ARIA roles. For instance, <button> is natively focusable and responds to Enter/Space keys, whereas a <div onclick="..."> requires extra work to achieve the same accessibility.

Essential Semantic Elements and When to Use Them​

Structural Elements​

<header> - Introductory content or navigational aids. Can be used multiple times (page header, article header, section header).

<nav> - Major navigation blocks. Don't use it for every list of links—reserve it for primary navigation.

<main> - The dominant content of the page. Use only once per page.

<article> - Self-contained, independently distributable content (blog posts, news articles, forum posts).

<section> - Thematic grouping of content, typically with a heading. If you can't give it a meaningful heading, it probably shouldn't be a section.

<aside> - Tangentially related content (sidebars, pull quotes, related links).

<footer> - Footer for its nearest sectioning content or root element.

Content Elements​

<h1> through <h6> - Headings that establish document outline. Don't skip levels for styling—use CSS instead.

<p> - Paragraphs of text. Don't use divs for text blocks.

<figure> and <figcaption> - Images, diagrams, code snippets with captions.

<figure>
  <img src="/charts/revenue-2025.png" alt="Q4 2025 Revenue Chart" />
  <figcaption>Revenue increased 23% in Q4 2025</figcaption>
</figure>

<time> - Dates and times with machine-readable values.

<time datetime="2026-01-15">January 15, 2026</time>

Common Semantic HTML Patterns​

Blog Post Structure​

<article>
  <header>
    <h1>Understanding React Server Components</h1>
    <p>
      By <span>John Doe</span> on
      <time datetime="2026-01-15">January 15, 2026</time>
    </p>
  </header>

  <section>
    <h2>Introduction</h2>
    <p>React Server Components represent a paradigm shift...</p>
  </section>

  <section>
    <h2>How They Work</h2>
    <p>Server Components render on the server...</p>
  </section>

  <footer>
    <p>
      Tags: <a href="/tags/react">React</a>,
      <a href="/tags/performance">Performance</a>
    </p>
  </footer>
</article>

Navigation Menu​

<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/blog">Blog</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

Form with Proper Labels​

<!-- ❌ Non-semantic -->
<div class="form-group">
  <div class="label">Email</div>
  <div class="input">
    <input type="text" />
  </div>
</div>

<!-- ✅ Semantic -->
<form>
  <label for="email">Email</label>
  <input type="email" id="email" name="email" required />

  <button type="submit">Subscribe</button>
</form>

When to Use Divs​

Divs aren't evil—they're just generic containers. Use them when:

• You need a wrapper purely for styling or layout purposes
• No semantic element accurately describes the content
• You're creating a grid or flexbox container

<!-- ✅ Appropriate div usage for layout -->
<section>
  <h2>Our Services</h2>
  <div class="grid grid-cols-3 gap-4">
    <article>...</article>
    <article>...</article>
    <article>...</article>
  </div>
</section>

Practical Tips for Implementation​

1. Start with Structure​

Before writing any HTML, sketch out your page structure using semantic elements. Think in terms of landmarks: header, navigation, main content, complementary content, and footer.

2. Use HTML5 Outlining​

Your headings and sectioning elements create an outline. Tools like the HTML5 Outliner browser extension can help you visualize this structure.

3. Test with Screen Readers​

Use VoiceOver (Mac), NVDA (Windows), or JAWS to navigate your site. You'll quickly discover where semantic HTML makes a difference.

4. Validate Your HTML​

Use the W3C Markup Validation Service to catch semantic errors and ensure proper nesting.

5. Leverage Developer Tools​

Modern browser DevTools can show you the accessibility tree, which reveals how assistive technologies interpret your markup.

React and Vue Considerations​

When working with React or Vue, it's tempting to use divs everywhere since everything is a component. Resist this urge:

// ❌ Div soup in React
function BlogPost() {
  return (
    <div className="blog-post">
      <div className="post-header">
        <div className="title">My Post</div>
      </div>
      <div className="post-content">...</div>
    </div>
  );
}

// ✅ Semantic React component
function BlogPost() {
  return (
    <article>
      <header>
        <h1>My Post</h1>
      </header>
      <section>...</section>
    </article>
  );
}

Use React Fragments (<>) or Vue's template syntax to avoid unnecessary wrapper divs when you just need to return multiple elements.

Conclusion​

Semantic HTML is a fundamental skill that pays dividends in accessibility, SEO, maintainability, and developer experience. It requires minimal extra effort but makes your code more professional and your websites more inclusive.

The next time you reach for a div, pause and ask: "Is there a more meaningful element for this content?" Your future self, your teammates, your users, and search engines will thank you.

Start small—refactor one component or page at a time. Before long, writing semantic HTML will become second nature, and you'll wonder how you ever settled for div soup.

Further Reading:

• MDN Web Docs: HTML elements reference
• W3C HTML5 Specification
• WebAIM: Semantic Structure
• A11y Project: Accessibility checklist