Update Markdown File Index
Keep README or docs markdown in sync with a folder of files by auto-building or refreshing a file index or table section.
Overview
Update Markdown File Index is an agent skill most often used in Build (also Operate) that scans a folder and rewrites a markdown file’s index or table section from discovered files.
Install
npx skills add https://github.com/github/awesome-copilot --skill update-markdown-file-indexWhat is this skill?
- Six-step workflow: scan target markdown, discover files by pattern, analyze existing index, structure output, update sec
- Supports simple link lists or detailed tables with file name, type, description, optional size and modified date
- User supplies target file, source folder, and glob pattern via skill inputs
- Replaces an existing index section or inserts a new one while matching surrounding format
- Extracts descriptions from first-line comments, headers, or inferred purpose per file
- 6-step scan-discover-analyze-structure-update-validate process
Adoption & trust: 8.6k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your docs claim to list every file in a folder, but the table is stale the moment someone adds or renames an asset.
Who is it for?
Maintainers of skill packs, prompt libraries, or monorepo docs who want repeatable index sections without a custom script.
Skip if: Teams that need generated API reference from Javadoc or OpenAPI—this indexes paths and light metadata, not full API docs.
When should I use this skill?
You need a markdown file section updated with an index or table of files from a specified folder and pattern.
What do I get? / Deliverables
After the skill runs, the target markdown file contains an up-to-date index or table aligned with the folder and valid markdown formatting.
- Updated markdown section with file index or table
- Consistent list or table formatting matching existing doc style
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Documentation indexes belong on the Build shelf because they are created while structuring repo docs; the same skill is reused when folders change during ongoing work. Docs subphase is the canonical home for markdown structure, TOCs, and file catalogs—not application runtime code.
Where it fits
Regenerate the skills table in CONTRIBUTING.md after adding ten new prompt files.
Refresh the examples index before tagging a release so release notes match the repo.
Re-run the index update weekly as partners drop new files into a shared templates folder.
How it compares
Use instead of manually copy-pasting filenames into README tables when your agent already has repo edit access.
Common Questions / FAQ
Who is update-markdown-file-index for?
Solo and indie builders (and tiny teams) who ship agent skills or docs-heavy repos and want folder listings to stay accurate in markdown.
When should I use update-markdown-file-index?
During Build when structuring docs for a new module; before Ship or Launch when publishing a catalog page; during Operate when folders change and the README index must be refreshed.
Is update-markdown-file-index safe to install?
It implies reading and editing markdown and listing directories in your project—review the Security Audits panel on this Prism page and restrict scope to trusted repos.
SKILL.md
READMESKILL.md - Update Markdown File Index
# Update Markdown File Index Update markdown file `${file}` with an index/table of files from folder `${input:folder}`. ## Process 1. **Scan**: Read the target markdown file `${file}` to understand existing structure 2. **Discover**: List all files in the specified folder `${input:folder}` matching pattern `${input:pattern}` 3. **Analyze**: Identify if an existing table/index section exists to update, or create new structure 4. **Structure**: Generate appropriate table/list format based on file types and existing content 5. **Update**: Replace existing section or add new section with file index 6. **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 ```markdown ## 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