Update Markdown File Index

From the author

Update a markdown file section with an index/table of files from a specified folder.

— the description by stbenjam

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The update-markdown-file-index skill streamlines documentation management by automatically scanning a specified folder and updating a markdown file with a structured index of its contents. It intelligently detects existing index sections to perform updates while preserving document flow, or creates new sections if none are found. The skill supports multiple output formats, including simple lists and detailed tables, and extracts metadata such as file names, types, and descriptions to provide a comprehensive overview of the directory contents.

What it does

Scans specified directories to discover files matching defined patterns.
Identifies existing index sections or tables within a target markdown file.
Generates formatted lists or tables containing file links and metadata.
Updates existing markdown content while preserving document structure and formatting.
Extracts file descriptions from headers or comments to enrich the index.
Ensures valid markdown syntax and consistent formatting across the generated index.

When to use it

When maintaining documentation for a project repository with many files.
When you need to keep a README or index file synchronized with folder contents.
When you want to provide a structured overview of project assets or code modules.
When manually updating file lists becomes tedious or error-prone.

Advantages

Reduces manual effort in keeping documentation up-to-date.
Ensures consistency in how file indexes are presented.
Maintains existing document formatting and structure.
Supports flexible output formats like simple lists or detailed tables.

Usage examples

“Update the README.md file with a list of all files in the /docs folder.”: The agent scans the /docs folder, extracts file names and descriptions, and updates the README.md file with a formatted list of links.
“Create a detailed table of contents in index.md for all python files in the src directory.”: The agent identifies all .py files in /src and inserts a markdown table into index.md containing the file names, types, and descriptions.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/update-markdown-file-index/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip update-markdown-file-index.zip -d .agents/skills

Documentation by stbenjam

Update markdown file ${file} with an index/table of files from folder ${input:folder}.

Process

Scan: Read the target markdown file ${file} to understand existing structure
Discover: List all files in the specified folder ${input:folder} matching pattern ${input:pattern}
Analyze: Identify if an existing table/index section exists to update, or create new structure
Structure: Generate appropriate table/list format based on file types and existing content
Update: Replace existing section or add new section with file index
Validate: Ensure markdown syntax is valid and formatting is consistent

File Analysis

For each discovered file, extract:

Name: Filename with or without extension based on context
Type: File extension and category (e.g., .md, .js, .py)
Description: First line comment, header, or inferred purpose
Size: File size for reference (optional)
Modified: Last modified date (optional)

Table Structure Options

Choose format based on file types and existing content:

Option 1: Simple List

## Files in ${folder}

- [filename.ext](path/to/filename.ext) - Description
- [filename2.ext](path/to/filename2.ext) - Description

Option 2: Detailed Table

| File | Type | Description |
|------|------|-------------|
| [filename.ext](path/to/filename.ext) | Extension | Description |
| [filename2.ext](path/to/filename2.ext) | Extension | Description |

Option 3: Categorized Sections

Group files by type/category with separate sections or sub-tables.

Update Strategy

🔄 Update existing: If table/index section exists, replace content while preserving structure
➕ Add new: If no existing section, create new section using best-fit format
📋 Preserve: Maintain existing markdown formatting, heading levels, and document flow
🔗 Links: Use relative paths for file links within the repository

Section Identification

Look for existing sections with these patterns:

Headings containing: "index", "files", "contents", "directory", "list"
Tables with file-related columns
Lists with file links
HTML comments marking file index sections

Requirements

Preserve existing markdown structure and formatting
Use relative paths for file links
Include file descriptions when available
Sort files alphabetically by default
Handle special characters in filenames
Validate all generated markdown syntax

Files

ATTRIBUTION.mdAdded by AutoGineer885 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md2.6 KiB

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Doc Coauthoring
AnthropicOfficial
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Link-onlyGitHub stars of the source repository188.6k
Markdown Mermaid Writing
K-Dense· Community
Generates scientific Markdown documentation and Mermaid structural diagrams for workflows, schemas, and relationships.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskGitHub stars of the source repository56.4k
JSON Canvas
Steph Ango (Obsidian)· Community
Create and edit JSON Canvas files for visual organization and mapping.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository51k
Obsidian Markdown
Steph Ango (Obsidian)· Community
Generate and format Obsidian-specific Markdown syntax for notes, links, and embeds.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository51k
Faq
AnthropicOfficial
Generate a team-specific FAQ document to address recurring questions about AI tool usage and project conventions.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0GitHub stars of the source repository46.3k
Hads
Seth Hobson· Community
A standardized Markdown format for technical documentation optimized for both human readability and AI model consumption.
Documents and contentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download update-markdown-file-index.zip