aigr-annotator

Annotate source code with structured review comments and extract them into .aigr JSON sidecar files.

Updated Sep 7, 2026
One-click install
npx skills add https://github.com/deriye/.agents-work --skill aigr-annotator-deriye
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: aigr-annotator
Source: https://github.com/deriye/.agents-work/tree/main/skills/aigr-annotator
Command: npx skills add https://github.com/deriye/.agents-work --skill aigr-annotator-deriye

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Code review feedback often lives in chat threads or external tools and gets disconnected from the code it references. This Skill lets you embed structured review annotations directly in source files as comment blocks, then extract them into .aigr sidecar files that a VS Code extension renders as gutter icons, line highlights, and hover tooltips. ## Core Features & Use Cases - Structured Review Blocks: Wrap code in <<<AIGR ... AIGR>>> comment markers with an ID, a [category:LEVEL] label (severity, confidence, or custom), a one-line note, and optional multi-line descriptions. - Validation and Extraction: A bundled Python script validates block formatting (malformed headers, unclosed blocks, missing code, duplicate IDs) and extracts annotations into .aigr JSON sidecars while stripping markers from the source. - Multi-Language Support: Works with Python, JavaScript, TypeScript, C/C++, Rust, Go, Java, Kotlin, C#, Ruby, Shell, YAML, TOML, and more, using each language's native comment syntax. - Use Case: While reviewing a pull request, flag a potential null-pointer bug with a [severity:CRITICAL] block and an N+1 query with a [confidence:MEDIUM] block, then run the extractor so reviewers see the annotations rendered inline in VS Code. ## Quick Start Ask the AI to annotate the current source file with AIGR review blocks flagging potential bugs, then run the bundled extractor script to validate and generate the .aigr sidecar files.

Frequently Asked Questions about aigr-annotator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add structured review comments to source code?▼

Wrap the code in <<<AIGR and AIGR>>> comment markers using the file's native comment syntax. The opening line needs an ID, a [category:LEVEL] label like [severity:CRITICAL], and a one-line note, with optional description lines before the code.

How do I extract AIGR annotations into .aigr files?▼

Run the bundled extract_aigr.py script with the target file or directory as an argument. It validates all blocks, strips the markers from the source in place, and writes a .aigr JSON sidecar next to each annotated file.

Which programming languages support AIGR annotation blocks?▼

The extractor supports .py, .js, .ts, .tsx, .jsx, .cpp, .c, .h, .hpp, .rs, .go, .java, .kt, .cs, .rb, .sh, .bash, .yaml, .yml, .toml, .txt, and .md files. Additional extensions can be registered with the --ext flag.

Why does AIGR extraction fail with validation errors?▼

Common causes are malformed headers missing the ID, [category:LEVEL] label, or note; unclosed blocks lacking the AIGR>>> marker; blocks with no code lines; or duplicate IDs within one file. Run the script with --validate to list every error with file and line numbers.

Can I use custom categories besides severity and confidence?▼

Yes, any [category:LEVEL] pair works, such as [priority:URGENT] or [risk:HIGH]. Unknown categories render in grey by default in VS Code, and their colors can be configured through the aigr.labels setting.