🎯 What You'll Learn: How to write documentation that turns your toolkit from a confusing folder into something anyone can install and use immediately
⏱️ Time Required: 35 minutes

---

The Documentation Problem

Riley sent David the toolkit folder. He messaged back: "What do I do with this?"

"A toolkit without a README is just a confusing folder of files. I'd spent three weeks building the automation and thirty minutes packaging it, and then forgot to explain anything. Documentation isn't the last step. It's the difference between 'I installed it in ten minutes' and 'I gave up and asked Riley again.'"
— Riley Harper

This lesson is about writing one good README that makes your toolkit self-installing.

---

The 5-Minute Rule

If someone can't get your toolkit working in 5 minutes from your README, the documentation needs work.

People read READMEs in a predictable sequence:

Scan the top for what it does (30 seconds)

Try the Quick Start commands (2 minutes)

Get stuck → search for the answer

Find the answer → continue; don't find it → abandon

Your README needs to support all four steps.

---

Exercise: Write Your README (35 min)

Part 1: The README (20 min)

Create README.md at the root of your toolkit. Use this structure:

# Toolkit Name

> One-line description: what it does, for whom.

## What It Does

- Bullet 1: specific outcome
- Bullet 2: specific outcome
- Time saved: [X hours → Y minutes]

## Prerequisites

Before installing:
- [ ] Claude Code installed (claude --version to check)
- [ ] [Any external accounts or tokens needed]
- [ ] [Any tools like Node.js if MCP servers are included]

## Installation

### Step 1: Copy the toolkit files

bash

cp -r margin-operations-toolkit ~/.claude/

### Step 2: Add your skills and agents

For each skill in the toolkit:

bash

Skills are installed by copying to ~/.claude/skills/

cp -r skills/weekly-margin-report ~/.claude/skills/

cp -r skills/data-validator ~/.claude/skills/

For each agent:

bash

cp -r agents/risk-analyzer ~/.claude/agents/

### Step 3: Add the hooks

Open `.claude/settings.json` (or create it if it doesn't exist).
Copy the contents of `hooks/settings-snippet.json` into the `"hooks"` section.

### Step 4: Set configuration

bash

Required, set your data folder path

export PRIME_BROKER_EXPORT_DIR="~/your/prime-broker/exports"

If using Slack notifications, set your webhook

export SLACK_WEBHOOK_URL="https://hooks.slack.com/..."

### Step 5: Test the install

Drop a CSV file in your configured folder and run:

bash

cd ~/your-project && claude --print "Run /weekly-margin-report"

You should see a formatted margin report as output.

## Configuration Reference

| Setting | Required | Default | Description |
|---------|----------|---------|-------------|
| `PRIME_BROKER_EXPORT_DIR` | Yes | — | Path to your Prime Broker portal CSV exports |
| `SLACK_WEBHOOK_URL` | No | — | Slack webhook for completion alerts |
| `AT_RISK_DAYS` | No | 7 | Days without activity before flagging a position |

## Skills Included

| Skill | Command | What it does |
|-------|---------|--------------|
| weekly-margin-report | `/weekly-margin-report` | Generates formatted margin report |
| data-validator | `/data-validator` | Validates Prime Broker portal CSV exports |

## Agents Included

| Agent | What it does |
|-------|--------------|
| risk-analyzer | Diagnoses why specific positions are at risk |

## Hooks Included

| Hook type | What it does |
|-----------|--------------|
| PostToolUse (Write) | Audit log entry for every file Claude writes |
| Stop | Slack notification when a session completes |

## Troubleshooting

**"Claude can't find the skill"**
Check that the skill file is at `~/.claude/skills/weekly-margin-report/SKILL.md` (not just inside the toolkit folder).

**"Hooks aren't firing"**
Validate your `settings.json` is valid JSON — a single missing comma breaks all hooks silently. Use `cat ~/.claude/settings.json | python3 -m json.tool` to check.

**"Report generates but Slack notification doesn't send"**
Check `SLACK_WEBHOOK_URL` is set in the environment where you're running Claude. Cron jobs need the variable exported in the crontab or your `.bashrc`.

## Support

[Where to ask for help — your name, Slack channel, or GitHub issues link]

---

Riley's README:

"I gave David the README and set a timer. He messaged back at 8 minutes: 'Everything is working.' The thirty minutes I spent writing this saved us both far more than that."

Part 2: Test It (10 min)

Before sharing, do this:

Get a second opinion. Ask a colleague to install the toolkit from your README on a clean machine. Watch silently. Don't help.

Every time they get confused is a documentation gap. Fix it.

Run every command in the README yourself. If a command fails, fix it before the README ships.

The test is worth more than any proofreading.

---

What Makes Documentation Fail

The three most common README mistakes:

1. Assuming context. You know your Prime Broker portal folder, your Slack channel, your CSV format. The installer knows none of it. Write the README as if the reader has never heard of your project.

2. Broken examples. Copy-paste a working command, then test it works after you paste it. Commands that look right but don't work destroy trust immediately.

3. Too long. If your README is more than 500 lines, move the detail into separate docs files. The README should answer "can I get this working?" not "what is every possible configuration?"

---

✅ Success Criteria:

---

Next Up

Lesson 4.4: Security Review

Before you share the toolkit with your team, you need to confirm there are no credentials, personal paths, or sensitive data anywhere in the files. One exposed Slack token in a README example can cause months of cleanup.