What is flatten-section?

This Claude skill automates the complex process of restructuring nested documentation directories into a standardized, flat file hierarchy. It optimizes documentation discoverability by consolidating equipment pages, manuals, and media assets into a single level, while simultaneously enforcing naming conventions, updating internal markdown links, and generating structured overview pages with maintenance schedules.

When should I use flatten-section?

flatten-section is useful in the following scenarios: • Case 1: Simplifying deeply nested technical documentation (e.g., moving files from 'docs/power/equipment/model/manuals/' to a root 'docs/power/' folder) to improve navigation and reduce click depth. • Case 2: Standardizing a knowledge base by automatically renaming files to kebab-case and ensuring all associated PDF manuals and images are co-located with their respective markdown articles. • Case 3: Migrating legacy documentation sections to a modern format that requires a mandatory '_overview.md' with auto-generated equipment tables and system specifications.

name	flatten-section
description	Flatten a documentation section to remove nested directories. Use when you need to simplify a docs section like power/, navigation/, or appliances/ to have a flat structure with equipment pages at the root level.
allowed-tools	Bash(rm:), Bash(mv:), Bash(mkdir:), Bash(ls:), Bash(find:*), Read, Edit, Write, Glob, Grep

Flatten Documentation Section

Restructure a nested documentation section into a flat structure following these conventions:

Target Structure

Each section folder should contain:

_overview.md - Section overview with heading "# Overview" (underscore prefix ensures it sorts first in nav)
<equipment-name>.md - Equipment pages with kebab-case names matching the product
<equipment-name>-*.pdf - Associated PDF manuals in same directory
<equipment-name>-*.jpg/png - Associated images in same directory

Steps

Identify the section to flatten (e.g., docs/power/, docs/navigation/)
Delete index.md if it exists (causes duplicate nav entries)
Rename systems.md to _overview.md if it exists
Flatten equipment pages:
- Move equipment/<model>.md → <model>.md
- Move equipment/<model>/manuals/*.pdf → keep original PDF names in same directory
- Move <subfolder>/<model>.md → <model>.md
- Rename equipment files to match product name in kebab-case
Update links in markdown files to reflect new paths (PDFs now in same directory)
Update _overview.md to provide actual content:
- Heading must be # Overview (not section-specific like "# Power Systems")
- Brief description of the section
- Equipment table linking to all equipment pages in the section
- Summary of each major system with key specs from equipment pages
- Maintenance schedule table
Cleanup empty directories

Overview Template

# Overview

Brief description of this section's systems.

## Equipment

| Equipment | Description |
|-----------|-------------|
| [Product Name](product-name.md) | Brief description |

## System Name

Summary with key specs and link to [equipment page](equipment.md).

## Maintenance Schedule

| Task | Frequency |
|------|-----------|
| Task name | Weekly/Monthly/Annually |

Naming Convention

Equipment markdown: <manufacturer>-<model>.md (e.g., whale-supersub-smart-1100.md)
PDF manuals: <year>-<manufacturer>-<model>-<description>-<lang>.pdf or descriptive name
Images: <equipment-name>-<description>.jpg

Example

Before:

docs/power/
├── index.md
├── systems.md
├── equipment/
│   ├── battery-monitor.md
│   └── battery-monitor/
│       └── manuals/
│           └── manual.pdf

After:

docs/power/
├── _overview.md
├── battery-monitor.md
└── battery-monitor-manual.pdf

flatten-section

When & Why to Use This Skill

Use Cases