Agent Md Refactor

Agent Md Refactor is a community skill for automating markdown documentation refactoring in agent-based workflows, covering structure normalization, heading hierarchy correction, content reorganization, and batch processing of markdown files across repositories.

What Is This?

Overview

Agent Md Refactor provides patterns for systematically restructuring markdown documentation using automated agent workflows. It covers heading hierarchy analysis and correction, section reordering based on configurable templates, link validation and path updating after file moves, frontmatter normalization across document collections, and batch refactoring operations that maintain consistency across large documentation sets. The skill enables teams to keep documentation structured and maintainable as projects grow.

Who Should Use This

This skill serves documentation engineers maintaining large markdown repositories that need periodic structural cleanup, development teams using agent workflows to enforce documentation standards, and technical writers refactoring legacy markdown into standardized templates.

Why Use It?

Problems It Solves

Documentation accumulated over time develops inconsistent heading levels, section ordering, and formatting conventions. Manual refactoring of hundreds of markdown files is tedious and error prone. Moving or renaming files breaks internal links that are hard to find without automated scanning. Frontmatter fields drift from the expected schema as different contributors add documents over time.

Core Highlights

Heading hierarchy analysis detects skipped levels and inconsistent nesting patterns. Template-based reordering moves sections into a canonical order defined by the team. Link scanning identifies broken references and suggests corrections after file reorganization. Frontmatter validation checks required fields and normalizes values against a defined schema.

How to Use It?

Basic Usage

from dataclasses import dataclass, field
from pathlib import Path
import re

@dataclass
class HeadingNode:
    level: int
    text: str
    line_number: int

class MarkdownAnalyzer:
    def __init__(self, content: str):
        self.content = content
        self.headings: list[HeadingNode] = []
        self._parse_headings()

    def _parse_headings(self):
        for i, line in enumerate(self.content.split('\n')):
            match = re.match(r'^(#{1,6})\s+(.+)', line)
            if match:
                self.headings.append(HeadingNode(
                    level=len(match.group(1)),
                    text=match.group(2).strip(),
                    line_number=i + 1))

    def find_skipped_levels(self) -> list[dict]:
        issues = []
        for i in range(1, len(self.headings)):
            prev = self.headings[i - 1].level
            curr = self.headings[i].level
            if curr > prev + 1:
                issues.append({
                    "line": self.headings[i].line_number,
                    "heading": self.headings[i].text,
                    "expected": prev + 1,
                    "found": curr})
        return issues

    def get_section_order(self) -> list[str]:
        return [h.text for h in self.headings]

Real-World Examples

from dataclasses import dataclass, field
from pathlib import Path
import re

@dataclass
class RefactorRule:
    name: str
    pattern: str
    replacement: str

class BatchMarkdownRefactor:
    def __init__(self, root_dir: str):
        self.root = Path(root_dir)
        self.rules: list[RefactorRule] = []
        self.results: list[dict] = []

    def add_rule(self, rule: RefactorRule):
        self.rules.append(rule)

    def scan_files(self) -> list[Path]:
        return sorted(self.root.rglob('*.md'))

    def apply_rules(self, content: str) -> tuple[str, int]:
        changes = 0
        for rule in self.rules:
            updated = re.sub(rule.pattern,
                             rule.replacement, content)
            if updated != content:
                changes += 1
                content = updated
        return content, changes

    def process_all(self, dry_run: bool = True) -> dict:
        files = self.scan_files()
        total_changes = 0
        for file_path in files:
            original = file_path.read_text(encoding='utf-8')
            updated, changes = self.apply_rules(original)
            if changes > 0:
                self.results.append({
                    "file": str(file_path),
                    "changes": changes})
                total_changes += changes
                if not dry_run:
                    file_path.write_text(
                        updated, encoding='utf-8')
        return {"files_scanned": len(files),
                "files_changed": len(self.results),
                "total_changes": total_changes}

Advanced Tips

Run refactoring in dry-run mode first to review proposed changes before writing files. Combine heading fixes with link updates in a single pass to avoid intermediate broken states. Store refactoring rules as configuration files that can be versioned and shared across repositories for consistent documentation standards.

When to Use It?

Use Cases

Normalize heading hierarchies across a documentation site before publishing to ensure consistent navigation structure. Batch update internal links after reorganizing a repository directory layout. Validate and repair frontmatter fields across hundreds of markdown files to match a required schema.

Related Topics

Markdown linting tools, documentation site generators, content management automation, agent-based file processing, and static site build pipelines.

Important Notes

Requirements

Python with file system access for reading and writing markdown files. A defined documentation template or schema specifying expected structure. Version control for tracking changes and reverting problematic refactoring operations.

Usage Recommendations

Do: always run refactoring with dry-run mode first to preview changes before modifying files. Commit documentation to version control before running batch operations so changes can be reviewed. Define explicit rules for heading levels and section order rather than relying on implicit conventions.

Don't: refactor markdown files without backing up or committing first, as regex-based changes can produce unexpected results. Apply rules globally without excluding generated or vendor documentation that should not be modified. Skip link validation after moving files, which will leave readers with broken references.

Limitations

Regex-based refactoring cannot understand semantic meaning, so it may make incorrect changes in ambiguous cases. Complex markdown extensions like custom directives may not be handled by standard parsing patterns. Large documentation sets require careful testing to ensure batch operations produce correct results across all file variations.