41 lines
1.7 KiB
Markdown
41 lines
1.7 KiB
Markdown
---
|
|
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.
|
|
|
|
## 🚨 Prohibitions
|
|
- **NEVER exceed ~100 lines.** If more detail is needed, put it in `docs/`.
|
|
- **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.
|
|
- **NEVER write in a language other than English.**
|
|
|
|
## Workflows
|
|
|
|
When writing or reviewing a README, ensure it contains exactly these three sections:
|
|
1. **What is this?** — One or two sentences explaining the problem and solution in plain language.
|
|
2. **How to run locally** — Minimal commands only, zero theory.
|
|
3. **Key links** — Direct links to detailed `docs/` files.
|
|
|
|
*Note: For general writing style, diagrams, and formatting, follow the `documentation` skill.*
|
|
|
|
## ✅ / ❌ 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.
|
|
```
|