Project Setup Guide Skill

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

Supported Project Types

Type	Examples	Key Sections
Dotfiles	Shell configs, vim, tmux, git	Tool configs, aliases, keybindings
CLI Tools	Scripts, utilities, automation	Installation, usage, options
Libraries	npm packages, Python modules	API reference, examples
Applications	Web apps, mobile apps, services	Environment setup, deployment
Frameworks	Starter kits, boilerplates	Configuration, extending
Dev Environments	Docker setups, Nix configs	Prerequisites, bootstrapping

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):

If Project Has...	Include Section
Multiple tools/configs	Repository Structure
CLI commands	Command Reference
Configuration options	Configuration Guide
Shell customizations	Aliases & Functions
Keyboard shortcuts	Keybindings
API surface	API Reference
Visual components	Screenshots
Breaking changes	Migration Guide
Community	Contributing Guide

Step 3: Document Core Information

Goal: Write the essential sections every README needs.

Title Block Pattern

markdown

# 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:

markdown

## 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

markdown

## 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:

markdown

## 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

markdown

## Prerequisites

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

Environment Variables Pattern

markdown

## 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

markdown

## 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

markdown

## 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

markdown

## 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

markdown

## 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

markdown

## Updating

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

# Update dependencies
npm install

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

Uninstall Pattern

markdown

## 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:

markdown

## 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:

markdown

## 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:

markdown

## 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

markdown

<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

markdown

[![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)

Generate for READMEs with 5+ sections:

markdown

## 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:

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

project-setup-guide

NPX Install

Tags

SKILL.md Content

Project Setup Guide Skill

Supported Project Types

6-Step Workflow

Step 1: Audit the Project

Step 2: Determine Structure

Step 3: Document Core Information

Title Block Pattern

Features Section Pattern

Repository Structure Pattern

Step 4: Write Setup Instructions

The Dual Setup Pattern

Prerequisites Pattern

Environment Variables Pattern

Step 5: Document Commands & Usage

Command Reference Pattern

Usage Examples Pattern

Step 6: Add Supporting Sections

Configuration Pattern

Troubleshooting Pattern

Updating Pattern

Uninstall Pattern

Project-Specific Guidance

For Dotfiles Projects

For Libraries/Packages

For Applications

Formatting Standards

Tables

Code Blocks

Collapsible Sections

Badges

Table of Contents

Section Templates Reference

Quality Checklist

Example Workflow