From context-manager
Use when running /context-manager:annotate or when the user wants to add, edit, remove, or view persistent human notes on a file or folder — notes that survive context regeneration and surface across all other context-manager commands.
How this skill is triggered — by the user, by Claude, or both
Slash command
/context-manager:annotateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Manages persistent human annotations on files and folders, stored in `.claude/context-annotations.json`. Annotations capture institutional knowledge that Claude cannot infer from source — deprecation plans, team ownership, vendor patches, known gotchas. They survive context regeneration and surface in search, brief, audit, wip, and repair.
Manages persistent human annotations on files and folders, stored in .claude/context-annotations.json. Annotations capture institutional knowledge that Claude cannot infer from source — deprecation plans, team ownership, vendor patches, known gotchas. They survive context regeneration and surface in search, brief, audit, wip, and repair.
Both the user and Claude can author annotations. Claude should suggest annotations when it spots something noteworthy (e.g. after an audit surfaces a pattern), but always ask for confirmation before writing.
.claude/context-annotations.json — lives in .claude/, never committed. Create it on first use.
{
"annotations": [
{
"id": "ann-001",
"path": "src/auth/",
"scope": "folder",
"note": "Being deprecated in Q3 — replacement is src/auth-v2/",
"author": "user",
"created_at": "2026-04-30T10:00:00Z",
"updated_at": "2026-04-30T10:00:00Z"
},
{
"id": "ann-002",
"path": "src/auth/session.py",
"scope": "file",
"note": "Vendor fork with a custom patch on line 84 — do not upgrade without consulting the platform team.",
"author": "claude",
"created_at": "2026-04-30T10:00:00Z",
"updated_at": "2026-04-30T10:00:00Z"
}
]
}
scope is "folder" or "file". author is "user" or "claude". IDs are sequential strings (ann-001, ann-002, …).
Handle these user intents naturally — no rigid subcommand syntax required:
"Annotate src/auth/ as deprecated in Q3" "Add a note to src/auth/session.py about the vendor patch"
author: "user" for user-authored, author: "claude" for Claude-suggested (always confirm before writing Claude-authored annotations).src/auth/.""Show all annotations" "/context-manager:annotate" (no argument)
Display all annotations grouped by folder, then file, sorted alphabetically:
Annotations — 3 items
src/auth/ [folder]
Being deprecated in Q3 — replacement is src/auth-v2/
Added by user · 2026-04-30
src/auth/session.py [file]
Vendor fork with a custom patch on line 84 — do not upgrade without consulting the platform team.
Added by Claude · 2026-04-30
src/api/routes/users.ts [file]
Rate limiting not wired — all routes currently unprotected.
Added by Claude · 2026-04-30
If no annotations exist: "No annotations yet. Use /context-manager:annotate to add one."
"What's annotated on src/auth/?"
Show all annotations for that exact path (and, if it's a folder, any annotations on files directly inside it).
"Update the annotation on src/auth/ — it's now deprecated in Q2, not Q3"
Find the annotation by path, update the note and updated_at, preserve author and created_at.
"Remove the annotation on src/auth/session.py"
Find by path, confirm with the user, then delete the entry. Confirm: "Annotation removed."
An annotation is orphaned if its path no longer exists on disk (file deleted or renamed).
repair and audit detect and flag orphaned annotations — they do not auto-delete.src/old-module/ no longer exists on disk. Remove it, or update the path?"annotate skill itself should also flag orphans when listing.All skills that read .folder-context.md should also check .claude/context-annotations.json for matching paths and surface any annotation alongside the context entry. Specific behaviors:
| Skill | How annotations surface |
|---|---|
search | Annotation note text is included in the search scope; matches shown with [annotation] label |
brief | Annotations appear under the relevant folder or file description |
status | Shows total annotation count |
audit | Folder/file annotations shown alongside findings; a "deprecated" annotation may indicate lower priority for code fixes |
wip | Annotations shown alongside WIP entries for the same path |
repair | Orphaned annotations flagged after stale context is repaired |
| Mistake | Fix |
|---|---|
| Writing Claude-authored annotations without confirmation | Always ask before saving a Claude-suggested annotation |
| Creating duplicate annotations for the same path | Check for existing annotation before adding; offer to update |
| Auto-deleting orphaned annotations | Flag them and ask the user — don't delete without instruction |
Storing annotations inside .folder-context.md | Annotations live only in .claude/context-annotations.json |
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub pklawansky/context-manager --plugin context-manager