Annotate

Skill tranhieutt/software_development_department/.claude/skills/annotate

Software Development Department

Install

npx -y skills add tranhieutt/software_development_department --skill annotate

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Records unexpected API behaviors, undocumented caveats, version bugs, or non-obvious workarounds into .claude/memory/annotations.md. Use immediately when an undocumented behavior or surprising caveat is discovered during development.

SKILL.md

3.7 KB, as published. Nobody here has run it

/annotate — Persist a Learned Lesson

You are adding a persistent annotation to the project's learned knowledge base. Annotations survive across sessions and auto-load when working with relevant services.

Arguments: $ARGUMENTS — format: <service> <description of gotcha/caveat>

Phase 1 — Parse the Annotation

Extract from $ARGUMENTS:

Service/Library: The specific service, library, or area (e.g., stripe, next.js, postgresql)
Annotation text: The gotcha, caveat, or learned lesson

If $ARGUMENTS is empty or unclear, ask:

"What service/library does this apply to, and what did you discover?"

Phase 2 — Format the Entry

Format the annotation as:

- [YYYY-MM-DD] <clear, specific description of the issue> — <workaround if applicable>

Good example:

- [2026-04-07] Stripe webhook signature verification requires raw body buffer, not parsed JSON. 
  Pass rawBody to stripe.webhooks.constructEvent() instead of req.body

Bad example:

- Stripe webhooks broken  ← too vague, no date, no solution

Apply this quality check before writing:

✅ Specific enough to be actionable without additional research?
✅ Includes the date?
✅ Includes workaround if one exists?
✅ Would a new developer understand this without context?

Phase 3 — Find or Create the Section

Read .claude/memory/annotations.md.

Find the existing section that matches the service (case-insensitive)
If no matching section exists, create one:

## <Service Name>

- [YYYY-MM-DD] <your annotation>

If the section exists and has *(no annotations yet)*, replace that line with the entry.
If the section exists with entries, append the new entry below the last one.

Phase 4 — Write and Confirm

Edit .claude/memory/annotations.md with the new entry.

Then confirm:

✅ Annotation saved to .claude/memory/annotations.md

Service: <service>
Entry: [YYYY-MM-DD] <annotation text>

This will auto-load in future sessions when working with <service>.

Annotation Quality Rules

Never write vague entries like "be careful with X" — always explain WHY
Always include the date (use current date: 2026-04-07)
Always include the workaround if you found one
Prefer short entries (1-2 lines) — link to docs if more context needed
Mark if issue is version-specific: (affects v2.x, fixed in v3.0)
Group related gotchas under the same service header

When Agents Should Use This Automatically

You do NOT need to wait for /annotate to be called explicitly. Proactively add annotations when you:

Spend more than 10 minutes debugging an unexpected API or library behavior
Find that official docs are wrong, incomplete, or misleading
Discover a version incompatibility not mentioned in release notes
Work around a bug with a non-obvious solution
Find that a library's "default" behavior causes problems in this project's setup

Pattern from Context Hub: The value compounds over time. Each annotation means the NEXT session starts smarter — not from zero.