markdown-document-structurer
/markdown-document-structurer
Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability. Use when Claude needs to: (1) Fix heading hierarchy issues (skipped levels, multiple h1s), (2) Generate or update table of contents, (3) Standardize formatting (lists, code blocks, emphasis, links), (4) Improve grammar and spelling, (5) Add missing standard sections (installation, usage, etc.), (6) Remove redundant or duplicate content, (7) Restructure technical docs, READMEs, or long-form content for better organization and flow.
- Author
- ArabelaTso ↗
- Repository
- Skills-4-SE ↗
- Licence
- Apache-2.0
- Last repository change
- 21.08.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.08.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/analyze_structure.py
What it does and when to use it
Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability. Use when Claude needs to: (1) Fix heading hierarchy issues (skipped levels, multiple h1s), (2) Generate or update table of contents, (3) Standardize formatting (lists, code blocks, emphasis, links), (4) Improve grammar and spelling, (5) Add missing standard sections (installation, usage, etc.), (6) Remove redundant or duplicate content, (7) Restructure technical docs, READMEs, or long-form content for better organization and flow.
Original author description
Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability. Use when Claude needs to: (1) Fix heading hierarchy issues (skipped levels, multiple h1s), (2) Generate or update table of contents, (3) Standardize formatting (lists, code blocks, emphasis, links), (4) Improve grammar and spelling, (5) Add missing standard sections (installation, usage, etc.), (6) Remove redundant or duplicate content, (7) Restructure technical docs, READMEs, or long-form content for better organization and flow.
How it works
- Workflow
- Document Type Guidelines
- Formatting Standards
- Content Preservation Rules
- Handling Redundancy
- Adding Missing Sections
- Table of Contents Generation
- Grammar and Spelling
- Output Format
- Best Practices
SKILL.md preview
--- name: markdown-document-structurer description: "Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability. Use when Claude needs to: (1) Fix heading hierarchy issues (skipped levels, multiple h1s), (2) Generate or update table of contents, (3) Standardize formatting (lists, code blocks, emphasis, links), (4) Improve grammar and spelling, (5) Add missing standard sections (installation, usage, etc.), (6) Remove redundant or duplicate content, (7) Restructure technical docs, READMEs, or long-form content for better organization and flow." --- # Markdown Document Structurer Reorganize and improve markdown documents while preserving content integrity. ## Workflow ### 1. Analyze Current Structure **Automated analysis:** ```bash python scripts/analyze_structure.py <markdown_file> ``` **Manual analysis:** - Read the document to understand content and purpose - Identify document type (README, technical doc, tutorial, article) - Note structural issues and inconsistencies ### 2. Identify Issues Check for: **Heading Hierarchy:** - Multiple h1 headings - Skipped heading levels (h1 → h3) - Inconsistent heading progression **Table of Contents:** - Missing TOC when document has 3+ main sections - Outdated TOC that doesn't match current structure - Incorrect anchor links **Formatting Consistency:** - Mixed list markers (-, *, +) - Code blocks without language specification - Inconsistent emphasis styles (** vs __, * vs _) - Inconsistent link formats **Content Issues:** - Missing standard sections for document type - Duplicate or redundant sections - Poor section organization - Grammar and spelling errors ### 3. Plan Restructuring Determine: - Target document structure based on type (see [document-patterns.md](references/document-patterns.md)) - Which sections to add, merge, or reorganize - Formatting standards to apply (see [markdown-best-practices.md](references/markdown-best-practices.md)) - Content improvements needed ### 4. Apply Restructuring Follow this order: **Step 1: Fix Heading Hierarchy** - Ensure single h1 for document title - Fix skipped levels - Maintain logical progression **Step 2: Reorganize Sections** - Reorder sections for logical flow - Merge duplicate sections - Add missing standard sections - Remove redundant content **Step 3: Generate/Update TOC** - Create TOC if document has 3+ sections - Update existing TOC to match structure - Ensure anchor links are correct **Step 4: Standardize Formatting** - Use `-` for unordered lists - Specify language for code blocks - Use `**bold**` and `*italic*` consistently - Standardize link formats - Fix spacing and blank lines **Step 5: Improve Content** - Fix grammar and spelling - Improve clarity where needed - Preserve all original information - Maintain author's voice and style ### 5. Verify Results Check: - All content preserved - Heading hierarchy correct - TOC matches structure - Formatting consistent - No broken links - Grammar improved - Document flows logically ## Document Type Guidelines ### README Files **Standard structure:** 1. Title and brief description 2. Table of contents (if 3+ sections) 3. Features/highlights 4. Installation 5. Usage examples 6. Configuration 7. Contributing 8. License **Required sections:** - Installation instructions - Basic usage example - License information See [document-patterns.md](references/document-patterns.md) for detailed README patterns. ### Technical Documentation **Standard structure:** 1. Title 2. Overview 3. Table of contents 4. Prerequisites 5. Installation/setup 6. Basic usage 7. Advanced usage 8. API reference (if applicable) 9. Examples 10. Troubleshooting 11. Additional resources **Required sections:** - Prerequisites - Installation/setup - Basic usage examples ### Long-Form Content (Articles, Tutorials) **Standard structure:** 1. Title 2. Introduction/hook 3. Table of contents 4. Main content sections 5. Conclusion 6. References/resources **For tutorials specifically:** - Prerequisites section - Step-by-step structure - Verification/testing steps - Next steps ## Formatting Standards ### Headings - Single h1 (`#`) for title - Sequential levels (no skipping) - One blank line before and after ### Lists - Use `-` for unordered lists - Proper indentation (2 or 4 spaces) - One blank line before and after ### Code Blocks - Always specify language: ```python - One blank line before and after ### Emphasis - Use `**bold**` for strong emphasis - Use `*italic*` for emphasis - Avoid mixing styles ### Links - Use inline format: `[text](url)` - Use reference format for repeated links ### Spacing - One blank line between sections - No trailing whitespace - Consistent blank line usage See [markdown-best-practices.md](references/markdown-best-practices.md) for complete formatting guidelines. ## Content Preservation Rules **Always preserve:** - All factual information - Code examples - Technical details - Links and references - Author's key points **Safe to modify:** - Grammar and spelling - Sentence structure for clarity - Section organization - Formatting consistency **Never:** - Remove content without user approval - Change technical accuracy - Alter code examples (except formatting) - Modify links or URLs ## Handling Redundancy ### Identifying Duplicates - Same section headings - Repeated installation instructions - Duplicate code examples - Overlapping explanations ### Consolidation Strategy 1. Identify all duplicate content 2. Keep the most complete version 3. Merge complementary information 4. Add cross-references if needed 5. Remove redundant sections ### Example **Before:** ```markdown ## Installation npm install package ## Installing the Package Run npm install package ## Setup Install with npm install package ``` **After:** ```markdown ## Installation Install the package using npm: ```bash npm install package ``` ``` ## Adding Missing Sections ### Detection Check document type and identify missing standard sections: - README: Installation, Usage, License - Technical docs: Prerequisites, Examples, Troubleshooting - Tutorials: Prerequisites, Verification steps, Next steps ### Adding Sections 1. Determine appropriate location in document flow 2. Add section with appropriate heading level 3. Include placeholder content or note that section needs completion 4. Inform user about added sections ### Example ```markdown ## Installation *Installation instructions to be added* ## Usage *Usage examples to be added* ``` ## Table of Contents Generation ### When to Generate - Document has 3+ main sections (h2) - Technical documentation - Long-form content (>500 lines) ### Placement - After title and description - Before main content - Use h2: `## Table of Contents` ### Format ```markdown ## Table of Contents - [Section 1](#section-1) - [Section 2](#section-2) - [Subsection 2.1](#subsection-21) - [Subsection 2.2](#subsection-22) - [Section 3](#section-3) ``` ### Anchor Generation - Lowercase all text - Replace spaces with hyphens - Remove special characters except hyphens - Example: "API Reference Guide" → `#api-reference-guide` ## Grammar and Spelling ### Approach - Fix obvious errors - Improve clarity without changing meaning - Maintain author's voice and style - Preserve technical terminology ### Common Fixes - Subject-verb agreement - Tense consistency - Article usage (a, an, the) - Common spelling errors - Punctuation ### Caution - Don't change technical terms - Preserve code-related text exactly - Keep domain-specific language - Maintain intentional informal tone ## Output Format After restructuring, provide: 1. **Summary of changes:** - Structural improvements - Sections added/removed/merged - Formatting fixes - Content improvements 2. **Restructured document:** - Complete markdown with all changes applied 3. **Notes:** - Any sections needing user input - Recommendations for further improvement - Warnings about significant changes ## Best Practices ### Analysis - Understand document purpose before restructuring - Identify document type to apply appropriate structure - Use automated analysis script for quick assessment - Note all issues before making changes ### Restructuring - Make one type of change at a time - Preserve all content unless clearly redundant - Maintain logical flow and readability - Follow established patterns for document type ### Quality - Verify all links work - Ensure TOC matches structure - Check heading hierarchy - Confirm formatting consistency - Test code blocks if possible ### Communication - Explain significant structural changes - Highlight added or removed sections - Note any content needing user input - Provide rationale for major reorganization
Files in this package (4)
- SKILL.md 9 KB
- references/document-patterns.md 5 KB
- references/markdown-best-practices.md 3 KB
- scripts/analyze_structure.py 8 KB
Versions
The database has no other skills named markdown-document-structurer.
Database snapshot: 13.11.2026 · package version deaf4f7408bd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100markdown-conventions
Markdown formatting conventions covering heading hierarchy, code blocks, tables, lists, links, images, and accessibility best practices. Apply this skill whenever writing or editing .md files -- including READMEs, documentation pages, changelogs, or any markdown content -- even… - 100obsidian-markdown-structure
Validate and enforce markdown document structure including frontmatter positioning, heading hierarchy, and content organization. Use when creating or validating markdown files. - 100docx-format-replicator
Extract formatting from existing Word documents and generate new documents with the same format but different content. Use this skill when users need to create multiple documents with consistent formatting, replicate document templates, or maintain corporate document standards… - 95heading-structure
When the user wants to optimize heading structure (H1-H6), fix heading hierarchy, or improve content structure. Also use when the user mentions "H1," "heading," "heading hierarchy," "content structure," "H2," "H3," "heading tags," "heading SEO," "multiple H1," or "heading… - 100readability
Improves the readability, formatting, and structure of text, documentation, and markdown files. Use when the user asks to clean up text, improve clarity, or structure documentation. - 91markdown-helper
Markdown文档编写辅助。当用户需要在markdown文档中生成UML图表、检查格式、生成目录时使用此skill。