Claude Code's Agent Skills gave you a way to teach the model your conventions once and reuse them everywhere. task-observer asks the next question: what if a skill could watch how you actually work and log where every other skill falls short?
What task-observer does: the meta-observer that accumulated 600 SKILL.md observations
task-observer is a single SKILL.md that runs quietly across an active Claude Code session, watching all your other skills and appending structured notes to skill-observations/log.md — without editing any target file until a deliberate review. Each entry is numbered and consistent: date, session context, the skill name (or "New skill candidate"), the issue, a suggested fix with section references, and a generalizable Principle .
The scale claim comes from author Eoghan Henn of Rebelytics, who self-reports logging and applying over 600 refinements across 40 skills in roughly three months — and notes most of those 40 skills began as "new skill candidate" entries the observer itself flagged, not from manual planning . The repo, rebelytics/one-skill-to-rule-them-all, showed roughly 928 stars and 103 forks at retrieval, having crossed 500 stars in mid-May 2026 off an r/ClaudeAI thread .
Mechanically there is nothing exotic here. task-observer reads JSONL session transcripts and appends to Markdown — no extra API calls, no weight changes. It is layered entirely on Anthropic's Agent Skills standard, which launched October 16, 2025 and gained organization-wide management on December 18, 2025 . It watches three signal classes: user corrections that reveal a missing rule, gaps where no existing skill covers the situation, and techniques that worked exceptionally well in that session .
"Self-improvement quality depends entirely on Claude's ability to accurately diagnose why something went wrong," — Eoghan Henn, Rebelytics (source: rebelytics/one-skill-to-rule-them-all).
What to have in place before adding task-observer
Before task-observer can start logging observations, you need Claude Code with Agent Skills support, which Anthropic launched on October 16, 2025 . Skills live as SKILL.md files in a personal directory (~/.claude/skills) and a project-level directory (.claude/skills); Claude auto-discovers both and reads only each file's YAML description field to decide whether to invoke it, loading full instructions on match .
Two more pieces make the loop reliable:
- A CLAUDE.md at your project root. Description-based matching alone is probabilistic and unreliable for a meta-observer that should run on every session, so you add an explicit invocation instruction here .
- Two scaffold paths in your workspace root. Create
skill-observations/log.md(empty; numbered entries accumulate here) andlast-review-date.txt, which controls the 7-day fallback that triggers the weekly review cycle .
Setting up task-observer: reliable activation and the observation log
With activation and scaffold decisions settled, four concrete steps get task-observer running. The mechanism is entirely filesystem-based — it edits SKILL.md text and reads two workspace files — so setup is copy, create, wire, and verify, with no build step and no change to Claude's weights.
- Install the skill. Copy the SKILL.md from rebelytics/one-skill-to-rule-them-all into
~/.claude/skills/task-observer/SKILL.md. It ships under CC BY 4.0, so redistribution is fine with attribution . - Create the two state files. In your workspace root, create an empty
skill-observations/log.mdand alast-review-date.txt. Numbered, structured entries append to the log; the observer reads the date file and, if it shows 7+ days ago, triggers a full weekly review at the next invocation . - Rely on the checkpoint behavior. task-observer flushes observations after every 3rd TodoWrite completion. It pre-reads
log.mdbefore each write and re-reads after, so it can detect and resolve duplicate entry numbers when parallel sessions collide .
Wire activation into CLAUDE.md. Add the invocation instruction below. Re-invocation after compaction is mandatory: a previously loaded SKILL.md copy persists in context through compaction, but the running observation count is lost, so numbering drifts unless you re-invoke .
At session start, invoke the task-observer skill.
After any compaction, re-invoke task-observer to restore
continuous entry numbering.How logged observations become SKILL.md edits depends on which mode you run. Interactive keeps you in the loop; scheduled autonomous mode trades some control for hands-off refinement but deliberately refuses to act unsupervised on high-risk changes.
| Mode | Applies edits how | Drops to report-only for |
|---|---|---|
| Interactive | Requires user approval — blanket or entry-by-entry — before any SKILL.md is changed | N/A (nothing applies without approval) |
| Autonomous (scheduled) | Auto-applies additive, non-escalated edits | New SKILL.md creation, removals, structural changes, conflicting observations, or self-flagged uncertainty |
Confirm setup by running a normal session, then checking that skill-observations/log.md gained numbered entries — a visible sign the observer attached and is watching .
Where task-observer goes quiet: compaction loss and description-match limits
task-observer has four failure modes worth knowing before you trust it. The most common is silent non-activation: Claude decides whether to load a skill by reading only its description, and that match is probabilistic. Without an explicit CLAUDE.md line invoking task-observer at session start, it may simply never attach — the CLAUDE.md instruction is the primary reliability guarantee, not a fallback .
The second is compaction. Once a session compacts, the loaded SKILL.md copy is dropped from context, so observation stops until you re-invoke. Skip the re-invocation and entry numbering in skill-observations/log.md restarts, producing duplicate numbers within the same session — which is why the recommended CLAUDE.md instruction re-invokes after mid-task compaction .
The third is the autonomous-mode escalation list. In scheduled autonomous mode only clean additive edits auto-apply; new SKILL.md creation, removals, restructuring, conflicting observations, or self-flagged uncertainty all downgrade to report-only and wait for human review . Fourth is the context budget: Anthropic recommends keeping each SKILL.md under 500 lines because loaded content stays in the active window, so an observer that has grown through self-editing costs tokens on every invocation .
Then there is the security surface. A July 1, 2026 study of 238 real-world SKILL.md files found over 99% contained at least one "skill smell" , and a June 15, 2026 Dynamic Malicious Skills paper showed natural-language content in a SKILL.md can inject logic into benign skills at runtime, proposing OS-enforced read-only mounts as mitigation . Anthropic's own docs warn that skills can include executable code and command hooks run with your account's full filesystem permissions . Treat any public SKILL.md as executable governance text before loading it.
Beyond task-observer: companion repos once your observation log fills up
Once your log.md starts filling faster than you review it, two lower-risk companions cover the ground task-observer's autonomous mode leaves exposed. TerenceBristol/claude-improve ships an approval-gated /improve slash command that runs a post-session retrospective on demand — manual cadence, no background SKILL.md writes . It is the safer starting point if silent edits feel premature. UniM0cha/claude-self-improving-skills goes further on guarantees: a Stop lifecycle hook delegates to a skill-distiller subagent with backups, validation, provenance stamping, rollback on malformed SKILL.md output, and staleness archival — stronger safety than task-observer's default autonomous path.
Whichever you run, aim it well. Comparable self-improvement loops show a 5–10 run ramp-up before behavior noticeably shifts, and one-off tasks generate observations that compound little . Point the observer at your most-repeated workflows first — planning style, commit conventions, test discipline — where the payoff accrues.
For teams, project-level .claude/skills turns this into shared compounding, but the discipline matters more: review each weekly-review diff before committing any task-observer-edited SKILL.md, so every teammate sees a deliberate, visible change rather than a silent one. The takeaway is simple — keep the loop, but keep every rewrite reviewable.
Frequently asked questions
Does task-observer automatically rewrite my SKILL.md files without me seeing the changes?
No. Observations queue as numbered entries in skill-observations/log.md and are acted on only during a comprehensive weekly review, on explicit user request, or when a skill is actively producing wrong output mid-session, per the task-observer SKILL.md. Interactive mode requires user approval — blanket or selective — before any edit lands. Scheduled autonomous mode auto-applies only additive, non-escalated clarifications and drops to report-only for anything structural: new skill files, removals, restructuring, conflicting observations, or self-flagged uncertainty. Updated files are staged to skill-updates/[date]/[skill-name]/SKILL.md and diffed against the live file, not blindly overwritten.
Why does task-observer sometimes not activate when I start a new session?
Claude decides whether to invoke a skill by matching your session context against each SKILL.md description field, and that match is probabilistic, not guaranteed (source: Claude Code skills docs). Description-based triggering alone is a documented weak point. The fix is to make activation explicit: add a CLAUDE.md instruction such as "At session start, invoke task-observer" as the primary mechanism rather than a fallback (source: rebelytics/one-skill-to-rule-them-all). Re-invoke after any mid-task compaction so the observation log's sequential entry numbering stays continuous.
How many sessions before task-observer noticeably improves my other SKILL.md files?
Expect a ramp-up of roughly 5–10 runs before behavior visibly shifts, in line with comparable learning loops . One-off tasks still accumulate observations but compound little, because the loop only pays off on frequently-run workflows. Point task-observer at your most-repeated patterns — planning style, commit conventions, test discipline — where it gathers enough signal to produce actionable refinements. For context, the maintainer self-reports logging and applying over 600 improvements across 40 skills in about three months of regular use .
Is it safe to drop in a public SKILL.md like task-observer without auditing it first?
No. Treat any SKILL.md as executable governance text, since Claude Code hooks and skill scripts run with your account's full filesystem permissions (source: hooks docs). Security research backs the caution: a May 2026 supply-chain paper found description-only framing drove 77.6% adversarial selection in paired trials , and a June 2026 paper demonstrated runtime injection of malicious logic into benign skills from malicious SKILL.md content . Audit before loading, and prefer repos with a clear license, visible commit history, and an active maintainer.
Can task-observer modify itself?
Yes. It observes all active SKILL.md files, including its own, so the weekly review surfaces self-observations and proposes edits to task-observer's own SKILL.md (source: task-observer SKILL.md). The quality of any self-directed change depends entirely on Claude accurately diagnosing why something went wrong, and it is not always right about its own failures. Keep human review in the loop for self-edits regardless of whether you run interactive or scheduled autonomous mode.
Enjoyed this article? Subscribe to get new stories by email whenever they're published.
