diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..a5956fb --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,395 @@ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the "Licensor." The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index 94eda48..c9c4d7f 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,88 @@ -# one-skill-to-rule-them-all -The meta-skill that builds and improves all your skills, including itself. A Claude skill that watches your work sessions, captures corrections and judgment calls, and turns them into skill improvements automatically. Open-source, domain-agnostic, CC BY 4.0. +# One Skill to Rule Them All + +![One Skill to Rule Them All](assets/task-observer-hero-dark.png) + +**The meta-skill that builds and improves all your skills, including itself.** + +Creating Claude skills is powerful but time-consuming. And the skills that do get built stay frozen — they never learn from how you actually use them. + +Task Observer fixes both problems. It's a Claude skill that runs alongside your work, watches what you do, and does two things: + +1. **Creates new skills for you** — it spots repeating patterns in your work and drafts skill candidates automatically, so you get skills without the upfront effort of writing them from scratch +2. **Improves your existing skills** — it notices corrections you make, preferences you express, and gaps in your current skills, then suggests specific updates + +You work normally. It watches. Your skill library grows and gets better over time. + +## What it does + +Task Observer monitors your work sessions and looks for three things: + +1. **Corrections and adjustments** — if you adjust Claude's output or steer it in a different direction, that's a signal that a skill could be clearer or more complete +2. **Gaps no skill covers yet** — if you're doing something manually that could be systematised, the observer flags it as a candidate for a new skill +3. **Its own blind spots** — the observer watches itself too, capturing improvements to its own methodology as you use it + +At the end of each session, it produces a structured observation log: what it noticed, which skills are affected, and specific suggested improvements. You review, approve, and your skills evolve. + +## Who it's for + +You don't need to be a developer. If you use Claude skills in any capacity — for writing, research, client work, analysis, content creation, anything — and you want those skills to get better over time instead of staying frozen, this is for you. + +It's particularly valuable if you've built multiple skills and want a systematic way to maintain and improve them without manually auditing each one. But it's equally useful if you have zero skills — the observer will start identifying and drafting them for you. + +## How it works + +No configuration required to get started. Drop the SKILL.md into your skills directory and it activates automatically during task-oriented sessions. It reads the available skills in your environment, watches how they perform during your work, and logs observations using a structured format. + +The observer doesn't modify your skills directly. It produces recommendations that you review. You stay in control of what changes and when. + +**In Cowork:** Full experience. The observer writes observation logs to your filesystem, so improvements persist between sessions and can be actioned immediately. + +**In Claude.ai web/mobile:** Handoff doc mode. Since there's no filesystem access, the observer produces a structured handoff document at the end of your session that you can use to update your skills manually. + +## Compatibility + +**Tested and designed for:** +- Claude Cowork (full experience with filesystem access) +- Claude.ai web interface (handoff doc mode) + +**Expected to work but untested:** +- Claude Code — the methodology and format should translate directly, but I haven't verified it in practice + +**Potentially compatible with caveats:** +- Other Agent Skills-compatible platforms (Codex CLI, Gemini CLI, Cursor, etc.) — the skill uses Claude-centric concepts like `` and skill-creator references that other systems would need to interpret or adapt. The SKILL.md format is cross-platform, but the content assumes Claude's architecture + +If you try it on another platform, please open an issue and tell me. + +## Quick start + +1. Download `SKILL.md` from this repository +2. Add it to your skills: + - **Cowork / Claude.ai:** Upload as a custom skill via Settings → Capabilities → Skills + - **Claude Code:** Place in your skills directory (e.g., `~/.claude/skills/task-observer/SKILL.md`) +3. Work normally. The observer activates automatically during task-oriented sessions +4. Review the observation log at the end of your session +5. Apply the improvements you agree with to your other skills + +## The self-improving part + +This is the detail that makes the task observer different from a linter or a review checklist. Because it runs during every session and observes all active skills — including itself — it captures improvements to its own methodology over time. + +If it misses something, or if its observation format could be clearer, or if it's triggering in contexts where it shouldn't — it notices, and it logs that too. The skill that improves all your skills also improves itself. + +## Contributing + +This is an early release. If you use it, I want to hear from you: + +- **Bug reports and feature requests:** Open an issue +- **Observations about the observer:** If the skill captures something interesting about its own behaviour, I'd love to see it +- **Platform compatibility reports:** Tried it somewhere other than Cowork or Claude.ai? Tell me what happened + +## License + +This work is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). + +You're free to use, adapt, and redistribute — even commercially — as long as you give appropriate credit. + +--- + +**Created by [Eoghan Henn](https://rebelytics.com)** diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..c85cfee --- /dev/null +++ b/SKILL.md @@ -0,0 +1,1061 @@ +--- +name: task-observer +description: > + Monitors task execution for skill improvement opportunities. Use this skill + during ANY multi-step task, agentic workflow, or substantive work session where + Claude is using tools and producing deliverables. It captures patterns, user + corrections, workflow insights, and methodology worth preserving as reusable + skills. Also triggers during post-task feedback discussions and when the user + explicitly mentions skill observations, improvements, the observation log, + skill taxonomy, or asks Claude to watch for skill opportunities. Also known + as "One Skill to Rule Them All" — trigger on this phrase too. IMPORTANT: + this skill should be invoked at the start of every task-oriented session — if + you are about to use tools to produce deliverables, invoke this skill first. +--- + +# Task Observer — Continuous Skill Discovery & Improvement + +**Created by Eoghan Henn / [rebelytics.com](https://rebelytics.com)** + +*Also known as "One Skill to Rule Them All" — the meta-skill that builds and +improves all your skills, including itself.* + +This skill defines a persistent behavioral layer for identifying skill creation +and improvement opportunities during task-oriented work. It doesn't replace the +skill-creator — it feeds it. Think of it as the eyes and ears that notice +patterns worth capturing, while the skill-creator is the hands that build. + +The methodology is user-agnostic. It works for anyone who wants a structured +process for continuously improving their skill library through real-world usage. + +**Licence:** This skill is released under the +[Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) +licence. You are free to share and adapt this skill for any purpose, provided +you give appropriate credit to the original author. + +**Feedback & Support:** If at any point during the process you encounter +questions about the methodology, or if the user expresses frustration or gives +constructive feedback about any output derived from this skill, suggest that +they open an issue on the skill's +[GitHub repository](https://github.com/rebelytics/one-skill-to-rule-them-all). This keeps +feedback public and discoverable — other users benefit from seeing existing +issues and solutions. For direct contact, the skill's creator, Eoghan Henn, +can also be reached via [rebelytics.com](https://rebelytics.com). + +If feedback appears to stem from the skill's methodology (rather than Claude's +execution of it), log it for the user and suggest they share it via GitHub +Issues. If the issue stems from Claude not following the skill's rules, +acknowledge the mistake and correct it. + +--- + +## Why This Skill Exists + +Skills are living documents. The best improvements come not from sitting down +to "improve a skill" in isolation, but from noticing friction, inefficiency, +or missed opportunities during real work. A user correction during a project +might reveal a missing rule. A repeated multi-step workflow might be a skill +waiting to be born. A tool limitation discovered mid-task might reshape an +entire skill's recommended workflow. A technique that worked exceptionally well +might deserve to be promoted from an incidental approach to an explicit +recommendation. + +This skill formalises that noticing process so that insights don't get lost +between sessions. Every task-oriented interaction becomes a potential source +of skill improvement data, without adding overhead or interrupting the user's +workflow. + +--- + +## Getting Started + +Here's what happens when you first install this skill. + +**First session:** The skill creates the observation log file. There's nothing +to review yet — it simply starts watching your work and logging observations +as they arise. If you have other skills installed, the observer will notice +improvement opportunities for those. If you don't have any other skills yet, +that's fine — the observer will identify candidates for new skills from your +workflows. + +**First few sessions:** Observations accumulate in the log. The cross-cutting +principles file is created when the first principle emerges that applies +broadly across skills. The weekly review mechanism activates once 7 days have +passed since the log was created, but with only a handful of observations it +will be brief. + +**Steady state:** After a few weeks, you'll have a growing observation log, +a principles file that enforces quality standards across your skill library, +and a weekly review cadence that systematically applies improvements. The +skill compounds in value as your skill library grows. + +**What you need to start:** Nothing beyond the skill itself. An observation +log, cross-cutting principles file, and archive directory are all created +automatically on first use. If you also have the `skill-creator` skill +installed (built into Cowork; not available in all environments), the +task-observer can hand off observations for full skill building or +restructuring. Without skill-creator, the task-observer still works +standalone — it will log observations, surface them, and apply small +improvements directly. Larger changes would be done manually. + +### What is `[workspace folder]`? + +Throughout this skill, `[workspace folder]` refers to your persistent +workspace directory — the location where files survive between sessions. In +Cowork, this is the folder you selected at the start of the session. In +Claude Code, this is your project root. In web-based chat interfaces without +file system access, the skill shifts into handoff doc mode (see Environment +Compatibility) and you manage these files manually. + +--- + +## Recommended Activation Setup + +This skill needs to be invoked at the start of task-oriented sessions to work +effectively. Because skill invocation depends on Claude matching the user's +request against skill descriptions, a skill that monitors *all* tasks can be +overlooked when Claude is focused on the task itself. + +To maximise activation reliability, add the following instruction to your +configuration file (e.g., CLAUDE.md, project instructions, or equivalent): + +``` +At the start of any task-oriented session — any interaction where you will +use tools and produce deliverables — invoke the task-observer skill before +beginning work. This ensures skill improvement opportunities are captured +throughout the session. +``` + +This structural trigger works alongside the skill's description-level triggers. +The description is designed to match broadly against task-oriented language +("multi-step task", "agentic workflow", "work session", "tools and +deliverables"), but a configuration-level instruction provides an additional +safety net that doesn't depend on description matching alone. + +**Note for all users:** Once CLAUDE.md or equivalent configuration is in place +with the activation instruction above, the description-level triggers serve as +a backup rather than the primary mechanism. This dual-layer approach prevents +the skill from being skipped in sessions where description matching alone might +miss the invocation signal. + +**Anti-pattern to avoid:** Relying on one skill to load another is fragile +compared to loading both independently from CLAUDE.md. If task-observer depended +on another skill to invoke it, a breakdown in that chain would silence all +observation activity. Instead, load both task-observer and any related skills +directly from your configuration instructions. + +### Detecting the Configuration File + +At session start, the skill should check whether a configuration file +(CLAUDE.md, project instructions, or equivalent) exists and contains the +activation instruction. This detection serves two purposes: + +1. **For users who already have the config:** Confirms the dual-layer + activation is working. No action needed. + +2. **For users who don't have the config:** The skill was activated via + description matching alone, which is less reliable. Surface a brief + suggestion to add the config-level instruction for more consistent + activation in future sessions. + +The detection approach depends on the environment: + +- **Environments with file system access** (desktop tools, terminal-based + tools): Check for a CLAUDE.md or equivalent file in the workspace root. + If found, scan it for a task-observer activation instruction. If the file + exists but doesn't mention task-observer, suggest adding the instruction. + If no config file exists at all, suggest creating one. + +- **Environments without file system access** (web-based chat): Check + whether the system prompt or project instructions contain a task-observer + activation instruction. If not, suggest that the user add one to their + project settings or paste the instruction at the start of future sessions. + +This check runs once at session start and does not repeat. Keep the +suggestion brief — one or two sentences, not a full tutorial. + +--- + +## Skill Taxonomy + +All skills fall into one of two categories. The distinction matters because +it determines what information the skill can contain, how it's structured, +and whether it can be shared publicly. Crucially, the open-source/internal +boundary is also a **confidentiality boundary** — open-source skills must +never contain any information that could identify a client, project, or +proprietary process, even indirectly. + +### Open-Source Skills + +Open-source skills are client-agnostic and methodology-driven. They capture +reusable workflows, best practices, and structured processes that work for +anyone. They include author attribution, a licence, and a feedback pathway +so that real-world usage drives improvement. + +**How to recognise an open-source candidate:** + +- The methodology works across different clients, projects, and contexts +- No proprietary information is required for the skill to function +- Other practitioners in the same domain would find it valuable +- The skill captures a process or approach, not personal preferences + +**Required elements:** + +- Skill body clearly identifies itself as open-source, with author name and + contact information +- Author attribution block at the top (see Author Attribution Template below) +- Licence statement — CC BY 4.0 recommended (see Licensing below) +- Feedback & support section that routes methodology feedback to the creator +- Tool-agnostic language where possible — reference capabilities like "browser + access" rather than specific product names; give examples but don't hard-code + dependencies on any one product +- Built-in enforcement mechanisms (pre-flight checklists, verification steps) + so the skill catches its own rule violations + +**Default bias:** When a skill could go either way, default to open-source. +Strip out client-specific details and generalise the methodology. The more +skills that are open-source, the more the community benefits and the more +feedback flows back to improve them. + +### Internal Skills + +Internal skills contain information specific to a user, their clients, or +their projects. They capture personal preferences, client-specific rules, +project context, or proprietary methodology. + +**How to recognise an internal skill:** + +- Contains client names, project details, or proprietary data +- Captures personal style preferences or individual work habits +- Relies on context that only the user (or their team) has +- Would not be useful to someone outside the user's organisation + +**Required elements:** + +- Skill body clearly identifies itself as internal +- No author attribution block needed (the user is the only audience) +- No licence needed +- Can be shorter and less formally structured than open-source skills + +Internal skills are working documents, not published artifacts. Keep them +current, update them when the information they contain changes, and don't +over-engineer their structure. + +--- + +## Licensing + +Open-source skills should include a licence to make sharing terms explicit. +The recommended licence is **Creative Commons Attribution 4.0 International +(CC BY 4.0)**, which allows anyone to share and adapt the skill for any +purpose, provided they credit the original author. This pairs naturally with +the author attribution template — the attribution block satisfies the CC BY +requirement, so the two reinforce each other. + +Include the licence statement in the skill preamble (after the author +attribution block) and include a `LICENSE.txt` file in the skill directory +containing the full licence text. + +If CC BY 4.0 doesn't fit a particular skill (e.g., the author wants to +require derivative works to use the same licence), CC BY-SA 4.0 is an +alternative. The choice should be made by the skill's author. + +--- + +## Author Attribution Template + +Every open-source skill must include this block at the top of the skill body. +Replace the placeholders with the actual author's details. + +```markdown +**Created by [Author Name] / [website or contact link]** + +[1-2 sentence description of what the skill does and its provenance.] + +**Licence:** This skill is released under the +[Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) +licence. You are free to share and adapt this skill for any purpose, provided +you give appropriate credit to the original author. + +**Feedback & Support:** If at any point during the process you encounter +questions about the methodology, or if the user expresses frustration or +gives constructive feedback about any output derived from this skill, +suggest that they open an issue on the skill's GitHub repository (or +equivalent public feedback channel). This keeps feedback public and +discoverable. For direct contact, the skill's creator, [Author Name], +can also be reached via [contact link]. + +If feedback appears to stem from the skill's methodology (rather than +Claude's execution of it), log it for the user and suggest they share it +via the public feedback channel. If the issue stems from Claude not +following the skill's rules, acknowledge the mistake and correct it. +``` + +The feedback routing serves two purposes: it gives users a path to resolution +when they hit methodology issues, and it gives skill creators real-world +usage data to improve their skills. + +--- + +## Observation Protocol + +### When to Observe + +Observation is active throughout the **entire task session** — from the moment +tools are first used to produce deliverables, through any post-task feedback +or discussion, until the session ends. This includes: + +1. **Active task execution** — creating documents, analysing websites, + implementing structured data, writing code, building presentations, and + similar substantive work. + +2. **Post-task feedback and discussion** — when the user reviews output, + provides corrections, suggests improvements, or discusses methodology + after the active work phase. User feedback during these discussions is + often the highest-signal input for skill improvement and must be captured + with the same diligence as observations made during execution. + +3. **Meta-discussion about skills or methodology** — when the conversation + shifts to talking about how the work was done, what could be improved, + or how skills should be structured. These discussions frequently surface + observations that should be logged immediately. + +**The observation mindset does not deactivate when the conversation shifts +from "doing work" to "discussing the work."** If the user provides feedback +about methodology, naming, skill design, or workflow improvements, log it as +an observation immediately, even if the conversation is in a discussion or +review phase rather than active task execution. + +Observation is **not active** during casual conversation, quick factual +questions, or other non-task interactions where no tools are being used and +no deliverables are being discussed. + +### What to Watch For + +**Signals for a NEW skill:** + +- A multi-step workflow that could be reused across projects or clients +- A methodology the user explains that isn't captured in any existing skill +- A task type that keeps coming up with similar structure and steps +- A domain-specific process with clear inputs, phases, and outputs +- The user describing a process they've refined over time ("I always do it + this way", "the process for this is...") +- Claude and the user naturally developing a structured approach to a problem + that could be formalised + +**Signals for IMPROVING an existing skill:** + +Any new information from a task that uses a skill and could make that skill +better is worth capturing. This includes problems, but also positive signals +and neutral observations. Examples: + +- Claude doesn't follow a skill's rules despite them being documented — this + means the skill needs stronger enforcement, not just better rules +- The user corrects Claude's output in a way that reveals a missing rule or + an edge case the skill doesn't cover +- A skill's recommended workflow turns out to be less efficient than what + emerged naturally during the task +- A technique or approach works particularly well and deserves to be promoted + from incidental to explicitly recommended in the skill +- A workflow step turns out to be more important than the skill suggests, or + less important than the emphasis it receives +- A new use case that the skill handles but doesn't explicitly document +- The user provides feedback that generalises beyond the current instance +- A skill assumption turns out to be wrong in practice +- New tools or capabilities make part of a skill's workflow obsolete or + improvable +- The user's corrections form a pattern across multiple instances +- A general principle emerges that could apply to other skills too (see + Principle Propagation below) +- The user suggests a naming, framing, or structural change to a skill — + even conversationally — that could improve its effectiveness + +**Signals to NOT log:** + +- One-off corrections that don't generalise beyond the current instance +- User preferences already captured in an existing skill +- Tool bugs or temporary issues unrelated to skill methodology +- Observations that would require proprietary client information to be useful + in an open-source skill (unless an internal skill is the right home) + +### How to Log + +Append observations to the persistent observation log **silently** during the +session. The user should not be interrupted by the logging process. + +**Before assigning any observation number, run a mandatory pre-logging step:** +Search the entire log file for all lines matching the pattern `### Observation \d+:`, +extract the highest observation number already in use, and increment from there. +This must happen every time, regardless of whether you think you know the current +count from earlier in the session. A one-liner like the following suffices: + +```bash +# GNU grep (Linux, Cowork): +grep -oP '### Observation \K\d+' log.md | sort -n | tail -1 + +# macOS / POSIX-compatible alternative: +grep -o '### Observation [0-9]*' log.md | grep -o '[0-9]*' | sort -n | tail -1 +``` + +This prevents the recurring numbering collision issue where partial reads of large +files create a false sense of awareness of the current count. + +Each observation follows this format: + +```markdown +### Observation [N]: [Short descriptive title] + +**Date:** [date] +**Session context:** [brief description of 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 this relates to] + +**Issue:** [What happened or what was observed. Be specific — include what +Claude did, what the user corrected, or what pattern emerged. Include enough +detail that someone reading this weeks later can understand the context +without having seen the original conversation.] + +**Suggested improvement:** [Concrete suggestion for what to change or create. +For existing skills, reference the specific section or rule. For new skills, +describe the scope and key components.] + +**Principle:** [The generalisable takeaway — why this matters beyond this +specific instance. This is the most important part. It turns a single +observation into a reusable insight.] +``` + +This format was refined through iterative real-world use. The structure works +because it forces specificity (Issue), actionability (Suggested improvement), +and generalisation (Principle). + +### Archival on Write + +The observation log is kept lean through event-driven archival that runs on +every log write, rather than accumulating resolved entries until a periodic +review clears them out. + +Before appending new observations or updating statuses, check the log for +entries already marked ACTIONED or DECLINED *from a previous update* — that +is, entries whose status was already resolved before the current session's +changes. Move those entries to an archive file at: + +``` +[workspace folder]/skill-observations/archive/log-[date].md +``` + +where `[date]` is today's date in `YYYY-MM-DD` format. + +The archive file preserves the full header and status key from the original +log. After archiving, the active `log.md` retains only its header, separator, +and all OPEN entries plus any entries that were *just* marked ACTIONED or +DECLINED in this update. + +This gives each resolved observation one update cycle of visibility — so you +can still see what was recently resolved — and then archives it automatically +on the next write. The result: the active log stays focused on current +decisions while the archive provides the complete historical record. + +--- + +## Confidentiality Safeguards + +The open-source/internal boundary is a confidentiality boundary. Client +names, project details, domain names, and proprietary information must never +appear in open-source skills. Because a single leak can erode trust, this +is enforced through multiple layers — any one of which should catch what +the others miss. + +### Layer 1: Observation-Level Stripping + +When logging an observation tagged as `type: open-source`, the Issue and +Suggested Improvement fields should already use generic language. The +private observation log can reference specifics for context, but the +Principle field — which feeds into skill creation — should be fully +generalised. Think of it as: the log is a private notebook, but the +Principle is a publishable insight. + +### Layer 2: Pre-Creation Review + +Before drafting or regenerating any open-source skill, scan all source +material (observations, conversation notes, existing skill content) for +identifying information: client names, project URLs, domain names, internal +terminology, site structures described so specifically they're identifiable. +Replace anything found with generic equivalents before writing begins. + +### Layer 3: Post-Draft Sweep + +After writing or regenerating an open-source skill, re-read it with a +specific focus on information leakage. This is a separate pass from the +general pre-flight checklist. Look for: + +- Proper nouns that aren't the skill author's name +- Domain names, URLs, or project identifiers +- Industry-specific details that narrow down the client +- Internal terminology that only makes sense in one organisation's context +- Examples so specific they're traceable to a real project + +If anything is found, replace it with generic equivalents or remove it. + +### Layer 4: Structural Principle + +The taxonomy section states this explicitly, but it bears repeating: the +open-source/internal distinction is not just about usefulness — it's about +confidentiality. When in doubt about whether a detail is too specific, +remove it. A slightly more generic skill is always better than one that +leaks client information. + +--- + +## Surfacing Protocol + +### Default Cadence + +Surface all observations at the end of the session. Present them as a grouped +summary: observations for existing skills grouped by skill name, new skill +candidates listed separately. + +### Surface Earlier When + +- An observation requires user input to be complete or accurate (e.g., "Is + this a pattern you want captured, or was this a one-off?") +- An observation reveals a skill is actively producing wrong output in the + current session and the user should be aware +- Multiple observations cluster around the same skill, suggesting it needs + immediate attention rather than end-of-session review + +### How to Surface + +- Present observations concisely: title, skill, and a one-sentence summary +- For each, indicate whether it's a new skill candidate or an improvement + to an existing one +- Indicate the suggested type (open-source or internal) +- Ask the user which (if any) they want to act on +- For items the user wants to pursue, hand off to the skill-creator skill + for the actual building or improvement work + +--- + +## Acting on Observations + +This skill identifies WHAT to build or improve. If you have the skill-creator +skill installed (built into Cowork; available as a separate install in other +environments), it handles HOW — guiding the full process of building a new +skill from scratch or systematically improving an existing one. Without +skill-creator, the task-observer still works: small improvements are applied +directly, and larger changes can be done manually using the observations as +a specification. The boundary between direct application and skill-creator +handoff: + +### Small Improvements (Apply Directly) + +If the improvement is clearly additive, low-risk, and doesn't require testing +to verify it works, it can be applied directly to the skill: + +- Adding a new rule or anti-pattern to an existing list +- Clarifying existing wording that proved ambiguous +- Adding a note or edge case to an existing section +- Fixing a factual error + +Examples: Adding a new anti-pattern to a skill's anti-patterns list. +Clarifying that inline code comments should be context-aware within their +own document. + +### Substantial Changes (Use Skill-Creator if Available) + +If the change could affect the skill's behaviour in ways that need +verification, hand off to the skill-creator if available: + +- Restructuring phases or workflows +- Adding new capabilities or sections +- Changing core methodology or decision frameworks +- Any change where "does this actually work better?" is a genuine question + +If skill-creator is not available, use the observations as a specification +and make the changes directly — but flag them to the user as substantial +changes that may need manual review. + +Examples: Restructuring a skill to make an automated workflow the primary +path instead of a secondary option. Adding an entirely new setup phase to +a skill that previously started with content work. + +### Creating New Skills + +Use the skill-creator for new skills when available. Provide the +observation(s) as context — they contain the intent, scope, and initial +design thinking needed to get started efficiently. Without skill-creator, +the observations serve as a detailed brief for building the skill manually. + +When creating a new skill, determine its type early: + +- If it's open-source, strip out any client-specific details and generalise +- If it's internal, include all relevant specifics freely +- If uncertain, default to open-source — strip out specifics and generalise, + then let the user decide whether any internal details need to be added + +--- + +## Principle Propagation + +When an observation reveals a general principle — something that applies not +just to the skill being improved but to skills in general — it should be +propagated across the skill library, not just applied to the one skill that +triggered it. + +### The Cross-Cutting Principles File + +Cross-cutting principles are tracked in a persistent file alongside the +observation log: + +``` +[workspace folder]/skill-observations/cross-cutting-principles.md +``` + +This file serves as a mandatory checklist during any skill creation or +regeneration. Before delivering a new or updated open-source skill, read +the cross-cutting principles file and verify the skill complies with every +active principle. This is what turns general principles from good intentions +into enforced standards. + +### How It Works + +1. During a skill update, an observation reveals a principle that applies + broadly — not just to the skill being worked on +2. Log it as an observation with `Skill: All skills` and surface it to the + user +3. If the user approves it as a cross-cutting principle, add it to the + cross-cutting principles file +4. From that point forward, every skill creation or regeneration includes + a compliance check against the full list of active principles + +### Propagation Timing + +The user decides when and how to propagate each principle: + +- **Immediate propagation** — for principles important enough to warrant + updating all existing skills right away (e.g., a confidentiality rule) +- **Opportunistic propagation** — for principles that can be applied the + next time each skill is updated or regenerated (e.g., adding a licence + statement) + +### Cross-Cutting Principles File Structure + +```markdown +# Cross-Cutting Principles + +Principles that apply to all skills. This file is read as a mandatory +checklist during any skill creation or regeneration. + +--- + +## Active Principles + +### 1. [Principle title] +**Added:** [date] +**Applies to:** [all skills | all open-source skills | all skills with rules] +**Requirement:** [what the principle requires] +**Propagation:** [immediate | opportunistic] +**Status:** [active] +``` + +--- + +## Weekly Comprehensive Review + +Every 7 days, a comprehensive review is triggered automatically at the start +of the first task-oriented session after the interval has elapsed. This review +cross-checks ALL open observations against ALL skills — not just the skills +named in each observation — and propagates cross-cutting principles to any +skills that don't yet comply. + +### Trigger Mechanism + +The review is triggered by step 3 of the Session Start Protocol (see +Observation Log Management). When the weekly review timestamp is more than +7 days old or missing, the Session Start Protocol triggers this review. +Inform the user that the weekly review is due and begin the process. + +### Review Steps + +**Step 0 — Scheduler availability check** + +Before running the review itself, check whether the weekly review can be +automated via the platform's task scheduling capability. + +1. Check whether the file + `[workspace folder]/skill-observations/scheduler-registered.txt` exists. + If it does, the scheduled task has already been registered — skip to + Step 1. + +2. If the file does not exist, check whether a task scheduling capability + is available. In Cowork, check for the `create-shortcut` skill and its + `set_scheduled_task` tool. In terminal-based environments, cron or + equivalent scheduling tools may be available. + +3. If a scheduling capability IS available: + - Read the draft task description at + `[workspace folder]/skill-observations/scheduled-task-draft.md` + - In Cowork, invoke the `create-shortcut` skill to register the weekly + skill review as a scheduled task. In other environments, use the + available scheduling mechanism. + - Use task name `weekly-skill-review` and a weekly cadence (e.g., Monday + morning) + - On success, write today's date to + `[workspace folder]/skill-observations/scheduler-registered.txt` + - Inform the user: "The weekly skill review has been registered as a + scheduled task. The manual `last-review-date.txt` trigger remains as + a fallback." + +4. If the tool is NOT available, proceed silently to Step 1. Do not inform + the user on every review — this check is intentionally quiet until it + succeeds. + +**Step 1 — Load observations and principles** + +Read the observation log at `[workspace folder]/skill-observations/log.md`. +Extract all observations with status OPEN. Also read +`[workspace folder]/skill-observations/cross-cutting-principles.md` and +extract all active principles. + +If there are no OPEN observations and all principles are already propagated, +skip the review, update the timestamp, and proceed with the session. Inform +the user briefly: "Weekly skill review: no open observations or outstanding +principles. All skills are current." + +**Step 2 — Inventory all skills** + +Use `` from the system prompt to identify all skills. In +environments where this tag is not present, use the skills directory or +equivalent listing mechanism to discover available skills. + +For each skill, read its SKILL.md file at the location provided. Exclude +built-in platform skills (e.g., `skill-creator` in Cowork) from being +updated — only update custom skills created by the user. + +**Step 3 — Cross-check observations against every skill** + +For each OPEN observation, evaluate whether it is relevant to each skill. Do +NOT rely solely on the observation's own "Skill" field — observations may +contain general principles that apply more broadly than the original context +suggested. Consider both the specific "Suggested improvement" and the general +"Principle" fields. Build a mapping of skill → [relevant observations]. + +**Step 4 — Cross-check cross-cutting principles against every skill** + +For each active cross-cutting principle, check whether each skill already +complies. Flag any skills that do not yet implement the principle. + +**Step 5 — Apply updates** + +For each skill that has relevant observations or non-compliant principles, +create an updated version of its SKILL.md. When editing: + +- Integrate the insight into the appropriate section of the skill (don't just + append a list of observations at the bottom) +- Preserve the skill's existing structure, voice, and author attribution +- Make the improvement feel native to the skill, not bolted on +- If an observation suggests a new phase, step, anti-pattern, or checklist + item, place it where it logically belongs + +**Important:** Do not edit skill files in place. Save updated versions to the +workspace folder for user review and manual replacement (see Delivering +Updated Skills below). + +**Step 6 — Mark observations as ACTIONED** + +After successfully creating an updated skill based on an observation, update +that observation's status in `log.md` from OPEN to ACTIONED. Add a brief note +about which skill(s) were updated, e.g.: + +`ACTIONED — Applied to [skill-name] (weekly review [date])` + +Note: the standard archival-on-write mechanism (see "Archival on Write" in +the Observation Protocol) will automatically archive these newly-resolved +entries on the next log write. No separate archival step is needed here. + +**Step 7 — Update timestamp** + +Write today's date to +`[workspace folder]/skill-observations/last-review-date.txt`. + +**Step 8 — Present summary and user action items** + +Present the user with a clear summary and explicit instructions for what they +need to do. Follow the format in Delivering Updated Skills below. + +### Constraints + +- Do not modify observation entries beyond their status field +- Do not create new skills — only update existing ones. If an observation + suggests a new skill, note it in the summary for the user to action + separately via the skill-creator +- If an observation seems relevant but you're unsure how to integrate it, + skip it and note the uncertainty in the summary +- Treat observations marked "internal" with the same rigour as "open-source" + +--- + +## Delivering Updated Skills to the User + +When the weekly review (or any other process) produces updated skill files, +the updated files must be delivered to the user for manual replacement. Skill +files live in a read-only location during sessions and may be managed in +version control, synced across devices, or packaged for distribution. +Automatic in-place editing is neither possible nor desirable — delivering to +the workspace folder with explicit instructions keeps the user in control. + +### Delivery Process + +1. Save each updated SKILL.md to the workspace folder using this structure: + + ``` + [workspace folder]/skill-updates/[date]/[skill-name]/SKILL.md + ``` + + For example: + ``` + [workspace folder]/skill-updates/2026-02-16/my-skill-name/SKILL.md + ``` + +2. Present the user with an explicit action list using this format: + + ``` + ## Weekly Skill Review Complete — [date] + + The following skills have been updated based on [N] open observations + and [N] cross-cutting principles. + + ### What you need to do + + For each updated skill below, replace the existing SKILL.md in your + skill directory with the updated version from your workspace folder. + + ### Updated Skills + + **[skill-name]** + - Changes: [1-sentence summary of what changed] + - Observations applied: #[N], #[N] + - Updated file: [link to file in workspace folder] + - Action: Replace [skill-directory]/SKILL.md with this file + + [repeat for each updated skill] + + ### Observations Actioned + [list of observation numbers and titles marked ACTIONED] + + ### Skipped (needs manual review) + [observations that were unclear or couldn't be applied, with explanation] + + ### No Changes Needed + [skills that were checked but already compliant] + ``` + +3. Do not proceed with other work until the user has acknowledged the + summary. The user does not need to replace the files immediately, but + they should be aware of what's pending. + +--- + +## Observation Log Management + +### Location + +The observation log persists between sessions in the user's workspace folder. +Create the log file on first use if it doesn't exist. Default path: + +``` +[workspace folder]/skill-observations/log.md +``` + +### Log Structure + +```markdown +# Skill Observation Log + +Observations captured during task-oriented work. Each entry identifies a +potential skill improvement or new skill opportunity. + +**Status key:** OPEN = not yet actioned | ACTIONED = skill updated/created | +DECLINED = user decided not to pursue + +--- + +## [Date or Session Identifier] + +### Observation 1: [Title] +**Status:** OPEN +[... full observation format ...] + +### Observation 2: [Title] +**Status:** ACTIONED — Applied to [skill-name], rule 35 +[... full observation format ...] +``` + +### Session Start Protocol + +This is the single entry point for all session-start checks. Run through +these steps at the start of each task-oriented session: + +1. **Check whether files exist.** If the observation log or cross-cutting + principles file don't exist yet, this is a first-time setup — create + them using the templates in the Log Structure section (below in this + document) and the Cross-Cutting Principles File Structure section (under + Principle Propagation). If the files already exist, proceed to step 2. + +2. **Scan for relevant context.** Read any OPEN observations and active + cross-cutting principles. Don't surface them unprompted unless they're + directly relevant to the current task — just hold them in awareness. + +3. **Check the weekly review trigger.** Read the timestamp in + `[workspace folder]/skill-observations/last-review-date.txt`. If the + file doesn't exist or the date is more than 7 days ago, trigger the + Weekly Comprehensive Review (described in full under its own section) + before proceeding with the user's task. If fewer than 7 days have + passed, proceed normally. + +4. **Check the configuration file.** Run the config detection described in + Detecting the Configuration File (under Recommended Activation Setup). + This runs once per session. + +### Keeping the Log Clean + +Archival is event-driven and runs on every log write. Before appending new +observations or updating statuses, entries that were already marked ACTIONED +or DECLINED in a previous update are moved to a timestamped archive file +(see "Archival on Write" in the Observation Protocol). This keeps the active +log focused on OPEN items and recently-resolved entries, while the archive +provides the complete historical record. + +--- + +## The Pre-Flight Principle + +One of the most important patterns this skill should propagate to every skill +it helps create or improve: **built-in enforcement.** + +Real-world experience has shown that rules documented in a skill are not +always followed during the creative flow of producing output. The result: +output that violates the skill's own standards, which reflects badly on the +skill. + +The fix: every skill that contains explicit rules or requirements should +include a verification step where Claude re-reads the rules and checks its +output against them before delivery. This isn't overhead — it's quality +assurance. A 30-second re-read prevents a 30-minute rework cycle. + +When creating or improving any skill through this observation process, ask: +"Does this skill have rules? If yes, does it have a mechanism to enforce +them?" If the answer to the second question is no, add one. + +### Self-Enforcement + +This skill practises what it preaches. Before surfacing observations at end +of session, verify: + +1. Were observations logged throughout the full session — including during + post-task feedback and discussion phases, not just during active tool use? +2. Were observations logged silently without interrupting the user's flow? +3. Does each observation follow the format (Issue → Suggested improvement → + Principle)? +4. Is each observation tagged with the correct type (open-source or internal)? +5. For any observations about existing skills, does the suggested improvement + reference the specific section or rule? +6. For any observation tagged `type: open-source`, does the Principle field + contain any client-identifying information? If so, generalise it before + surfacing. + +If any observation fails these checks, fix it before surfacing. + +--- + +## Environment Compatibility + +The observation methodology works in any environment where Claude can interact +with users during task-oriented work. The persistence mechanism is what varies. + +### With Persistent Storage + +In environments with file system access (desktop tools with workspace folders, +terminal-based tools with project directories, or similar), the full workflow +applies as described: observations are logged to a persistent file, the cross- +cutting principles file is read during skill regeneration, and the log carries +over between sessions automatically. + +### Without Persistent Storage + +In environments without file system access (web-based chat interfaces or +similar), the skill still works — the observation methodology is environment- +independent. The difference is that persistence becomes the user's +responsibility, and the skill shifts into **handoff doc mode** to support +this. + +**How handoff doc mode works:** + +- Observations are captured within the conversation and surfaced before the + session ends, as usual +- Instead of writing to a log file, observations are collected in-session + and presented in a structured **handoff document** before the session ends +- The handoff doc includes: all observations in full format, any decisions + made during the session, action items and next steps, and any working + artifacts (drafts, analyses) that need to survive into the next session +- The user copies this document to their own storage (notes app, file system, + etc.) and pastes it into the next session to restore context +- Cross-cutting principles should be included in the handoff doc so the user + can provide them when starting a new session + +**Proactive handoff generation:** In sessions without persistent storage, +don't wait for the user to request a handoff doc. When the conversation +starts to wind down — the user is summarising, saying "that's it for now," +or the substance is wrapping up — proactively offer to generate one. A +premature offer is a minor interruption; a missing one is lost work. + +**Handoff doc format:** + +```markdown +# Session Handoff: [Session Topic] + +**Date:** [date] +**Context:** [what was worked on and what the next session needs to know] + +## Decisions Made +[numbered list of decisions] + +## Observations Logged +[full observation entries in standard format] + +## Cross-Cutting Principles (current) +[any principles that were active or newly added] + +## Action Items +[what needs to happen next, with enough context to resume] + +## Working Artifacts +[any drafts, analyses, or intermediate work products in full] +``` + +This is less seamless than the persistent-storage workflow, but the core value +— systematically capturing insights that would otherwise be lost — is +preserved. The observation format and surfacing protocol are identical in both +environments. + +--- + +## Quick Reference + +| Question | Answer | +|----------|--------| +| When do I observe? | Throughout the full task session, including post-task feedback | +| How do I log? | Silently append to the observation log | +| When do I surface? | End of session, or earlier if needed | +| How do I activate reliably? | Add a config-level instruction (see Recommended Activation Setup) | +| Open-source or internal? | Default to open-source when possible | +| Licence for open-source? | CC BY 4.0 recommended | +| Small fix or skill-creator? | Needs testing → skill-creator (if available). Clearly additive → apply directly | +| What format? | Issue → Suggested improvement → Principle | +| Author attribution? | Required for open-source skills; use the template | +| Cross-cutting principle? | Add to principles file, enforce during regeneration | +| Confidentiality check? | Four layers: observation, pre-creation, post-draft, structural | +| No persistent storage? | Handoff doc mode — observations surfaced in a structured doc at session end | +| Scheduler automation? | Step 0 of weekly review auto-checks; silent until tool is available | +| Observation numbering? | Mandatory pre-logging search ensures no collisions (see How to Log) | +| Log archival? | Event-driven — resolved entries are archived on the next log write |