broken-reference skill

Overview

This skill demonstrates and helps detect broken cross-references in a skill repository. It models a minimal example where documentation links or reference targets are missing or incorrect, useful for testing tooling and validation workflows. It is implemented in Python and intended as a teaching and diagnostic artifact.

How this skill works

The skill contains example documentation and metadata with intentionally invalid links or targets. Running the checker inspects documentation files, cross-reference targets, and metadata pointers to report missing targets and malformed links. It produces a concise report listing the broken references and their locations so you can reproduce and fix the issues.

When to use it

• Validating documentation and cross-references before release
• Testing CI checks that enforce internal link integrity
• Teaching contributors how broken links manifest in metadata
• Simulating repository issues for tooling and parsers
• Integrating into linting workflows to catch regressions early

Best practices

• Run link and reference checks as part of CI on every pull request
• Keep references relative and consistent to reduce breakage
• Provide clear error messages with file and line references
• Automate fixes where possible and list suggested corrections
• Document expected reference formats and conventions for contributors

Example use cases

• Integrate into a pre-merge CI job to fail PRs with broken links
• Use as a training example in onboarding docs tooling for new devs
• Validate automated documentation generation pipelines
• Run during release checks to ensure published docs contain no dead links

FAQ