Building day: the SaaS blueprint

Welcome to the culmination of week two — week two, day five. This is a blue day, a building day, and by the end of it we will have a working SaaS platform: our legal-document drafter, Pre-Legal. Yesterday we learned to drive Claude Code through a disciplined workflow. Today we point that skill at a real product and build it, ticket by ticket. First, we lay the foundations properly — skills, and the two kinds of CLAUDE.md.

01Where we are — and the one thing we skipped

A last, quick recap of the big three. MCP stitches in other people's tools (huge ecosystem, but context-hungry and occasionally flaky — remember the Jira auth). Skills are simple Markdown that add expertise efficiently. Plugins bundle all of it up. Yesterday's build read a Jira ticket via MCP, ran it through the FeatureDev plugin, and shipped a GitHub PR — all from one command.

02How a skill actually works

A skill has a beautiful design: progressive disclosure. Only a tiny bit is always loaded; the rest is read on demand, so it barely touches your context until it is needed.

Metadata and instructions live together in one file, SKILL.md, with the metadata at the top in a special format (a block fenced by hyphens — more on that next page). Skills use a simple file-system architecture: a .claude folder (in your project and/or your home directory) with a skills/ folder inside. Drop a correctly-structured skill folder in there and Claude Code can use it. That is the whole mechanism.

03There are two CLAUDE.md files

At the start of any real project you write a good CLAUDE.md. But here is something we have not said before: there is more than one — and not just the many you can scatter in subfolders.

Just as you can keep skills in your home .claude folder, you can keep a CLAUDE.md there too. It is your personal standing instructions — your style, your pet peeves — applied to all your work with Claude.

04Writing a lean global CLAUDE.md

Because it loads into every context, the golden rule is: keep it short, and make every word count — because every token counts. Anthropic already bakes a lot of good defaults into Opus, so use this only for the extra nuggets you always want. A useful starting shape:

# IMPORTANT — be simple
Approach tasks in a simple, incremental way. Small, simple steps.
Validate and check each increment before moving on.
Do not over-engineer. Do not program defensively.

# Code style
Use UV as the Python package manager: always `uv run`, never `python3`;
always `uv add`, never `pip install`.
Favor clear, concise docstring comments; be sparing elsewhere.
Favor short modules. Keep the README concise. Clean up old files.
Never use emojis in code, print statements, or logs.

# Debugging
Always identify the root cause before fixing — prove it, do not guess.
Reproduce consistently. Change one thing at a time. Be methodical.
Do not jump to conclusions. Do not apply workarounds.