New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Markdown Document Structurer

by ArabelaTso in ArabelaTso/Skills-4-SE

Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability.

Apache-2.0Auto-check passedDocuments & Office

Install Markdown Document Structurer

skills CLI
$ npx skills add ArabelaTso/Skills-4-SE --skill markdown-document-structurer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ArabelaTso/Skills-4-SE markdown-document-structurer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ArabelaTso/Skills-4-SE.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/markdown-document-structurer .claude/skills/markdown-document-structurer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
markdown-document-structurer
GitHub stars
253
Token cost
~2.2k tokens
SKILL.md length
823 words
Files
4 (incl. scripts, references)
Skills in repo
150
Repo updated
First seen
Licence
Apache-2.0

At a glance

Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability.

  • Works in 5 steps: Analyze Current Structure → Identify Issues → Plan Restructuring → …
  • Claude needs to:
  • SKILL.md covers Workflow, Document Type Guidelines, Formatting Standards and Content Preservation Rules, plus 3 more sections
  • Runs Python scripts from its folder; calls python

What it does

Markdown Document Structurer is an agent skill from ArabelaTso/Skills-4-SE. 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…

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 5 other files, including scripts and reference files (for example `references/document-patterns.md`, `references/markdown-best-practices.md` and `scripts/analyze_structure.py`).

It sits in Documents & Office, covering Technical documentation, Markdown and Plain language and style rules. The repository describes itself as: A curated list of 180+ useful Claude Skills for Software Engineering and resources for customizing AI for SE workflows. The licence is Apache-2.0.

When your agent uses it

  • Claude needs to:
  • Fix heading hierarchy issues (skipped levels
  • Update table of contents
  • Standardize formatting (lists

Example prompts

  • “Use the markdown-document-structurer skill to reorganiz markdown documents into well-structured, consistent format while preserving content and…”
  • “/markdown-document-structurer”

Requirements

  • Python 3
  • Node.js

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Analyze Current Structure
  2. Identify Issues
  3. Plan Restructuring
  4. Apply Restructuring
  5. Verify Results

What it can do on your machine

Read from SKILL.md and the folder at commit 4f38503. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Markdown Document Structurer loads about 2.2k tokens when it runs, and up to ~4.2k if it reads all its reference files. Until then it costs about 147 tokens; SKILL.md has 823 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~147
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from ArabelaTso/Skills-4-SE at commit 4f38503, republished under its Apache-2.0 licence (© ArabelaTso). 823 words, ~2,200 tokens.

Download SKILL.mdSave it as .claude/skills/markdown-document-structurer/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
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:

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 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
  • 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 for complete formatting guidelines.

Show full SKILL.md (333 more words)Show less

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

© ArabelaTso, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts, references) in skills/markdown-document-structurer of ArabelaTso/Skills-4-SE.

  • SKILL.md
  • references/document-patterns.md
  • references/markdown-best-practices.md
  • scripts/analyze_structure.py

Open the folder on GitHubat commit 4f38503

Compare with similar skills

Markdown Document Structurer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Markdown Document Structurer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Markdown Document Structurer this skillArabelaTso/Skills-4-SE253—~2.2kAutomated safety check: PassApache-2.0
Tabler Docs Writertabler/tabler42k—~2.5kAutomated safety check: PassMIT
Review Docsvideojs/video.js40k—~413Automated safety check: PassCustom licence
Rstack Docs Writerweb-infra-dev/rstest505—~361Automated safety check: PassMIT
Create EvaluationsGAIK-project/gaik-toolkit100—~2.3kAutomated safety check: PassMIT
Technical Writing Standardcursor/plugins10k10 repos~2.4kAutomated safety check: PassNone

Similar skills

  • Tabler Docs Writer

    tabler/tabler

    Writes and updates Tabler documentation pages in simple English following the repository's page schema, and flags new components that have no docs yet.

    42k GitHub stars~2.5k tokensUpdated today
    DevelopmentAuto-check passed

  • Review Docs

    videojs/video.js

    Review Video.js documentation without editing it. An agent skill from videojs/video.js.

    40k GitHub stars~413 tokensUpdated today
    Documents & OfficeAuto-check passed

  • Rstack Docs Writer

    web-infra-dev/rstest

    Write or revise Markdown and MDX documentation, including READMEs, guides, and Rspress-based docs.

    505 GitHub stars~361 tokensUpdated today
    Documents & OfficeAuto-check passed

  • Create Evaluations

    GAIK-project/gaik-toolkit

    Creates evaluation documentation for a GAIK component in both locations: evaluationlayer/evalmethods/{component}eval/ (README + optional script stubs) and…

    100 GitHub stars~2.3k tokensUpdated yesterday
    Documents & OfficeAuto-check passed

  • Technical Writing Standard

    cursor/plugins

    Official

    Applies four layers of technical-writing rules to docs, RFCs, readmes, PR descriptions and commit messages so a tired engineer follows them on the first read.

    10k GitHub starsUsed in 10 repos~2.4k tokens
    Writing & ContentAuto-check passed

  • Suiko

    nwiizo/suiko

    日本語文書のAI由来の均一さ、翻訳調、不自然さ、論旨、読解負荷を、決定的なRust CLIと目視で診断し、依頼に応じて書く・直す。日本語の学術論文・研究報告では、中心命題、用語、論証、DOCX/PDF納品を監査契約で確認する。Use when the user explicitly mentions suiko, asks whether Japanese text looks…

    114 GitHub stars~1.8k tokensUpdated today
    Documents & OfficeAuto-check passed

More from ArabelaTso/Skills-4-SE

All 150 skills in this repo

  • Framework Migration Assistant

    ArabelaTso/Skills-4-SE

    Automatically migrate Python web applications between frameworks (Flask → FastAPI, Django → FastAPI).

    253 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Metamorphic Test Generator

    ArabelaTso/Skills-4-SE

    Generate test cases using metamorphic testing by applying transformations based on metamorphic properties.

    253 GitHub stars~798 tokensUpdated 1 mo ago
    Auto-check passed

  • Reproduction Trace Instrumenter

    ArabelaTso/Skills-4-SE

    Instruments programs to capture execution traces specifically for reproducing reported bugs, enabling consistent replay and diagnosis of failures.

    253 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed

  • Spring Mvc To Boot Migrator

    ArabelaTso/Skills-4-SE

    Automatically migrate Spring MVC applications to Spring Boot.

    253 GitHub stars~2.2k tokensUpdated 1 mo ago
    Auto-check passed

  • State Snapshot Instrumenter

    ArabelaTso/Skills-4-SE

    Instrument programs (Python, C/C++, Java) to capture snapshots of key program states at runtime, including variables, memory, and call stacks.

    253 GitHub stars~2.2k tokensUpdated 1 mo ago
    Auto-check passed

Categories

Questions about Markdown Document Structurer

What does Markdown Document Structurer do?

Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability. Markdown Document Structurer is an agent skill from ArabelaTso/Skills-4-SE. Reorganizes markdown documents into well-structured, consistent format while preserving content and improving readability.

When should I use Markdown Document Structurer?

Markdown Document Structurer fits situations like: Claude needs to:; fix heading hierarchy issues (skipped levels; update table of contents; standardize formatting (lists.

How do I install Markdown Document Structurer in Claude Code?

Run `npx skills add ArabelaTso/Skills-4-SE --skill markdown-document-structurer -a claude-code`. Or copy the skill folder (skills/markdown-document-structurer in ArabelaTso/Skills-4-SE) into .claude/skills/markdown-document-structurer in your project. Claude Code loads it when a task matches its description.

How do I install Markdown Document Structurer in Codex?

Run `npx skills add ArabelaTso/Skills-4-SE --skill markdown-document-structurer -a codex`. Or copy the skill folder (skills/markdown-document-structurer in ArabelaTso/Skills-4-SE) into .agents/skills/markdown-document-structurer in your project. Codex loads it when a task matches its description.

Can I use Markdown Document Structurer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ArabelaTso/Skills-4-SE --skill markdown-document-structurer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/markdown-document-structurer, .gemini/skills/markdown-document-structurer, .github/skills/markdown-document-structurer and .opencode/skills/markdown-document-structurer in your project.

What does Markdown Document Structurer need to run?

Going by SKILL.md and its folder, Markdown Document Structurer needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python 3; Node.js.

Does Markdown Document Structurer access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Markdown Document Structurer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Markdown Document Structurer use?

Markdown Document Structurer is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Markdown Document Structurer use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2k tokens, read only when the agent opens those files.

What are the alternatives to Markdown Document Structurer?

Skills that share tags, products or a category with Markdown Document Structurer: Tabler Docs Writer (tabler/tabler, 42k stars), Review Docs (videojs/video.js, 40k stars), Rstack Docs Writer (web-infra-dev/rstest, 505 stars) and Create Evaluations (GAIK-project/gaik-toolkit, 100 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Markdown Document Structurer?

ArabelaTso (a GitHub user) maintains it in ArabelaTso/Skills-4-SE, which has 253 GitHub stars. The repository holds 150 skills in this directory. The repository was last updated on August 21, 2026.

Source: ArabelaTso/Skills-4-SE on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.