update-markdown-file-index
github/awesome-copilot
Automatically generate or refresh a file index table in a markdown doc from a folder's contents.
What is update-markdown-file-index?
This skill scans a specified folder and generates or updates an index/table section within a target markdown file listing the folder's contents. It's useful for keeping documentation file indexes (like a docs directory listing) automatically in sync with actual files."
- Scans a target markdown file to detect existing index/table sections
- Lists files in a specified folder matching an optional pattern
- Extracts file metadata such as name, type, and inferred description
- Generates a list, detailed table, or categorized sections format for the index
- Replaces existing index sections or adds a new one while preserving surrounding markdown structure
- Validates resulting markdown syntax and sorts files alphabetically with relative links
How to install update-markdown-file-index
npx skills add https://github.com/github/awesome-copilot --skill update-markdown-file-index- A markdown file to update and a folder of files to index, accessible to the agent
How to use update-markdown-file-index
- 1.Open or specify the target markdown file you want updated (the ${file} variable)
- 2.Provide the folder path to scan for files (${input:folder}) and optionally a file pattern filter (${input:pattern})
- 3.Invoke the skill to have it scan the markdown file's existing structure and the folder's files
- 4.Review the generated or updated index/table section for accuracy
- 5.Confirm or adjust the format (simple list, detailed table, or categorized sections) if the default choice doesn't fit
- 6.Save the updated markdown file
Use cases
- Keeping a README's 'Files' or 'Contents' section up to date with a docs folder
- Generating a table of scripts/files with descriptions for a repository
- Creating an index of templates or prompt files in a directory
- Refreshing a categorized list of files by type in project documentation
- Documentation maintainers
- Repository owners managing docs or template directories
- Developers automating README/index upkeep
update-markdown-file-index FAQ
It needs the target markdown file (${file}), the folder to scan (${input:folder}), and an optional file matching pattern (${input:pattern}).
No, it tries to find an existing index/table section and replace only that, preserving the rest of the document's structure and formatting.
It can generate a simple bullet list, a detailed table with file/type/description columns, or categorized sections grouped by file type, depending on context.
Files are sorted alphabetically by default and linked using relative paths within the repository.
Full instructions (SKILL.md)
Source of truth, from github/awesome-copilot.
name: update-markdown-file-index description: 'Update a markdown file section with an index/table of files from a specified folder.'
Update Markdown File Index
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 | Extension | Description |
| 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
Related skills
More from github/awesome-copilot and the wider catalog.
git-commit
Execute semantic git commits with conventional message analysis and intelligent staging.
excalidraw-diagram-generator
Generate Excalidraw diagrams from natural language descriptions.
documentation-writer
Create structured technical documentation using the Diátaxis framework for tutorials, how-to guides, references, and explanations.
gh-cli
GitHub CLI comprehensive reference for repositories, issues, PRs, Actions, projects, releases, and all GitHub operations from the command line.
prd
Generate comprehensive Product Requirements Documents with executive summaries, user stories, technical specs, and risk analysis.
refactor
Surgical code refactoring to improve maintainability without changing behavior.