Skip to main content

README Generation Skill

Overview​

Skill for automatically generating CODITECT-compliant README.md files by analyzing directory contents and selecting appropriate templates.

When to Use​

Use this skill when:

  • Creating documentation for new directories
  • Filling gaps in README coverage
  • Standardizing existing READMEs
  • Preparing project for production
  • Onboarding projects to CODITECT

Capabilities​

Level 1: Single README​

  • Analyze one directory
  • Select appropriate template
  • Generate README.md

Level 2: Batch Generation​

  • Find all directories missing README
  • Generate READMEs for each
  • Report coverage improvement

Level 3: Full Documentation​

  • All Level 2 capabilities
  • Update existing READMEs
  • Ensure cross-linking
  • Validate quality

Templates​

TemplateUse ForSections
MinimalSimple dirs, <5 filesTitle, Contents
StandardMost directoriesTitle, Overview, Contents, Usage
ComprehensiveProject rootsFull documentation

Usage​

Single Directory​

/agent readme-generator "Create README for docs/guides/"

All Missing READMEs​

/agent readme-generator "Generate all missing READMEs"

Specific Template​

/agent readme-generator "Create comprehensive README for project root"

Output​

Generated README Structure​

# Directory Name

## Overview
[Auto-generated description]

## Contents
| Item | Description |
|------|-------------|
[Auto-generated list]

## Usage
[If applicable]

Generation Report​

## README Generation Report

Coverage: 67% → 100%
Generated: 15 READMEs

| Directory | Template | Status |
|-----------|----------|--------|
| docs/ | Standard | ✓ |
| scripts/ | Standard | ✓ |

Standards Applied​

  • README-STANDARD.md
  • FILE-NAMING-CONVENTIONS.md
  • file-structure-analysis - Identify missing READMEs
  • project-organization - Full organization workflow

Example​

Input: "Generate missing READMEs"

Output:
Scanned: 45 directories
Missing: 15 READMEs

Generated:
- docs/README.md (Standard)
- docs/guides/README.md (Standard)
- scripts/README.md (Standard)
- scripts/utils/README.md (Minimal)
...

Coverage: 67% → 100%

Success Output​

When successful, this skill MUST output:

✅ SKILL COMPLETE: readme-generation

Completed:
- [x] Scanned directory structure
- [x] Selected appropriate templates
- [x] Generated README files
- [x] Updated coverage metrics

Outputs:
- Generated 15 README.md files
- Coverage improved: 67% → 100%
- All files comply with README-STANDARD.md

Completion Checklist​

Before marking this skill as complete, verify:

  • Directory structure analyzed correctly
  • Appropriate template selected for each directory
  • All README.md files created with proper formatting
  • Cross-linking between READMEs established (if applicable)
  • Coverage metrics calculated and reported
  • All generated files pass README-STANDARD.md validation

Failure Indicators​

This skill has FAILED if:

  • ❌ No directories found or directory structure unreadable
  • ❌ Template selection logic produced errors
  • ❌ Generated README files have syntax errors or missing sections
  • ❌ Coverage metrics cannot be calculated
  • ❌ Generated files don't comply with README-STANDARD.md

When NOT to Use​

Do NOT use this skill when:

  • Only need to update a single existing README (use direct file editing instead)
  • Directory structure is not finalized
  • Custom README requirements conflict with standard templates
  • Need interactive README with dynamic content
  • Directory contains specialized documentation requiring manual authoring

Use alternatives:

  • Manual README creation for complex, highly customized documentation
  • file-structure-analysis skill for just scanning without generation
  • Direct editing for minor README updates

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Overwriting custom READMEsLoses manually crafted contentCheck for existing READMEs, skip or merge
Wrong template selectionComprehensive template for simple dirsUse directory complexity heuristics
Missing coverage trackingCan't measure improvementAlways calculate before/after metrics
No cross-linkingIsolated documentationGenerate navigation links between READMEs
Ignoring standardsInconsistent documentationAlways validate against README-STANDARD.md

Principles​

This skill embodies:

  • #1 Recycle → Extend → Re-Use → Create - Uses template system for efficient generation
  • #3 Keep It Simple - Minimal template for simple directories, comprehensive only when needed
  • #5 Eliminate Ambiguity - Clear template selection criteria based on directory analysis
  • #6 Clear, Understandable, Explainable - Generated READMEs follow standard structure
  • #8 No Assumptions - Scans actual directory structure, doesn't assume content

Version: 1.0.0 Created: 2026-01-02