crafting-effective-readmes

Generates project-type-specific README files with templates, decision matrices, and style rules.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill crafting-effective-readmes-leonardoacosta
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: crafting-effective-readmes
Source: https://github.com/leonardoacosta/skills/tree/main/leo-core/skills/crafting-effective-readmes
Command: npx skills add https://github.com/leonardoacosta/skills --skill crafting-effective-readmes-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing READMEs that stay accurate and useful is hard: sections go stale, setup instructions get duplicated across a monorepo, and different project types need different structures. This Skill provides a decision framework, per-project-type templates, and anti-pattern rules so every README matches its audience. ## Core Features & Use Cases - Project-type detection and templates: Identifies whether the target is a T3 monorepo app, internal package, CLI tool, OSS library, personal project, config directory, or internal service, then loads exactly one matching template. - Judgment framework and decision matrix: Applies audience, staleness-risk, and single-source tests plus a section matrix to decide what belongs in each README. - Reference depth on demand: Loads Standard README spec, examples, and README philosophy references only when the task requires compliance or deeper guidance. - Use Case: Ask for a README for a new package in packages/ and receive a scoped document with exports table, usage example, and gotchas, without duplicated root-level setup instructions. ## Quick Start Ask the agent to write a README for your project, for example: write a README for the packages/db workspace package in my T3 monorepo.

Frequently Asked Questions about crafting-effective-readmes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a README for a T3 monorepo package?

Identify the package as a T3 internal package, then use the inline package template with an exports table, a minimal usage example, extension steps, and a gotchas section. Link to the root README for setup instead of duplicating pnpm install or Doppler instructions.

What sections should a README include for different project types?

Required sections depend on project type: monorepo apps need prerequisites, local dev, and env vars; packages need exports and usage; OSS projects need install, usage, contributing, and license. The decision matrix and section checklist map each type to its required sections.

Should I document tRPC endpoints or database schemas in a README?

No. tRPC signatures and schema fields change with every code edit, so README prose documenting them goes stale silently. Use TypeScript types and schema files with JSDoc as the source of truth, and keep the README to low-drift content like env vars and deploy targets.

Does this support Standard README specification compliance?

Yes. For OSS projects needing Standard README compliance, the skill loads the standard-readme-spec reference plus minimal and maximal compliant examples covering required sections, ordering, and formatting rules.

When should README content be cut even if it seems useful?

Cut content that fails any of three tests: it does not serve the actual reader's next action, it drifts independently of the code it describes, or it duplicates documentation maintained at a broader scope. Link to the canonical source instead of forking a second copy.