Crafting Effective Complete

A practical skill for writing effective README files — covering audience analysis, content structure, installation instructions, usage examples, contribution guidelines, and documentation that answers the questions your readers actually have.

When to Use This Skill

Choose Crafting Effective Complete when you need to:

• Write a README for a new open-source project
• Improve an existing README that's confusing or incomplete
• Create documentation for internal tools and services
• Write configuration folder READMEs for team reference
• Structure documentation for different audience types

Consider alternatives when:

• You need full API reference documentation (use an API docs skill)
• You need tutorial or course content (use a technical writing skill)
• You need marketing landing page copy (use a copywriting skill)

Quick Start

Copy
# Generate a README
claude "Write a README for a Node.js CLI tool called 'logwatch' that monitors log files in real-time, filters by severity level, and sends Slack notifications for errors."

Copy
# logwatch

Monitor log files in real-time. Filter by severity. Get Slack
alerts when errors happen.

## Install

```bash
npm install -g logwatch

Quick Start

Copy
# Watch a log file
logwatch /var/log/app.log

# Filter by severity
logwatch /var/log/app.log --level error

# Send Slack notifications for errors
logwatch /var/log/app.log --level error --slack-webhook $SLACK_URL

Configuration

Create ~/.logwatchrc:

Copy
{
  "default_level": "warn",
  "slack_webhook": "https://hooks.slack.com/...",
  "patterns": {
    "error": "\\b(ERROR|FATAL|CRITICAL)\\b",
    "warn": "\\b(WARN|WARNING)\\b"
  }
}

Options

Flag	Description	Default
--level, -l	Minimum severity level	info
--slack-webhook	Slack webhook URL	—
--format, -f	Output format	text
--tail, -n	Lines to show initially	10

License

MIT

## Core Concepts

### README Structure by Audience

| Audience          | What They Need First         | Sections to Prioritize     |
|------------------|------------------------------|----------------------------|
| New user         | What does this do? How to install? | Title, Install, Quick Start |
| Returning user   | Config options, API reference | Options, Configuration     |
| Contributor      | How to set up dev environment | Contributing, Development  |
| Evaluator        | Is this worth using?         | Features, Comparison, License |
| Future you       | Why did I make these choices? | Architecture, Decisions    |

### Section Templates

```markdown
## Essential Sections (Every README)

### 1. Title + One-Line Description
# projectname
One sentence that explains what this does and why you'd use it.

### 2. Install
How to get it. The exact commands. No ambiguity.

### 3. Quick Start
The simplest possible example that produces a visible result.
Maximum 5 lines of code. If your quick start needs 20 lines,
you have a UX problem.

### 4. Usage / API
The main features with examples. One example per feature.

## Optional Sections (Add When Needed)

### 5. Configuration
Only if configuration exists. Table format preferred.

### 6. Contributing
Only for open-source projects expecting contributions.

### 7. Architecture / Design
Only for complex projects where contributors need context.

### 8. License
Required for open-source. One line is sufficient.

Writing Rules

Copy
## README Writing Principles

### Lead with Value
❌ "LogWatch is a Node.js-based log monitoring solution
   that leverages real-time file system events..."
✅ "Monitor log files. Filter by severity. Get Slack
   alerts when errors happen."

### Show, Don't Describe
❌ "LogWatch supports multiple output formats including
   text, JSON, and CSV."
✅ logwatch --format json /var/log/app.log

### Be Specific About Requirements
❌ "Requires Node.js"
✅ "Requires Node.js 18 or later"

### One Concept Per Section
Don't mix installation, configuration, and usage
in the same section. Each section answers one question.

Configuration

Parameter	Description	Example
audience	Primary reader type	"developer" / "user"
project_type	Type of project	"cli" / "library" / "service"
include_badges	Add status badges	true
include_toc	Add table of contents	true (if > 5 sections)
license	License type	"MIT" / "Apache-2.0"

Best Practices

1. Write the README before writing the code — Your README is your product spec. If you can't explain how to use it in simple terms, the design may be too complex. Writing the README first clarifies the API, identifies complexity, and forces user-centric thinking.

2. Make the Quick Start produce a visible result — The reader should be able to copy-paste the Quick Start, run it, and see something happen within 60 seconds. If your Quick Start requires setting up a database, configuring API keys, and writing a config file first, it's not quick.

3. Use real examples, not placeholder text — logwatch /var/log/app.log --level error is real. logwatch <path> --level <level> is a template. Real examples are copyable and demonstrate actual usage patterns.

4. Keep the README under 500 lines — Long READMEs don't get read. If you need more than 500 lines, move detailed content to a /docs folder and link to it from the README. The README is an on-ramp, not the complete manual.

5. Test every code example before publishing — Copy-paste each code block from your README and run it. Outdated or broken examples in the README are the fastest way to lose user trust.

Common Issues

README is outdated and doesn't match current behavior — The most common README problem. Add a CI step that tests README code examples, or at minimum, review the README during every release. Include a "Last tested with version X.Y.Z" note.

Quick Start assumes too much context — A Quick Start that begins with "Configure your database connection" isn't quick. If your tool requires setup before the first use, provide an explicit "Prerequisites" section before the Quick Start and keep prerequisites minimal.

README describes features without showing usage — "Supports JSON output" tells the reader nothing actionable. "Run logwatch --format json to get JSON output" shows them exactly how to use the feature. Every feature claim should be followed by a code example.