rebelytics/one-skill-to-rule-them-all instruction manual

1. Purpose, operating model, and Claude Code classification

Task Observer instruction manual

Task Observer (“One Skill to Rule Them All”) is a meta-skill for discovering reusable workflows and improving existing skills from evidence gathered during real work. It watches substantive, multi-step sessions for corrections, preferences, recurring processes, workflow gaps, successful techniques, obsolete steps, and weaknesses in its own observation method. It records recommendations; it does **not** directly change skills by default. The user reviews and controls what is applied.

Its main outputs are a structured observation log, proposed skill improvements, candidates for new skills, and cross-cutting principles that can raise the quality floor for multiple skills. It is most valuable when a user has—or expects to build—a sizable skill library, runs parallel sessions, or schedules regular reviews. The README explicitly notes that built-in memory or direct editing may be simpler for a small collection.

**Claude Code classification:** `context_injection`, `orchestration`, and `skill_authoring`; install mode: `claude_extension`; setup effort: low; confidence: high. The evidence is that Claude Code loads the Markdown bundle from a skills directory, while the skill coordinates observation, review, and skill-creation/editing episodes. It is not documented as an MCP server, lifecycle hook, or executable interception layer. Its own text warns that description matching alone cannot guarantee activation, so persistent instructions or a harness-level session-start hook must come from the surrounding environment.

The published Tessl manifest identifies version `2.0.0` and exposes the repository root as one public skill. The repository is public and licensed under CC BY 4.0.

2. Obtain and install the complete bundle

The complete bundle consists of four first-party files: `SKILL.md` and `references/weekly-review.md`, `references/skill-authoring.md`, and `references/environments.md`. Keep the three references inside the `references/` subfolder next to `SKILL.md`. Installing only `SKILL.md` is supported as a degraded mode: the core rules still operate, but the skill should identify missing references when an affected episode occurs.

To obtain the files, use GitHub’s **Code → Download ZIP** interface or clone the repository. No literal clone command is provided in the supplied documentation, so this manual does not invent one.

For Claude Code, place the complete folder at:

.claude/skills/task-observer/
├── SKILL.md
└── references/
    ├── weekly-review.md
    ├── skill-authoring.md
    └── environments.md

The documented alternative is the user-level skills directory, again preserving the same internal structure. The supplied files do not state its literal path, so consult your installed Claude Code environment rather than assuming one.

For Claude web, desktop chat, mobile, and Cowork, put `SKILL.md` and `references/` into one folder, zip that folder, then upload it through **Settings → Capabilities**. In filesystem-enabled Cowork or Claude Code desktop use, observations persist in `[shared workspace]/skill-observations/`, while proposed updates may appear in `[shared workspace]/skill-updates/`. Storage-less chat environments use a structured handoff document instead.

For other skills-compatible systems, preserve the bundle and adapt it to that platform’s expected skill location. Compatibility is not equivalent to verified parity: the content assumes Claude concepts such as `<available_skills>` and skill-creator references.

3. Activate the observer and choose durable storage

Task Observer is intended to load at the beginning of every tool-using, deliverable-producing session. Its activation description covers multi-step work, agentic workflows, substantive tasks, post-task feedback, skill discussions, observation-log requests, taxonomy questions, and the phrase “One Skill to Rule Them All.” It stays active through execution, review, reflection, and methodology discussions. It is inactive for casual conversation and quick factual questions that involve neither tools nor deliverables.

Description-level routing is explicitly described as non-enforceable. The repository recommends pairing it with a `CLAUDE.md` instruction or a harness-level session-start hook. The quick start says to ensure the skill loads in all relevant sessions and reports that the author uses `CLAUDE.md`. The exact instruction text is housed in `references/environments.md`, which was named but not supplied here; therefore this manual cannot reproduce or invent it.

Choose a stable workspace identity. The default log is:

[workspace folder]/skill-observations/log.md

In Cowork, the workspace is the shared folder. For Claude Code, the skill gives a stable project identity such as:

~/.claude/projects/<project-id>/

Do not anchor persistent state inside `.claude/worktrees/`, temporary clones, or other ephemeral checkouts. Before any creation or write, resolve the workspace path; if it is ephemeral, warn the user and re-anchor first.

For setup questions or environments without filesystem access, the agent must load `references/environments.md` before proceeding. In web, desktop/mobile chat, and similar storage-less contexts, use handoff-document mode so observations can be transferred into a later skill-maintenance session.

4. Run the session-start protocol and review check

At session start, create `skill-observations/log.md` and `cross-cutting-principles.md` if absent. Also create `skill-observations/last-review-date.txt` with the literal value `never`. Do not insert a setup date: a date means a review actually ran.

Next, scan OPEN observations and active principles. Keep them in awareness without surfacing them unprompted. Read `last-review-date.txt` as the source of truth. If it is missing, recreate it with `never`; never infer a review date. If it says `never`, or its date is more than seven days old, and OPEN observations exist, an interactive session should offer the review in one line and continue the requested task unless the user opts in. A review must never gate normal work. Scheduled or autonomous runs may launch the review without asking.

The review procedure itself is in `references/weekly-review.md`, which must be loaded when a review begins. Because that file was not included in the supplied evidence, details beyond the trigger, approval policy reference, and stated update-delivery/staging role cannot reliably be documented here.

Once per session, check for a `CLAUDE.md` or equivalent activation instruction. Briefly suggest adding one only if absent. Also record the log’s modification time. A modification within the last few hours may indicate another writer, so re-read the live file immediately before every append.

The README’s quick-start operating rhythm is to ask “Any observations logged?” at session end and schedule recurring review sessions. Its Monday/Wednesday/Friday example is personal, not a requirement; choose a cadence suited to your workload. The seven-day fallback remains the documented stale-backlog check.

5. Identify, classify, and record observations

Log a **new-skill candidate** when work reveals a reusable multi-step workflow, an uncaptured methodology, a recurring structured task, a process with clear inputs/phases/outputs, or a refined “I always do it this way” practice. Improve an **existing skill** when a correction, rule violation, better workflow, successful technique, undocumented use case, wrong assumption, obsolete tool step, repeated pattern, or structural suggestion can generalize. Also seek simplification: unused sections, unvalidated one-off rules, routinely skipped steps, contradictions, speculative complexity, or rules that need structural enforcement rather than stronger wording.

Do not log non-generalizable corrections, already-documented preferences, unrelated tool bugs, or open-source observations that require proprietary details. Classify reusable, client-agnostic methodology as `open-source`; classify user, client, project, or personal specifics as `internal`. Default to open-source only after stripping identifying detail.

Append silently in the same or next turn. Every third TodoWrite completion—approximately the 3rd, 6th, 9th, and so on—requires an actual log write: either observations or a one-line `no observations` acknowledgement. Flush pending observations before presenting a major deliverable, staged skill, deck/PDF render, or completed task batch.

Every entry goes at the file end and begins exactly as follows:

### Observation [N]: [Short descriptive title]

**Status:** OPEN
**Date:** [date]
**Session context:** [what task was being worked on]
**Skill:** [existing skill name, or "New skill candidate: [working name]"]
**Type:** [open-source | internal]
**Phase/Area:** [which part of the skill or workflow]

**Issue:** [specific event]

**Suggested improvement:** [concrete change]

**Principle:** [generalisable takeaway]

If evidence depends on temporary uploads or API output, save it into the workspace and add `**Reference file:**`. Open-source Principle fields must contain no traceable client details.

6. Number entries and protect a shared log

Before every append, read the actual log and derive the highest identifier from `### Observation N:` headers. The repository supplies these alternatives:

# GNU grep:
grep -oP '### Observation \K\d+' log.md | sort -n | tail -1
# macOS / POSIX:
grep -o '### Observation [0-9]*' log.md | grep -o '[0-9]*' | sort -n | tail -1

On GNU grep, calculate and collision-check the proposed number:

PROPOSED=$(( $(grep -oP '### Observation \K\d+' log.md | sort -n | tail -1) + 1 ))
grep -qE "^### Observation ${PROPOSED}:" log.md && {
  echo "COLLISION on #${PROPOSED}"; exit 1; }

If a collision exists, advance beyond all identifiers, re-check, and log the concurrency problem. After appending, verify the new number occurs once. Capture line counts immediately before and after the append so your entry—not another writer’s—is identifiable if renumbering is needed. Confirm any substitution by rereading the affected line.

Never perform greedy or DOTALL edits across multiple entries. For every programmatic mutation: make a backup; isolate one entry or one line; re-read the live log immediately before write-back; merge intervening appends; compare observation-header counts before and after; and verify all entries created this session still exist exactly once. A status-only change must preserve the header count. An archival rewrite must reduce it by exactly the number moved.

When referencing an observation, use the number in its literal header. A `grep -n` prefix is a line number, not an observation ID. Resolve a matched line to its nearest preceding header and reject identifiers outside the known header range.

7. Archive, surface, review, and apply findings

Before each log write, archive already-resolved entries to:

skill-observations/archive/log-[YYYY-MM-DD].md

Only archive entries whose recorded resolution date is before today. Valid resolved forms are `ACTIONED (YYYY-MM-DD) — [what was done]` and `DECLINED (YYYY-MM-DD) — [reason]`. Keep same-day resolutions in the active log until a later day. If a resolved entry lacks a readable date, add today’s date rather than archiving it. Preserve the log header in both active and archive handling, and follow the full backup, fresh-read, merge, bounded-edit, count-invariant, and survival-check procedure.

At session end, summarize existing-skill improvements grouped by skill, then list new-skill candidates separately. Give each a one-sentence description and suggested type. Surface earlier only when user input is needed, a skill is currently generating wrong output, or observations cluster around one skill. The default is **log and defer**—do not repeatedly ask whether each observation should be applied now.

Act only during: a comprehensive review; an explicit request such as “update X skill” or “act on observation #N”; or an in-session correction to a skill producing wrong output. Small additive clarifications, rules, or factual fixes may be applied directly. For restructuring, new capabilities, all new skills, and other substantial work, load `references/skill-authoring.md` first. That reference also governs taxonomy details, attribution, licensing, lean content, confidentiality, cross-cutting principles, and live-file editing/staging.

Before surfacing, verify every entry has `**Status:** OPEN`, includes Issue → Suggested improvement → Principle, has a type, names the affected section where relevant, protects confidentiality, and survived concurrent writes.

8. Compatibility, boundaries, maintenance, and licensing

The README says the full filesystem-backed experience is tested and designed for Claude Cowork, Claude Dispatch, and Claude Code in the desktop app. Claude.ai web and Claude mobile are tested in handoff-document mode. Standalone Claude Code is expected to work but is identified as untested by the maintainer, alongside a report of seamless user experience. Other skills-compatible platforms may need adaptations because the content assumes Claude architecture. User-reported Openclaw and Hermes integrations are not equivalent to first-party testing; a separately linked Codex adaptation is maintained elsewhere and is not part of this repository.

The supplied bundle evidence has important limits. The three mandatory reference files are named but their contents were not provided, so this manual cannot reproduce the comprehensive review procedure, exact activation configuration, full authoring taxonomy, confidentiality layers, staging rules, or cross-cutting-principle template. No executable automation, hook implementation, MCP server, or Claude Code plugin manifest is documented in the supplied first-party files. The observer’s reliability therefore depends on model instruction-following and surrounding activation. Parallel writes and archival rewrites carry explicit data-loss risks despite the documented safeguards.

Contribute bug reports, feature requests, platform reports, use cases, and integration stories through the repository’s issue/PR facilities. The skill text asks the agent to offer drafting a methodology issue, while instruction-following failures should be acknowledged and corrected rather than externalized.

The project uses Creative Commons Attribution 4.0 International. Use, adaptation, redistribution, and commercial use are allowed with appropriate credit. The README specifies linking to `https://github.com/rebelytics/one-skill-to-rule-them-all/` and naming Eoghan Henn / rebelytics.com. The repository also displays an external security-audit badge, but the supplied files include no report contents; do not treat the badge alone as proof of security.