lint-markdown

CsHeng's avatarfrom CsHeng

Execute markdown validation with taxonomy-based classification and custom rules. Use when validating markdown compliance with LLM-facing writing standards or when generating structured validation reports.

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025

When & Why to Use This Skill

The lint-markdown skill is a specialized tool for automated markdown validation and governance, specifically designed to enforce LLM-facing writing standards. It utilizes a three-tier classification system (STRICT, MODERATE, LIGHT) to ensure that agent definitions, skill descriptions, and technical documentation adhere to specific structural and stylistic rules, providing structured reports and automated fixing capabilities to maintain high-quality, AI-optimized content.

Use Cases

  • Ensuring Agent Compliance: Automatically validate AGENT.md and SKILL.md files against strict LLM-facing standards to improve agent prompt clarity and performance.
  • Automated Content Governance: Apply tiered validation rules across a workspace to maintain consistency in technical documentation, governance files, and general markdown content.
  • Efficient Bulk Refactoring: Use the --fix parameter to instantly correct formatting issues, line-length violations, and common syntax errors across large repositories.
  • Structured Quality Reporting: Generate detailed JSON validation reports for integration into CI/CD pipelines or developer dashboards to track documentation health and compliance metrics.
namelint-markdown
descriptionExecute markdown validation with taxonomy-based classification and custom rules. Use when validating markdown compliance with LLM-facing writing standards or when generating structured validation reports.

Purpose

Execute Python-based markdown validation with three-tier classification based on taxonomy-rfc.md: STRICT files require full compliance with LLM-facing standards, MODERATE files apply governance rules, and LIGHT files receive basic validation.

IO Semantics

Input: File paths, directories, or global workspace scope with optional parameters.

Output: Structured linting reports with issue categorization, severity levels, and auto-fix suggestions when applicable.

Side Effects: Updates target files when using --fix parameter, generates structured reports in JSON or human-readable format.

Deterministic Steps

1. Environment Validation

  • Verify Python 3 availability.
  • Confirm validator script exists at skills/llm-governance/scripts/validator.py.
  • Validate config.yaml exists and loads properly.

2. File Classification

  • Apply STRICT classification to LLM-facing files: commands//*.md, skills//SKILL.md, agents//AGENT.md, rules//*.md, AGENTS.md, CLAUDE.md
  • Apply MODERATE classification to governance files: governance//*.md, config-sync//.md, agent-ops/**/.md
  • Apply LIGHT classification to remaining markdown files.
  • Exclude human-facing docs: docs/, examples/, tests/, ide/

3. Validation Execution

  • Run Python validator based on requested mode: python3 skills/llm-governance/scripts/validator.py for standard validation python3 skills/llm-governance/scripts/validator.py for JSON output (future)
  • Parse validator output and categorize issues by severity and type.

4. Report Generation

  • Aggregate results by file classification and issue type.
  • Generate structured summary with:
    • Total issue count and severity breakdown
    • Classification-specific compliance metrics
    • Auto-fix success rate where applicable
  • Provide actionable recommendations organized by priority.

5. Validation Compliance

  • Ensure all processing respects skills/llm-governance/rules/99-llm-prompt-writing-rules.md constraints.
  • Apply imperative communication patterns in all output.
  • Maintain 100-character line limits in generated reports.

Safety Constraints

  • Never modify files without explicit --fix parameter.
  • Preserve original file content through backup mechanisms when fixing.
  • Respect file exclusions and never scan excluded directories.
  • Validate tool chain compatibility before executing validator.