---
name: readme
description: Guidelines for creating or updating README files. Use when generating, formatting, or editing the project's root README.md.
category: meta
impact: low
---

> **🏷️ Category:** `Meta-Skill` | **⚙️ Applies to:** Project Documentation Management

# README Instructions

## 🎯 Purpose
Establish the README as the primary entry point for both humans and AI. It must concisely articulate the problem the project solves and how to get started.

## Base Workflow
For process flow and writing behavior, follow `.ai/skills/documentation/SKILL.md` as the base workflow.
This skill overrides only README-specific boundaries below.

## 🚨 Prohibitions
- **NEVER treat 100 lines as a hard fail without split strategy.** Target `<=100` lines by default.
- **NEVER exceed 140 lines without explicit user approval.**
- **NEVER duplicate `docs/` content.** Link to the documents instead.
- **NEVER invent content.** If the README is missing, ask the user what problem it solves and how to start it locally before writing.
- **NEVER rewrite the entire file when updating.** Point out specifically what is wrong and fix only that section.

## README-Specific Overrides

1. **Scope Ownership**
   - README owns entrypoint content only.
   - Detailed architecture, decisions, and deep explanations belong in `docs/`.

2. **Required README Structure**
   - Keep exactly these three sections:
     - **What is this?** — One or two sentences in plain language.
     - **How to run locally** — Minimal commands only, zero theory.
     - **Key links** — Direct links to detailed docs.

3. **Update Policy**
   - For non-trivial edits, update one section at a time and let the user review before expanding.
   - If a correction is requested, fix only the requested section.
   - If README approaches 100 lines, move depth into `docs/<topic>.md` and add links in README.

## ✅ / ❌ Examples

### Updating an Outdated README
```text
// ❌ FORBIDDEN: Rewriting the entire file to update a small detail
(Generates a completely new 150-line README replacing the author's voice)

// ✅ REQUIRED: Targeted fix
I noticed the "How to run" section is outdated. I have updated just that command block.
```