{"id":32740637,"url":"https://github.com/s2005/markdown-linter-fixer-skill","last_synced_at":"2026-06-25T06:31:32.772Z","repository":{"id":319364353,"uuid":"1078490726","full_name":"s2005/markdown-linter-fixer-skill","owner":"s2005","description":"A Claude Agent Skill that systematically fixes linting issues in markdown files using markdownlint-cli2","archived":false,"fork":false,"pushed_at":"2026-03-20T14:43:45.000Z","size":188,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T06:47:53.818Z","etag":null,"topics":["documentation","formatting","linter","markdown","markdownlint","md","skill"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s2005.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T20:22:53.000Z","updated_at":"2026-03-20T14:43:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"3b5bc527-3173-4f50-b0b0-27659add7e71","html_url":"https://github.com/s2005/markdown-linter-fixer-skill","commit_stats":null,"previous_names":["s2005/markdown-linter-fixer-skill"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/s2005/markdown-linter-fixer-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s2005%2Fmarkdown-linter-fixer-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s2005%2Fmarkdown-linter-fixer-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s2005%2Fmarkdown-linter-fixer-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s2005%2Fmarkdown-linter-fixer-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s2005","download_url":"https://codeload.github.com/s2005/markdown-linter-fixer-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s2005%2Fmarkdown-linter-fixer-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34763481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","formatting","linter","markdown","markdownlint","md","skill"],"created_at":"2025-11-03T10:01:26.862Z","updated_at":"2026-06-25T06:31:32.766Z","avatar_url":"https://github.com/s2005.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Linter Fixer\n\nA Claude Agent Skill that systematically fixes linting issues in markdown files using markdownlint-cli2.\n\n## Overview\n\nThis skill provides Claude with structured workflows to diagnose, fix, and verify markdown formatting issues across projects. It focuses on the most common real-world issues, especially MD029 errors caused by improper indentation of content within ordered lists.\n\n**Available for multiple platforms:**\n\n- **Claude Code**: Install as a plugin via marketplace\n- **VS Code**: Install as a custom chat mode for GitHub Copilot\n- **Codex CLI**: Install as a local Codex skill\n\n## What This Skill Does\n\nThe Markdown Linter Fixer skill enables Claude to:\n\n- **Verify and install** markdownlint-cli2 if needed\n- **Scan markdown files** at root level and recursively through subdirectories\n- **Categorize errors** by type with frequency analysis\n- **Apply automatic fixes** for correctable issues\n- **Guide manual corrections** with detailed reference documentation\n- **Focus on MD029 errors** - the most common issue with lists containing code blocks\n- **Generate comprehensive reports** showing what was fixed and what remains\n\n## Why This Skill?\n\nMarkdown linting errors are common in documentation, especially when combining:\n\n- Ordered lists with code blocks\n- Mixed content (paragraphs, blockquotes, nested lists)\n- Technical documentation with examples\n\nThe **MD029 error** (ordered list item prefix) is particularly common and confusing. This skill includes a comprehensive guide explaining the root cause: **improper indentation** of content between list items, not just numbering inconsistencies.\n\n## Quick Links\n\n- **[Installation \u0026 Troubleshooting Guide](INSTALLATION.md)** - Complete installation guide with troubleshooting\n- **[Plugin Documentation](PLUGIN.md)** - Plugin-specific features and configuration\n- **[Changelog](CHANGELOG.md)** - Version history and release notes\n\n## Installation\n\n### For Codex CLI Users\n\nUse the canonical Codex instructions in [INSTALLATION.md](INSTALLATION.md#codex-cli-installation), including [uninstall](INSTALLATION.md#uninstall-from-codex) and verification steps.\n\n### For VS Code Users (GitHub Copilot Chat)\n\n[markdown-linter-fixer mode instructions](.github/chatmodes/markdown-linter-fixer.chatmode.md)\n\nClick the button below to install the custom chat mode in VS Code:\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://aka.ms/awesome-copilot/install/chatmode?url=vscode%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fs2005%2Fmarkdown-linter-fixer-skill%2Fmain%2F.github%2Fchatmodes%2Fmarkdown-linter-fixer.chatmode.md) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://aka.ms/awesome-copilot/install/chatmode?url=vscode-insiders%3Achat-mode%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fs2005%2Fmarkdown-linter-fixer-skill%2Fmain%2F.github%2Fchatmodes%2Fmarkdown-linter-fixer.chatmode.md)\n\n\u003e **Requirements:** GitHub Copilot subscription and VS Code version 1.96 or higher (custom chat modes available from v1.101+)\n\n**What you get:**\n\n- Markdown linting and fixing workflows directly in VS Code\n- Same 6-phase systematic approach\n- Access via GitHub Copilot Chat interface\n- Works alongside your existing VS Code extensions\n\n**To use after installation:**\n\n1. Open GitHub Copilot Chat in VS Code\n2. Select \"markdown-linter-fixer\" mode\n3. Ask to fix markdown linting errors or scan your files\n4. Follow the guided workflow\n\n### For Claude Code Users\n\n**Quick start for Claude Code:**\n\n```bash\n# Add the marketplace\n/plugin marketplace add https://github.com/s2005/markdown-linter-fixer-skill\n\n# Install the plugin\n/plugin install markdown-linter-fixer@markdown-linter-fixer-marketplace\n\n# Restart Claude Code\n```\n\n**For complete installation instructions**, including:\n\n- Local development setup\n- Team deployment\n- Manual installation (Claude.ai/Desktop/API)\n- Troubleshooting\n- Uninstallation with known bug workarounds\n\nSee **[INSTALLATION.md](INSTALLATION.md)**.\n\n### Prerequisites\n\n**For VS Code users:**\n\n- VS Code version 1.96 or higher (for custom chat modes support)\n- GitHub Copilot subscription\n\n**For Claude Code users:**\n\n- Claude Code version 2.0.0 or higher (for plugin marketplace support)\n\n**For Codex CLI users:**\n\n- Codex CLI with access to `$CODEX_HOME/skills` (defaults to `~/.codex/skills`)\n\n**For all platforms:**\n\nThe skill uses `markdownlint-cli2` under the hood to perform linting and fixes. You don't need to install it beforehand - Claude/VS Code will automatically check for it and guide you through installation if needed:\n\n```bash\n# Global installation (if prompted)\nnpm install -g markdownlint-cli2\n\n# Or local to project (if prompted)\nnpm install --save-dev markdownlint-cli2\n```\n\n## Usage\n\nOnce installed, Claude/Codex automatically activates this skill when you:\n\n- Ask about \"markdown linting issues\"\n- Mention \"fixing MD029 errors\"\n- Request to \"scan markdown files\"\n- Say \"I have ordered list numbering problems\"\n- Ask to \"set up markdown linting\"\n\nIn Codex, you can also explicitly call the skill by name in your prompt:\n\n```text\nUse $markdown-linter-fixer to scan and fix markdown lint errors in this repo.\n```\n\n### Slash Command\n\nThe plugin provides a unified slash command for markdown linting:\n\n**Command Format:**\n\n```bash\n/markdown-linter-fixer:mdlinter [mode] [scope]\n```\n\n**Arguments:**\n\n- `mode` (optional): Either `check` or `fix`\n  - `check` - Scan and report issues without making changes (DEFAULT)\n  - `fix` - Scan and automatically fix all issues\n  - If not specified or invalid, safely defaults to `check` mode\n- `scope` (optional): Target file(s), folder, or pattern. Defaults to all markdown files in the project.\n\n**Examples:**\n\n```bash\n# Check all files (default mode)\n/markdown-linter-fixer:mdlinter\n\n# Explicitly check all files\n/markdown-linter-fixer:mdlinter check\n\n# Fix all files\n/markdown-linter-fixer:mdlinter fix\n\n# Check only README.md (default mode)\n/markdown-linter-fixer:mdlinter README.md\n\n# Explicitly check only README.md\n/markdown-linter-fixer:mdlinter check README.md\n\n# Fix files in docs folder\n/markdown-linter-fixer:mdlinter fix docs/\n\n# Check multiple specific files\n/markdown-linter-fixer:mdlinter check README.md CONTRIBUTING.md\n```\n\nThe check mode is useful for CI/CD or pre-commit checks, while fix mode runs the complete workflow to resolve all issues. For safety, the command always defaults to check mode when mode is not specified.\n\n### Example Requests\n\n**Simple cleanup:**\n\n```text\nFix all markdown linting errors in my project\n```\n\n**Setup from scratch:**\n\n```text\nSet up markdown linting for my documentation\n```\n\n**Specific MD029 issues:**\n\n```text\nI have ordered list numbering issues in my markdown files with code blocks\n```\n\n**Comprehensive scan:**\n\n```text\nScan all markdown files and create a report of issues\n```\n\n## Plugin Structure\n\n```tree\n.\n├── .claude-plugin/\n│   ├── plugin.json                 # Plugin manifest\n│   └── marketplace.json            # Marketplace catalog\n├── skills/                         # Skills directory\n│   └── markdown-linter-fixer/      # Skill directory\n│       ├── SKILL.md                # Main skill instructions\n│       └── references/\n│           └── MD029-Fix-Guide.md  # Detailed MD029 indentation guide\n├── examples/                       # Example files\n├── PLUGIN.md                       # Plugin documentation\n├── README.md                       # This file\n└── LICENSE                         # MIT License\n```\n\n### Progressive Disclosure Design\n\nFollowing Anthropic's recommendations, this skill uses progressive disclosure:\n\n1. **Level 1**: Metadata (`name` + `description`) - Always loaded (~50 words)\n2. **Level 2**: SKILL.md body - Loaded when skill is triggered (~2,000 words)\n3. **Level 3**: MD029-Fix-Guide.md - Loaded only when needed (~1,500 words)\n\nThis keeps Claude's context window efficient while providing comprehensive guidance when required.\n\n## Key Features\n\n### 6-Phase Workflow\n\n1. **Environment Setup**: Verify tools and configuration\n2. **Diagnostic Assessment**: Scan files and document issues\n3. **Issue Analysis**: Categorize by error type\n4. **Automatic Fixes**: Apply auto-fix for correctable issues\n5. **Manual Fixes**: Guide through remaining corrections\n6. **Verification**: Confirm completion and report results\n\n### MD029 Indentation Focus\n\nThe included reference guide focuses on the **root cause** of MD029 errors:\n\n- Explains why improper indentation breaks list continuity\n- Provides clear 4-space indentation rules\n- Shows ❌ wrong vs ✅ correct examples\n- Includes real-world before/after fixes\n- Documents when to use `\u003c!-- markdownlint-disable MD029 --\u003e`\n\n### Configuration Awareness\n\n- Respects existing `.markdownlint.json` files\n- Creates sensible defaults (disables MD013 line length)\n- Never overrides project-specific rules without permission\n\n## Common Scenarios\n\n### Scenario 1: Clean Project Setup\n\n```text\nUser: \"Set up markdown linting for my documentation\"\nClaude: [Installs markdownlint-cli2, creates config, runs diagnostic, reports results]\n```\n\n### Scenario 2: Fix Existing Issues\n\n```text\nUser: \"Fix all markdown linting errors\"\nClaude: [Scans, categorizes, auto-fixes, guides manual fixes, verifies completion]\n```\n\n### Scenario 3: MD029 Focus\n\n```text\nUser: \"My lists with code blocks show MD029 errors\"\nClaude: [Scans for MD029, loads indentation guide, fixes with proper 4-space indentation]\n```\n\n## Configuration\n\nThe skill creates `.markdownlint.json` with sensible defaults:\n\n```json\n{\n  \"MD013\": false\n}\n```\n\nThis disables the max line length rule while keeping other formatting checks active.\n\n## Development \u0026 Contribution\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/s2005/markdown-linter-fixer-skill.git\ncd markdown-linter-fixer-skill\n\n# The plugin is ready to use - skill is at skills/markdown-linter-fixer/\n# For manual installation, package just the skill:\ncd skills/markdown-linter-fixer\nzip -r ../../markdown-linter-fixer.zip SKILL.md references/\n```\n\n### Testing the Skill\n\n1. Install in Claude.ai or Claude Code\n2. Test with a project containing markdown files\n3. Verify it properly:\n   - Detects markdownlint-cli2 availability\n   - Scans files correctly\n   - Applies fixes appropriately\n   - Loads MD029 guide when needed\n   - Generates accurate reports\n\n### Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## Technical Details\n\n**Skill Type**: Workflow-based with progressive disclosure  \n**Dependencies**: markdownlint-cli2 (npm package)  \n**Supported Environments**: GitBash, WSL2, Linux, macOS  \n**File Format**: Markdown with YAML frontmatter  \n**Reference Files**: 1 (MD029-Fix-Guide.md)\n\n## Best Practices\n\n- **Start with auto-fix**: Let markdownlint-cli2 handle what it can\n- **Use the guide**: Load MD029-Fix-Guide.md for indentation issues\n- **Preserve content**: All fixes maintain original meaning\n- **Report clearly**: Always provide detailed before/after summaries\n- **Respect config**: Never override project linting rules\n\n## Security Considerations\n\nThis skill:\n\n- ✅ Only reads/writes markdown files\n- ✅ Uses standard npm package (markdownlint-cli2)\n- ✅ Requires explicit user permission for file modifications\n- ✅ Provides clear explanations before executing commands\n- ✅ No external network calls (except npm installation)\n\nAlways review the skill contents before installing, especially:\n\n- The commands it will execute\n- The files it will modify\n- The npm packages it requires\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## Resources\n\n- [Claude Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)\n- [Anthropic Skills Repository](https://github.com/anthropics/skills)\n- [markdownlint-cli2 Documentation](https://github.com/DavidAnson/markdownlint-cli2)\n- [Markdown Linting Rules (MD029)](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029)\n\n## Acknowledgements\n\nCreated following Anthropic's [Agent Skills design pattern](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).\n\nSpecial thanks to:\n\n- Anthropic for the [Skills framework](https://github.com/anthropics/skills)\n- GitHub for [GitHub Copilot](https://github.com/features/copilot) and custom chat modes support\n- GitHub [awesome-copilot](https://github.com/github/awesome-copilot) repository for [custom chat modes examples and patterns](https://github.com/github/awesome-copilot/blob/main/README.chatmodes.md)\n- David Anson for [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)\n- The CommonMark specification team\n\n## Support\n\n### Reporting Issues\n\nIf you encounter problems:\n\n1. **Check existing issues:** [GitHub Issues](../../issues)\n2. **Create new issue** with:\n   - Your operating system (Windows/macOS/Linux)\n   - Claude Code version: `claude --version`\n   - Node.js version: `node --version`\n   - markdownlint-cli2 version: `markdownlint-cli2 --version`\n   - Steps to reproduce\n   - Error messages or logs\n   - What you expected vs what happened\n\n### Get Help\n\n- **Issues**: Report bugs or request features via [GitHub Issues](../../issues)\n- **Discussions**: Ask questions in [GitHub Discussions](../../discussions)\n- **Documentation**:\n  - [Claude Skills docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)\n  - [VS Code Custom Chat Modes](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes)\n\n---\n\n**Version**: 1.5.4\n**Last Updated**: October 26, 2025\n**Compatibility**: Claude Code (Sonnet 4+), VS Code (GitHub Copilot with custom chat modes)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2005%2Fmarkdown-linter-fixer-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs2005%2Fmarkdown-linter-fixer-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs2005%2Fmarkdown-linter-fixer-skill/lists"}