Markdown TOC

Generate a table of contents from Markdown headings with configurable levels, formats, and unique anchors, excluding headings inside code blocks.

Security Scan

The skill's code and instructions match its description: it reads a Markdown file, extracts headings (skipping code blocks), and writes a TOC — no network, secrets, or unexpected privileges are requested.

Purpose & Capability

Name/description align with the included script and README. The Python script implements heading extraction, slug generation, duplicate handling, and output formatting as described.

Instruction Scope

SKILL.md instructs running the included Python script against a user-supplied file and only reads/writes the specified input/output paths. It explicitly avoids headings inside code blocks. Minor note: the instructions reference an installation path (~/.openclaw/skills/markdown-toc/markdown_toc.py) which assumes the skill is installed there; otherwise README uses a relative invocation. No instructions ask the agent to read unrelated files or env vars.

Install Mechanism

There is no install spec (instruction-only) and the repository contains a single small Python script. No downloads or external installers are used.

Credentials

The skill declares no required environment variables or credentials. Minor inconsistency: SKILL.md/README show invoking the script with the 'python' command but required-binaries lists none; the platform will need Python available to run the script.

Persistence & Privilege

always is false and the skill does not request persistent system modifications or access to other skills/configs. disable-model-invocation is false (normal) so the agent could invoke it autonomously, but that is expected for user-invocable skills.

Assessment

This skill appears to do exactly what it says: local processing of Markdown files to generate a TOC. Before installing, ensure your environment has Python available (the SKILL.md calls 'python'), and only pass files you trust (the script will read the input file and optionally write the output path you provide). There are no network calls or secret/env var requirements. If you want to be extra cautious, inspect the included markdown_toc.py (present here) and run it manually on a sample file to confirm behavior before allowing autonomous agent invocation.

Generate a Table of Contents (TOC) from Markdown headings.

Description

This skill extracts headings from Markdown files and generates a well-formatted table of contents. It supports standard Markdown heading syntax (#, ##, ###, etc.) and outputs a clean, indented TOC that can be inserted back into your document.

Usage

# Generate TOC from a markdown file
python ~/.openclaw/skills/markdown-toc/markdown_toc.py <input-file> [options]

# Options:
#   --output, -o    Output file (default: stdout)
#   --min-level     Minimum heading level to include (default: 1)
#   --max-level     Maximum heading level to include (default: 6)
#   --format        Output format: "list" or "links" (default: list)

Examples

# Basic usage - print TOC to stdout
python ~/.openclaw/skills/markdown-toc/markdown_toc.py README.md

# Save TOC to a file
python ~/.openclaw/skills/markdown-toc/markdown_toc.py README.md -o toc.md

# Include only level 2-3 headings
python ~/.openclaw/skills/markdown-toc/markdown_toc.py README.md --min-level 2 --max-level 3

# Generate TOC with anchor links
python ~/.openclaw/skills/markdown-toc/markdown_toc.py README.md --format links

Features

• Extracts headings from # to ###### (levels 1-6)
• Supports both bullet list and linked TOC formats
• Configurable heading level filtering
• Handles duplicate headings with unique anchors
• Preserves heading text formatting (bold, italic, code)
• Skips headings inside code blocks

Output Formats

List Format (default)

- Heading 1
  - Heading 2
    - Heading 3

Links Format

- [Heading 1](#heading-1)
  - [Heading 2](#heading-2)
    - [Heading 3](#heading-3)