191f9f4f2a
Tighten root/core control flow, add dedicated post-mortem, web, and context-hygiene capabilities, and reduce instruction drift through clearer ownership, conflict-priority handling, and README/docs workflow alignment. This makes long-session AI behavior more deterministic while keeping the instruction system compact and maintainable.
53 lines
2.2 KiB
Markdown
53 lines
2.2 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.
|
|
|
|
## 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.
|
|
```
|