Continuous Learning V2
Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination. Use when capturing lessons from a session, managing instincts, or promoting them into skills, commands, or agents.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Continuous Learning V2 when an AI agent needs a reusable SKILL.md workflow for this job: Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination. Use when capturing lessons from a session, managing instincts, or promoting them into skills, commands, or agents.
When not to use it
Skip Continuous Learning V2 when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/continuous-learning-v2 # Save SKILL.md to ~/.claude/skills/continuous-learning-v2/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/continuous-learning-v2/SKILL.md. For a shared project, commit the folder at .claude/skills/continuous-learning-v2/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Continuous Learning V2 skill for this task: Use Continuous Learning V2 when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Continuous Learning v2.1 - Instinct -Based Architecture
An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring.
**v2.1** adds **project-scoped instincts** — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns (like "always validate input") are shared globally.
## When to Activate
- Setting up automatic learning from Claude Code sessions - Configuring instinct-based behavior extraction via hooks - Tuning confidence thresholds for learned behaviors - Reviewing, exporting, or importing instinct libraries - Evolving instincts into full skills, commands, or agents - Managing project-scoped vs global instincts - Promoting instincts from project to global scope
## What's New in v2.1
| Feature | v2.0 | v2.1 | |---------|------|------| | Storage | Global (`~/.claude/homunculus/`) | Project-scoped (`${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/`) | | Scope | All instincts apply everywhere | Project-scoped + global | | Detection | None | git remote URL / repo path | | Promotion | N/A | Project → global when seen in 2+ projects | | Commands | 4 (status/evolve/export/import) | 6 (+promote/projects) | | Cross-project | Contamination risk | Isolated by default |
## What's New in v2 (vs v1)
| Feature | v1 | v2 | |---------|----|----| | Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) | | Analysis | Main context | Background agent (Haiku) | | Granularity | Full skills | Atomic "instincts" | | Confidence | None | 0.3-0.9 weighted | | Evolution | Direct to skill | Instincts -> cluster -> skill/command/agent | | Sharing | None | Export/import instincts |
## The Instinct Model
An instinct is a small learned behavior:
```yaml --- id: prefer-functional-style trigger: "when writing new functions" confidence: 0.7 domain: "code-style" source: "session-observation" scope: project project_id: "a1b2c3d4e5f6" project_name: "my-react-app" ---
# Prefer Functional Style
## Action Use functional patterns over classes when appropriate.
## Evidence - Observed 5 instances of functional pattern preference - User corrected class-based approach to functional on 2025-01-15 ```
**Properties:** - **Atomic** -- one trigger, one action - **Confidence-weighted** -- 0.3 = tentative, 0.9 = near certain - **Domain-tagged** -- code-style, testing, git, debugging, workflow, etc. - **Evidence-backed** -- tracks what observations created it - **Scope-aware** -- `project` (default) or `global`
## How It Works
``` Session Activity (in a git repo) | | Hooks capture prompts + tool use (100% reliable) | + detect project context (git remote / repo path) v +---------------------------------------------+ | projects/<project-hash>/observations.jsonl | | (prompts, tool calls, outcomes, project) | +---------------------------------------------+ | | Observer agent reads (background, Haiku) v +---------------------------------------------+ | PATTERN DETECTION | | * User corrections -> instinct | | * Error resolutions -> instinct | | * Repeated workflows -> instinct | | * Scope decision: project or global? | +---------------------------------------------+ | | Creates/updates v +---------------------------------------------+ | projects/<project-hash>/instincts/personal/ | | * prefer-functional.yaml (0.7) [project] | | * use-react-hooks.yaml (0.9) [project] | +---------------------------------------------+ | instincts/personal/ (GLOBAL) | | * always-validate-input.yaml (0.85) [global]| | * grep-before-edit.yaml (0.6) [global] | +---------------------------------------------+ | | /evolve clusters + /promote v +---------------------------------------------+ | projects/<hash>/evolved/ (project-scoped) | | evolved/ (global) | | * commands/new-feature.md | | * skills/testing-workflow.md | | * agents/refactor-specialist.md | +---------------------------------------------+ ```
## Project Detection
The system automatically detects your current project:
1. **`CLAUDE_PROJECT_DIR` env var** (highest priority) -- honored as an explicit override even when the directory is not a git repo (hashed by its absolute path) 2. **`git remote get-url origin`** -- hashed to create a portable project ID (same repo on different machines gets the same ID) 3. **`git rev-parse --show-toplevel`** -- fallback using repo path (machine-specific) 4. **Global fallback** -- if no project is detected, instincts go to global scope
Each project gets a 12-character hash ID (e.g., `a1b2c3d4e5f6`). A registry file at `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json` maps IDs to human-readable names.
### Data Directory
Continuous-learning-v2 stores observer data outside `~/.claude` so Claude Code's sensitive-path guard does not block background instinct writes:
1. `CLV2_HOMUNCULUS_DIR` when set to an absolute path 2. `$XDG_DATA_HOME/ecc-homunculus` 3. `$HOME/.local/share/ecc-homunculus`
Existing users with data at `~/.claude/homunculus` can migrate once:
```bash bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh ```
## Quick Start
### 1. Enable Observation Hooks
**If installed as a plugin** (recommended):
No extra `settings.json` hook block is required. Claude Code v2.1+ auto-loads the plugin `hooks/hooks.json`, and `observe.sh` is already registered there.
If you previously copied `observe.sh` into `~/.claude/settings.json`, remove that duplicate `PreToolUse` / `PostToolUse` block. Duplicating the plugin hook causes double execution and `${CLAUDE_PLUGIN_ROOT}` resolution errors because that variable is only available inside plugin-managed `hooks/hooks.json` entries.
**If installed manually** to `~/.claude/skills`, add this to your `~/.claude/settings.json`:
```json { "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" }] }] } } ```
### 2. Initialize Directory Structure
The system creates directories automatically on first use, but you can also create them manually:
```bash # Global directories mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
# Project directories are auto-created when the hook first runs in a git repo ```
### 3. Use the Instinct Commands
```bash /instinct-status # Show learned instincts (project + global) /evolve # Cluster related instincts into skills/commands /instinct-export # Export instincts to file /instinct-import # Import instincts from others /promote # Promote project instincts to global scope /projects # List all known projects and their instinct counts ```
## Commands
| Command | Description | |---------|-------------| | `/instinct-status` | Show all instincts (project-scoped + global) with confidence | | `/evolve` | Cluster related instincts into skills/commands, suggest promotions | | `/instinct-export` | Export instincts (filterable by scope/domain) | | `/instinct-import <file>` | Import instincts with scope control | | `/promote [id]` | Promote project instincts to global scope | | `/projects` | List all known projects and their instinct counts |
## Configuration
Edit `config.json` to control the background observer:
```json { "version": "2.1", "observer": { "enabled": false, "run_interval_minutes": 5, "min_observations_to_analyze": 20 } } ```
| Key | Default | Description | |-----|---------|-------------| | `observer.enabled` | `false` | Enable the background observer agent | | `observer.run_interval_minutes` | `5` | How often the observer analyzes observations | | `observer.min_observations_to_analyze` | `20` | Minimum observations before analysis runs |
Other behavior (observation capture, instinct thresholds, project scoping, promotion criteria) is configured via code defaults in `instinct-cli.py` and `observe.sh`.
### Observer platform support
The background observer requires WSL2, Linux, or macOS. On native Windows (Git Bash / MSYS2) it starts and reports success, but the process is killed when the spawning hook exits and its Job Object closes, so no analysis ever runs — setting `observer.enabled: true` there is effectively a no-op (see issue #2489).
`observe.sh` detects this on the following hook invocation and writes an explanatory warning to `observer-start.log` once the observer has failed to survive several times in a row.
| Env var | Default | Description | |---------|---------|-------------| | `ECC_OBSERVER_NOSURVIVE_WARN_AFTER` | `3` | Consecutive non-survivals before the warning is logged |
## File Structure
``` ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/ +-- identity.json # Your profile, technical level +-- projects.json # Registry: project hash -> name/path/remote +-- observations.jsonl # Global observations (fallback) +-- instincts/ | +-- personal/ # Global auto-learned instincts | +-- inherited/ # Global imported instincts +-- evolved/ | +-- agents/ # Global generated agents | +-- skills/ # Global generated skills | +-- commands/ # Global generated commands +-- projects/ +-- a1b2c3d4e5f6/ # Project hash (from git remote URL) | +-- project.json # Per-project metadata mirror (id/name/root/remote) | +-- observations.jsonl | +-- observations.archive/ | +-- instincts/ | | +-- personal/ # Project-specific auto-learned | | +-- inherited/ # Project-specific imported | +-- evolved/ | +-- skills/ | +-- commands/ | +-- agents/ +-- f6e5d4c3b2a1/ # Another project +-- ... ```
## Scope Decision Guide
| Pattern Type | Scope | Examples | |-------------|-------|---------| | Language/framework conventions | **project** | "Use React hooks", "Follow Django REST patterns" | | File structure preferences | **project** | "Tests in `__tests__`/", "Components in src/components/" | | Code style | **project** | "Use functional style", "Prefer dataclasses" | | Error handling strategies | **project** | "Use Result type for errors" | | Security practices | **global** | "Validate user input", "Sanitize SQL" | | General best practices | **global** | "Write tests first", "Always handle errors" | | Tool workflow preferences | **global** | "Grep before Edit", "Read before Write" | | Git practices | **global** | "Conventional commits", "Small focused commits" |
## Instinct Promotion (Project -> Global)
When the same instinct appears in multiple projects with high confidence, it's a candidate for promotion to global scope.
**Auto-promotion criteria:** - Same instinct ID in 2+ projects - Average confidence >= 0.8
**How to promote:**
```bash # Promote a specific instinct python3 instinct-cli.py promote prefer-explicit-errors
# Auto-promote all qualifying instincts python3 instinct-cli.py promote
# Preview without changes python3 instinct-cli.py promote --dry-run ```
The `/evolve` command also suggests promotion candidates.
## Confidence Scoring
Confidence evolves over time:
| Score | Meaning | Behavior | |-------|---------|----------| | 0.3 | Tentative | Suggested but not enforced | | 0.5 | Moderate | Applied when relevant | | 0.7 | Strong | Auto-approved for application | | 0.9 | Near-certain | Core behavior |
**Confidence increases** when: - Pattern is repeatedly observed - User doesn't correct the suggested behavior - Similar instincts from other sources agree
**Confidence decreases** when: - User explicitly corrects the behavior - Pattern isn't observed for extended periods - Contradicting evidence appears
## Why Hooks vs Skills for Observation?
> "v1 relied on skills to observe. Skills are probabilistic -- they fire ~50-80% of the time based on Claude's judgment."
Hooks fire **100% of the time**, deterministically. This means: - Every tool call is observed - No patterns are missed - Learning is comprehensive
## Backward Compatibility
v2.1 is fully compatible with v2.0 and v1: - Existing global instincts can be migrated from `~/.claude/homunculus/instincts/` with `scripts/migrate-homunculus.sh` - Existing `~/.claude/skills/learned/` skills from v1 still work - Stop hook still runs (but now also feeds into v2) - Gradual migration: run both in parallel
## Privacy
- Observations stay **local** on your machine - Project-scoped instincts are isolated per project - Only **instincts** (patterns) can be exported — not raw observations - No actual code or conversation content is shared - You control what gets exported and promoted
## Related
- [ECC-Tools GitHub App](https://github.com/apps/ecc-tools) - Generate instincts from repo history - Homunculus - Community project that inspired the v2 instinct-based architecture (atomic observations, confidence scoring, instinct evolution pipeline) - [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Continuous learning section
---
*Instinct-based learning: teaching Claude your patterns, one project at a time.*
Intended uses
- Use Continuous Learning V2 when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.