moilanik 191f9f4f2a refactor(ai-skills): harden control flow and reduce instruction drift

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.

2026-04-21 16:01:21 +03:00

2.2 KiB

Raw Permalink Blame History

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.

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

Scope Ownership
- README owns entrypoint content only.
- Detailed architecture, decisions, and deep explanations belong in docs/.
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.
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

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

2.2 KiB Raw Permalink Blame History