affaan-m/everything-claude-code/continuous-learning-v2

Name: continuous-learning-v2
Author: affaan-m

Claude Code and agent skill by affaan-m/everything-claude-code

Trust tier 1

community

Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install affaan-m/everything-claude-code/continuous-learning-v2

SKILL.md

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:

`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)
`git remote get-url origin` -- hashed to create a portable project ID (same repo on different machines gets the same ID)
`git rev-parse --show-toplevel` -- fallback using repo path (machine-specific)
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:

CLV2_HOMUNCULUS_DIR when set to an absolute path
$XDG_DATA_HOME/ecc-homunculus
$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

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 65 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/continuous-learning-v2/SKILL.md

Popularity

Repository stars: 182,281
Repository forks: 28,085
Repository npm downloads, 7 days: 1,824
7-day trend score: 77

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 19 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/affaan-m/everything-claude-code/continuous-learning-v2/badge)](https://verified-skill.com/skills/affaan-m/everything-claude-code/continuous-learning-v2)

Something wrong with this skill or its page? Tell us.