ai-superpower/.ai/skills/readme/SKILL.md

name	description	category	impact
readme	Guidelines for creating or updating README files. Use when generating, formatting, or editing the project's root README.md.	meta	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

// ❌ 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.