Project Setup Guide Skill

Generate professional, comprehensive README.md files for any project type requiring setup documentation.

Supported Project Types

6-Step Workflow

Follow these steps sequentially to create a complete setup guide:

Step 1: Audit the Project

Goal: Understand what exists before documenting.

Actions:
1. List all configuration files and their purposes
2. Identify dependencies (package.json, requirements.txt, Brewfile, etc.)
3. Find existing documentation (README, docs/, wiki)
4. Note installation scripts or makefiles
5. Check for environment variables or secrets

Questions to answer:

• What does this project do?
• Who is the target audience?
• What are the prerequisites?
• Are there automated setup options?

Step 2: Determine Structure

Goal: Choose sections based on project type.

Universal sections (all projects):

• Title with badges
• One-line description
• Features overview
• Table of Contents
• Installation
• Basic usage

Conditional sections (by type):

Step 3: Document Core Information

Goal: Write the essential sections every README needs.

Title Block Pattern

# Project Name

> One-line description of what this project does

[![License](badge-url)](license-url)
[![Version](badge-url)](version-url)

Features Section Pattern

Use a table for scannable feature lists:

## Features at a Glance

| Category | Features |
|----------|----------|
| **Shell** | Zsh with Powerlevel10k, syntax highlighting, autosuggestions |
| **Editor** | Neovim with LSP, Telescope, Treesitter |
| **Terminal** | Tmux with custom keybindings, Alacritty config |

Repository Structure Pattern

## Repository Structure

\`\`\`
project-root/
├── config/           # Application configurations
│   ├── app.config.ts
│   └── database.ts
├── src/              # Source code
│   ├── components/
│   └── utils/
├── scripts/          # Automation scripts
│   └── setup.sh
└── README.md
\`\`\`

Step 4: Write Setup Instructions

Goal: Provide clear, tested installation steps.

The Dual Setup Pattern

Always offer both automated AND manual options when possible:

## Installation

### Quick Start (Recommended)

\`\`\`bash
# One-line installation
curl -fsSL https://example.com/install.sh | bash
\`\`\`

### Manual Installation

<details>
<summary>Click to expand manual steps</summary>

1. Clone the repository:
   \`\`\`bash
   git clone https://github.com/user/project.git
   cd project
   \`\`\`

2. Install dependencies:
   \`\`\`bash
   npm install
   \`\`\`

3. Configure environment:
   \`\`\`bash
   cp .env.example .env
   # Edit .env with your values
   \`\`\`

</details>

Prerequisites Pattern

## Prerequisites

| Requirement | Version | Check Command |
|-------------|---------|---------------|
| Node.js | ≥18.0 | `node --version` |
| npm | ≥9.0 | `npm --version` |
| Git | ≥2.0 | `git --version` |

Environment Variables Pattern

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
| `API_KEY` | Yes | - | External service API key |
| `DEBUG` | No | `false` | Enable debug logging |

Step 5: Document Commands & Usage

Goal: Show users how to actually use the project.

Command Reference Pattern

## Commands

| Command | Description |
|---------|-------------|
| `npm start` | Start development server |
| `npm test` | Run test suite |
| `npm run build` | Build for production |
| `npm run lint` | Check code style |

Usage Examples Pattern

## Usage

### Basic Example

\`\`\`typescript
import { something } from 'project';

const result = something({
  option: 'value'
});
\`\`\`

### Advanced Example

\`\`\`typescript
// More complex usage with all options
import { something, configure } from 'project';

configure({
  debug: true,
  timeout: 5000
});

const result = await something({
  option: 'value',
  callback: (data) => console.log(data)
});
\`\`\`

Step 6: Add Supporting Sections

Goal: Complete the README with helpful extras.

Configuration Pattern

## Configuration

Configuration file: `config.json`

\`\`\`json
{
  "setting1": "value",
  "setting2": true,
  "nested": {
    "option": "value"
  }
}
\`\`\`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `setting1` | string | `"default"` | Description of setting1 |
| `setting2` | boolean | `false` | Description of setting2 |

Troubleshooting Pattern

## Troubleshooting

<details>
<summary><strong>Error: Module not found</strong></summary>

**Cause:** Dependencies not installed properly.

**Solution:**
\`\`\`bash
rm -rf node_modules
npm install
\`\`\`

</details>

<details>
<summary><strong>Permission denied</strong></summary>

**Cause:** Script lacks execute permission.

**Solution:**
\`\`\`bash
chmod +x scripts/setup.sh
\`\`\`

</details>

Updating Pattern

## Updating

\`\`\`bash
# Pull latest changes
git pull origin main

# Update dependencies
npm install

# Run migrations (if applicable)
npm run migrate
\`\`\`

Uninstall Pattern

## Uninstallation

\`\`\`bash
# Remove installed files
npm uninstall -g project-name

# Clean up configuration (optional)
rm -rf ~/.config/project-name
\`\`\`

Project-Specific Guidance

For Dotfiles Projects

Must include:

• Tool-by-tool breakdown with features
• Aliases and abbreviations table
• Custom functions documentation
• Keybindings reference (especially for tmux/vim)
• Backup instructions before installation
• Symlink strategy explanation

Example structure:

## Tools Included

### Zsh
- Theme: Powerlevel10k
- Plugins: syntax-highlighting, autosuggestions, fzf
- Custom aliases: [see below](#shell-aliases)

### Neovim
- Plugin manager: lazy.nvim
- LSP servers: typescript, lua, python
- Keybindings: [see below](#vim-keybindings)

## Shell Aliases

| Alias | Expansion | Description |
|-------|-----------|-------------|
| `ll` | `ls -la` | Long list with hidden |
| `..` | `cd ..` | Go up one directory |
| `g` | `git` | Git shorthand |

## Keybindings

### Tmux

| Key | Action |
|-----|--------|
| `Ctrl-a` | Prefix key |
| `Prefix + \|` | Vertical split |
| `Prefix + -` | Horizontal split |

For Libraries/Packages

Must include:

• Installation via package manager
• Import/require examples
• API reference with types
• Multiple usage examples (basic → advanced)
• TypeScript types documentation (if applicable)

Example structure:

## Installation

\`\`\`bash
npm install package-name
# or
yarn add package-name
# or
pnpm add package-name
\`\`\`

## Quick Start

\`\`\`typescript
import { mainFunction } from 'package-name';

const result = mainFunction('input');
\`\`\`

## API Reference

### `mainFunction(input, options?)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input` | `string` | Yes | The input to process |
| `options` | `Options` | No | Configuration options |

**Returns:** `Result`

**Example:**
\`\`\`typescript
const result = mainFunction('hello', { uppercase: true });
// => 'HELLO'
\`\`\`

For Applications

Must include:

• System requirements
• Environment setup (env vars, config files)
• Development vs production instructions
• Database setup (if applicable)
• Deployment guide

Example structure:

## Getting Started

### Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis (optional, for caching)

### Development Setup

1. Clone and install:
   \`\`\`bash
   git clone https://github.com/user/app.git
   cd app
   npm install
   \`\`\`

2. Set up database:
   \`\`\`bash
   createdb myapp_dev
   npm run db:migrate
   npm run db:seed
   \`\`\`

3. Configure environment:
   \`\`\`bash
   cp .env.example .env
   \`\`\`

4. Start development server:
   \`\`\`bash
   npm run dev
   \`\`\`

### Production Deployment

See [Deployment Guide](docs/deployment.md)

Formatting Standards

Tables

• Use tables for: features, commands, env vars, options, keybindings
• Always include header row
• Align columns for readability in raw markdown

Code Blocks

• Always specify language for syntax highlighting
• Use bash for shell commands
• Use typescript over javascript when types are shown
• Keep examples concise but complete

Collapsible Sections

Use <details> for:

• Long installation steps
• Troubleshooting items
• Optional/advanced content
• Manual alternatives to automated steps

<details>
<summary>Click to expand</summary>

Content here...

</details>

Badges

Place at top of README, common badges:

• License
• Version/Release
• Build status
• npm/PyPI downloads
• Code coverage

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![npm version](https://badge.fury.io/js/package.svg)](https://npmjs.com/package/package)

Table of Contents

Generate for READMEs with 5+ sections:

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

Section Templates Reference

For detailed, copy-paste-ready templates for each project type, see: references/section-templates.md

Quality Checklist

Before finalizing any README, verify:

• Accurate: All commands tested and working
• Complete: All prerequisites listed
• Scannable: Uses tables, headers, and formatting
• Accessible: Both quick start and detailed options
• Maintainable: Easy to update when project changes
• Consistent: Formatting uniform throughout

Example Workflow

User: “Create a setup guide for my dotfiles repo”

Claude’s approach:

1. Read the repository structure to understand what’s included
2. Identify all configuration files and tools
3. Check for existing install scripts
4. Ask clarifying questions if needed (target OS, experience level)
5. Generate README using dotfiles-specific sections
6. Include tool breakdown, aliases, keybindings tables
7. Provide both automated and manual install options