skills.rest
Blotch-Smart-Frames
Blotch-Smart-FramesOFFICIAL
Explore all skills by this author →
WebsiteGitHub

annotate

Adds explanatory inline comments to recent code changes documenting fixes and rationale.

Updated Feb 9, 2026
Search Tags:#typescript#code review#documentation#code comments#code annotation#inline comments#tsdoc
One-click install
npx skills add https://github.com/Blotch-Smart-Frames/Board --skill annotate-blotch-smart-frames
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: annotate
Source: https://github.com/Blotch-Smart-Frames/Board/tree/main/packages/client/.claude/skills/annotate
Command: npx skills add https://github.com/Blotch-Smart-Frames/Board --skill annotate-blotch-smart-frames

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code changes often lack context about why they were made, leaving future maintainers guessing about the root cause, the bug being fixed, and why a particular approach was chosen over alternatives. ## Core Features & Use Cases - Rationale Documentation: Adds comment blocks above changed code explaining what it fixes, why it is needed, and why the approach was chosen. - Convention-Aware Formatting: Uses // comments for TypeScript logic and multi-line TSDoc blocks for function, method, and class signatures, matching project conventions. - Safety Explanation: Documents non-obvious properties like loop prevention, duplicate-call guards, and the user-facing symptoms the fix prevents. - Use Case: After fixing a bug where users saw "Not Connected" despite a successful OAuth flow, run this Skill to annotate the changed sections with the root cause and data-flow reasoning before committing. ## Quick Start Ask the assistant to annotate all code changes made in this conversation with comments explaining what was fixed and why.

Frequently Asked Questions about annotate

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

FAQPage Schema
How do I document the reasoning behind code changes inline?▼

Add comment blocks above each changed section explaining what it fixes, the root cause, and why the approach was chosen. This Skill automates that by reviewing all files modified in the conversation and writing convention-matching comments.

How to add TSDoc comments to TypeScript functions?▼

Use multi-line TSDoc blocks starting with /** and ending with */ placed above the function or method signature. This Skill appends rationale to existing TSDoc blocks rather than duplicating them with separate line comments.

Does this code annotation modify or refactor existing code?▼

No, it only adds comments and never rewrites or refactors code. Unchanged code is left untouched, and no comments are added to sections that were not modified in the conversation.

What kinds of comments should be avoided when documenting code?▼

Avoid trivial comments that restate the code, ticket or PR number references, and single-line TSDoc on signatures. Comments should explain root causes, safety properties, and user-visible symptoms instead.

When should I run code annotation in my workflow?▼

Run it after making code changes but before committing, so the reasoning is captured while context is fresh. It works best when the changes address a specific bug or behavior with a clear root cause.

Related Skills

Explore More Software Engineering Skills→
mattbobambrosemattbobambrose
1

fix-bugs

Fix numbered bugs from bugs-summary.md and add verifying tests.

Community
Advanced
vstorm-covstorm-co
1.0k

git-workflow

Manage git commits, branches, pull requests, and conflict resolution.

Official
Intermediate
TheCardGoatTheCardGoat
14

source-command-review-pr-comments

Resolve unanswered GitHub pull request review comments and run tests.

Official
Intermediate
insightriotinsightriot
1

documentation-and-adrs

Write ADRs, API docs, READMEs, and changelogs that capture architectural decision rationale.

Official
Intermediate