Does it support all programming languages?

While the skill provides specific examples for major languages like TypeScript, Python, and Rust, the underlying pattern of structured @ai-tags can be applied to any language that supports comments.

Is this compatible with my existing documentation tools?

Yes, these patterns are designed to be compatible with standard comment formats used by popular tools like JSDoc, Sphinx, TypeDoc, and Javadoc.

What is the benefit of using @ai-tech-debt markers?

They allow the AI to recognize 'temporary' code and its limitations, preventing the AI from accidentally building new features on top of unstable or deprecated logic.

How does this skill improve Claude's coding output?

By providing structured metadata about performance, security, and intent, Claude can make decisions that align precisely with your specific architectural constraints and safety requirements.

Can I use these annotations for automated reporting?

Absolutely. The documentation includes methods for extracting these annotations using grep and jq, allowing you to generate custom reports or integrate them into CI/CD pipelines.

Code Annotation Patterns

Name: Code Annotation Patterns
Author: TheBushidoCollective

byTheBushidoCollective

•

Learning & Documentation

Enhances code maintainability and AI comprehension using structured metadata tags for security, performance, and technical debt.

Code Annotation Patterns provides a standardized framework for embedding rich metadata directly into your source code to optimize AI-assisted development workflows. By using structured semantic tags like @ai-security or @ai-performance, developers can provide explicit context to Claude Code about architectural decisions, known limitations, and critical safety requirements. This skill bridges the gap between raw code and developer intent, facilitating more accurate code reviews, automated documentation, and proactive risk identification across various programming languages.

Key Features

01Accessibility (a11y) and test coverage markers for automated compliance auditing

02Standardized semantic tags for tracking tech debt, security risks, and performance bottlenecks

03Structured metadata support using JSON blocks for complex tool integration

04Language-specific annotation patterns for TypeScript, Python, Java, Go, and Rust

05Change impact and dependency markers to prevent breaking changes during refactoring

0639 GitHub stars

Use Cases

01Documenting complex architectural patterns and technical debt to guide future AI-led refactoring

02Providing performance constraints and profiling data to help Claude suggest better optimizations

03Flagging security-sensitive code blocks with specific CWE references and mitigation strategies

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add thebushidocollective/han code-annotation-patterns

For use in Claude.ai and ChatGPT

Download Skill