| name | task-observer |
| description | Capture lightweight observations about friction, surprises, or repeated mistakes during a Claude Code session, so they can be reviewed later and turned into skill improvements. Use whenever you notice a pattern worth remembering — confusing instructions in a skill, a workaround you had to invent, a step that should be automated, or behaviour that contradicted a skill's guidance. Always log when you correct yourself or the user corrects you on something a skill should have prevented.
|
Task-Observer Skill
Purpose
This skill captures small, structured observations during a session so that recurring friction
surfaces during a later review and can be turned into skill improvements. It does not modify
skills directly — that happens in the /review-observations workflow, with explicit user approval
on a literal diff.
When to log
- You hit friction caused by an instruction in a skill that was unclear, contradictory, or missing.
- You worked around something a skill should have handled.
- You or the user noticed the same problem you noticed before.
- A skill's guidance contradicted what actually worked.
- You corrected yourself, or the user corrected you, on something a skill could have prevented.
When NOT to log
- The same observation has already been written this session — do not write a near-duplicate.
- The friction was a one-off typo or a trivially recoverable mistake with no structural cause.
- The trigger is normal exploratory back-and-forth (clarifying questions, refinement, scope
changes) rather than a structural skill issue.
Confidentiality
Layer 1 — Hard mechanical block (must run before every write). Before writing the
observation, scan the proposed body. If it contains any of the following literal substrings,
abort the write and ask the user how to proceed: AKIA, ASIA, Bearer (followed by a
space), -----BEGIN (followed by a space), ghp_, ghs_, gho_, xoxb-, xoxp-, xoxo-,
xoxa-. Also abort
if the proposed body contains a line that appears to be quoted from a .env* file referenced
or read in the current session.
Layer 2 — Judgement rule. If you are uncertain whether something belongs in an observation
file — secrets, personal information, internal project details, customer data, internal
codenames — ask the user before writing it. The mechanical block above does not catch
everything; this rule is the catch-all.
Known security limitations. Layer 1's prefix list is non-exhaustive: Google API keys,
JWTs, and high-entropy blobs may pass through undetected. The audit log is not tamper-evident.
Concurrent /review-observations sessions are not locked. Audit observation files before
running /review-observations if this matters to you.
Sync/backup note. ~/.ai-tpk/observations/ is commonly included in Time Machine, Dropbox,
iCloud Drive, or Syncthing backups. Add it to your backup-exclude list if you care about this.
Where to write
Write each observation to ~/.ai-tpk/observations/YYYY-MM-DD-HHMMSS-<pid>-<slug>.md. The
wall-clock timestamp orders observations; the <pid> (the writer's process id) satisfies the
session-isolation invariant by ensuring two parallel sessions cannot collide even within the
same second.
Shell derivation:
- Timestamp:
date +%Y-%m-%d-%H%M%S
- PID:
$$
- Slug: a short kebab-case noun phrase you generate
Slug constraint. The slug must match [a-z0-9-]{1,40} — lowercase ASCII letters, digits,
and hyphens only. No slashes, no .., no spaces, no shell metacharacters. Sanitize before
writing if needed.
Write protocol. Write to ~/.ai-tpk/observations/.tmp-$$-<slug> first, then mv to the
final filename. This guarantees readers never see a half-written file.
Directory bootstrap. If ~/.ai-tpk/observations/ does not yet exist, run
mkdir -p ~/.ai-tpk/observations before writing.
Size cap. Keep the observation body under ~2 KB. If you have more to say, you are choosing
the wrong granularity — split into multiple narrower observations or defer.
Count cap. Before writing, check ls ~/.ai-tpk/observations/*.md 2>/dev/null | wc -l. If
the count exceeds 50, do not write — instead tell the user: "There are over 50 pending
observations; run /review-observations to clear the backlog before logging more."
Observation format
All five fields go in YAML frontmatter. No body sections. Example:
---
timestamp: 2026-04-28T21:31:43Z
trigger: <one-line summary of what prompted the observation>
affected_skill: <skill name, or "none" if not skill-specific>
what_happened: <one short paragraph>
proposed_fix: <one short paragraph, or "unclear — flag for discussion">
---
Five fields total, all in frontmatter. This gives the slash command a single parsing approach.
Anything outside the frontmatter is ignored.
Reviewing observations
When you're ready to turn observations into skill improvements, run /review-observations.
That command groups observations by affected skill, proposes concrete edits as literal unified
diffs, and waits for your approval before changing anything. Pending observations stay until
you run the command — there is no automatic notification, so run it weekly or after long
sessions.
Optional reference
For recurring patterns observed across past reviews, see
~/.claude/references/task-observer-guide.md (advisory only).
