annotate

Name: annotate
Author: tranhieutt

69stars41forks

How to install annotate?

tranhieutt/software_development_department/annotate

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

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# /annotate — Persist a Learned Lesson
2
3	You are adding a persistent annotation to the project's learned knowledge base.
4	Annotations survive across sessions and auto-load when working with relevant services.
5
6	Arguments: `$ARGUMENTS` — format: `<service> <description of gotcha/caveat>`
7
8	---
9
10	## Phase 1 — Parse the Annotation
11
12	Extract from `$ARGUMENTS`:
13	- Service/Library: The specific service, library, or area (e.g., `stripe`, `next.js`, `postgresql`)
14	- Annotation text: The gotcha, caveat, or learned lesson
15
16	If `$ARGUMENTS` is empty or unclear, ask:
17	> "What service/library does this apply to, and what did you discover?"
18
19	---
20
21	## Phase 2 — Format the Entry
22
23	Format the annotation as:
24
25	```
26	- [YYYY-MM-DD] <clear, specific description of the issue> — <workaround if applicable>
27	```
28
29	Good example:
30	```
31	- [2026-04-07] Stripe webhook signature verification requires raw body buffer, not parsed JSON.
32	Pass rawBody to stripe.webhooks.constructEvent() instead of req.body
33	```
34
35	Bad example:
36	```
37	- Stripe webhooks broken ← too vague, no date, no solution
38	```
39
40	Apply this quality check before writing:
41	- ✅ Specific enough to be actionable without additional research?
42	- ✅ Includes the date?
43	- ✅ Includes workaround if one exists?
44	- ✅ Would a new developer understand this without context?
45
46	---
47
48	## Phase 3 — Find or Create the Section
49
50	Read `.claude/memory/annotations.md`.
51
52	1. Find the existing section that matches the service (case-insensitive)
53	2. If no matching section exists, create one:
54
55	```markdown
56	## <Service Name>
57
58	- [YYYY-MM-DD] <your annotation>
59	```
60
61	3. If the section exists and has `(no annotations yet)`, replace that line with the entry.
62	4. If the section exists with entries, append the new entry below the last one.
63
64	---
65
66	## Phase 4 — Write and Confirm
67
68	Edit `.claude/memory/annotations.md` with the new entry.
69
70	Then confirm:
71
72	```
73	✅ Annotation saved to .claude/memory/annotations.md
74
75	Service: <service>
76	Entry: [YYYY-MM-DD] <annotation text>
77
78	This will auto-load in future sessions when working with <service>.
79	```
80
81	---
82
83	## Annotation Quality Rules
84
85	- Never write vague entries like "be careful with X" — always explain WHY
86	- Always include the date (use current date: 2026-04-07)
87	- Always include the workaround if you found one
88	- Prefer short entries (1-2 lines) — link to docs if more context needed
89	- Mark if issue is version-specific: `(affects v2.x, fixed in v3.0)`
90	- Group related gotchas under the same service header
91
92	---
93
94	## When Agents Should Use This Automatically
95
96	You do NOT need to wait for `/annotate` to be called explicitly.
97	Proactively add annotations when you:
98
99	1. Spend more than 10 minutes debugging an unexpected API or library behavior
100	2. Find that official docs are wrong, incomplete, or misleading
101	3. Discover a version incompatibility not mentioned in release notes
102	4. Work around a bug with a non-obvious solution
103	5. Find that a library's "default" behavior causes problems in this project's setup
104
105	> Pattern from Context Hub: The value compounds over time.
106	> Each annotation means the NEXT session starts smarter — not from zero.

People who liked this also viewed

6 picks

Type

annotate

69stars41forks

View on GitHub

How to install annotate?

tranhieutt/software_development_department/annotate

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /annotate — Persist a Learned Lesson
2
3	You are adding a persistent annotation to the project's learned knowledge base.
4	Annotations survive across sessions and auto-load when working with relevant services.
5
6	Arguments: `$ARGUMENTS` — format: `<service> <description of gotcha/caveat>`
7
8	---
9
10	## Phase 1 — Parse the Annotation
11
12	Extract from `$ARGUMENTS`:
13	- Service/Library: The specific service, library, or area (e.g., `stripe`, `next.js`, `postgresql`)
14	- Annotation text: The gotcha, caveat, or learned lesson
15
16	If `$ARGUMENTS` is empty or unclear, ask:
17	> "What service/library does this apply to, and what did you discover?"
18
19	---
20
21	## Phase 2 — Format the Entry
22
23	Format the annotation as:
24
25	```
26	- [YYYY-MM-DD] <clear, specific description of the issue> — <workaround if applicable>
27	```
28
29	Good example:
30	```
31	- [2026-04-07] Stripe webhook signature verification requires raw body buffer, not parsed JSON.
32	Pass rawBody to stripe.webhooks.constructEvent() instead of req.body
33	```
34
35	Bad example:
36	```
37	- Stripe webhooks broken ← too vague, no date, no solution
38	```
39
40	Apply this quality check before writing:
41	- ✅ Specific enough to be actionable without additional research?
42	- ✅ Includes the date?
43	- ✅ Includes workaround if one exists?
44	- ✅ Would a new developer understand this without context?
45
46	---
47
48	## Phase 3 — Find or Create the Section
49
50	Read `.claude/memory/annotations.md`.
51
52	1. Find the existing section that matches the service (case-insensitive)
53	2. If no matching section exists, create one:
54
55	```markdown
56	## <Service Name>
57
58	- [YYYY-MM-DD] <your annotation>
59	```
60
61	3. If the section exists and has `(no annotations yet)`, replace that line with the entry.
62	4. If the section exists with entries, append the new entry below the last one.
63
64	---
65
66	## Phase 4 — Write and Confirm
67
68	Edit `.claude/memory/annotations.md` with the new entry.
69
70	Then confirm:
71
72	```
73	✅ Annotation saved to .claude/memory/annotations.md
74
75	Service: <service>
76	Entry: [YYYY-MM-DD] <annotation text>
77
78	This will auto-load in future sessions when working with <service>.
79	```
80
81	---
82
83	## Annotation Quality Rules
84
85	- Never write vague entries like "be careful with X" — always explain WHY
86	- Always include the date (use current date: 2026-04-07)
87	- Always include the workaround if you found one
88	- Prefer short entries (1-2 lines) — link to docs if more context needed
89	- Mark if issue is version-specific: `(affects v2.x, fixed in v3.0)`
90	- Group related gotchas under the same service header
91
92	---
93
94	## When Agents Should Use This Automatically
95
96	You do NOT need to wait for `/annotate` to be called explicitly.
97	Proactively add annotations when you:
98
99	1. Spend more than 10 minutes debugging an unexpected API or library behavior
100	2. Find that official docs are wrong, incomplete, or misleading
101	3. Discover a version incompatibility not mentioned in release notes
102	4. Work around a bug with a non-obvious solution
103	5. Find that a library's "default" behavior causes problems in this project's setup
104
105	> Pattern from Context Hub: The value compounds over time.
106	> Each annotation means the NEXT session starts smarter — not from zero.

People who liked this also viewed

6 picks

Type