What is bidirectional documentation linking?

It is a practice where code points to its relevant documentation (using annotations like @doc) and documentation points back to specific code files or lines, ensuring both stay synchronized and navigable.

How do I prevent documentation links from breaking?

The skill includes templates for automated validation scripts and Git pre-commit hooks that check for broken documentation links before they are merged into the repository.

Can I use this for external documentation like Wikis or Jira?

Absolutely. The skill provides standardized patterns for linking to GitHub issues, Jira tickets, Confluence pages, and official RFC specifications.

Is it compatible with OpenAPI or Swagger?

Yes, it specifically covers patterns for linking backend handlers directly to OpenAPI specifications, ensuring the API contract and implementation remain aligned.

Does this skill support line-specific links?

Yes, it includes patterns for linking to specific line ranges and anchors within Markdown files or source code, enabling precise documentation.

Documentation Linking

Name: Documentation Linking
Author: TheBushidoCollective

byTheBushidoCollective

•

Learning & Documentation

Establishes bidirectional traceability between source code and technical documentation to maintain a synchronized single source of truth.

This skill empowers developers to bridge the gap between their codebase and its documentation by implementing standardized linking patterns across various artifacts. It supports bidirectional references, allowing for seamless navigation between implementation details, architecture diagrams, API specifications, and architecture decision records (ADRs). By formalizing how links are structured—including absolute, relative, and line-specific formats—it ensures that context is preserved throughout the development lifecycle, making onboarding, debugging, and system maintenance significantly more efficient for both AI assistants and human developers.

Key Features

01Standardized annotation patterns for APIs, ADRs, and Architecture docs

02Bidirectional traceability between implementation and documentation

0339 GitHub stars

04Automated link validation scripts to prevent broken references

05Support for line-specific and anchor-based deep linking

06Cross-referencing for external issues, wikis, and technical specifications

Use Cases

01Connecting REST controllers and models to their corresponding OpenAPI/Swagger specifications

02Linking complex business logic to Architecture Decision Records (ADRs) for historical context

03Mapping integration tests to specific documentation sections and operational runbooks

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add thebushidocollective/han documentation-linking

For use in Claude.ai and ChatGPT

Download Skill