Back to Kiosk

KIOSK.md Guide

The KIOSK.md file is the heart of every Kiosk app. It contains instructions that Claude Code follows to install your app.

Creating a KIOSK.md

The easiest way to create a KIOSK.md is to run:

kiosk init

This uses Claude Code to analyze your project and generate a complete KIOSK.md with installation instructions tailored to your app.

What is KIOSK.md?

A KIOSK.md file is a markdown document in your repository that describes how to install your app. When users install your app, Claude Code reads this file and executes the instructions.

File Location

Place your KIOSK.md file in one of these locations:

  • Repository root (recommended): /KIOSK.md
  • Subdirectory: /packages/my-app/KIOSK.md

Structure

A good KIOSK.md includes:

  1. Title and description - What the app does
  2. Prerequisites - What's needed before installation
  3. Installation steps - Clear, numbered instructions
  4. Configuration - Any required setup or environment variables
  5. Usage examples - How to use the app after installation

Example KIOSK.md

# My Component Library

A collection of beautiful UI components for React applications.

## Prerequisites

- React 18 or higher
- Tailwind CSS configured in your project

## Installation

1. Copy the `components` folder to your project's `src` directory
2. Install the required dependencies:

\`\`\`bash
npm install clsx tailwind-merge
\`\`\`

3. Add the following to your `tailwind.config.js`:

\`\`\`js
module.exports = {
content: ['./src/components/**/*.tsx'],
}
\`\`\`

## Configuration

Create a `.env.local` file with:

\`\`\`
NEXT_PUBLIC_API_URL=your-api-url
\`\`\`

## Usage

Import components in your code:

\`\`\`tsx
import { Button } from '@/components/button'
\`\`\`

Best Practices

  • Be specific - Don't assume users know your project structure
  • Use relative paths - Reference files relative to the repository root
  • Include all steps - Even obvious ones like npm install
  • Test your instructions - Try installing in a fresh project
  • Keep it updated - Update KIOSK.md when your app changes

Tips for Claude Code

Claude Code works best with:

  • Clear, numbered steps
  • Exact file paths and names
  • Code blocks with proper syntax highlighting
  • Explicit commands (not just "install dependencies")