claude-recall 0.18.7 → 0.18.9

package/.claude/settings.json

@@ -1,48 +1 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 /home/ebiarao/repos-wsl/personal-projects/claude-recall/.claude/hooks/search_enforcer.py"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node /home/ebiarao/repos-wsl/personal-projects/claude-recall/dist/cli/claude-recall-cli.js hook run correction-detector"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node /home/ebiarao/repos-wsl/personal-projects/claude-recall/dist/cli/claude-recall-cli.js hook run memory-stop",
-            "timeout": 30
-          }
-        ]
-      }
-    ],
-    "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node /home/ebiarao/repos-wsl/personal-projects/claude-recall/dist/cli/claude-recall-cli.js hook run precompact-preserve",
-            "timeout": 60
-          }
-        ]
-      }
-    ]
-  },
-  "hooksVersion": "6.0.0"
-}
+{"hooks": {}, "hooksVersion": "1.0.0"}

package/.claude/skills/auto-corrections/SKILL.md

@@ -8,7 +8,7 @@ source: claude-recall
 
 # Corrections
 
-Auto-generated from 17 memories. Last updated: 2026-03-21.
+Auto-generated from 20 memories. Last updated: 2026-03-22.
 
 ## Rules
 
@@ -22,8 +22,11 @@ Auto-generated from 17 memories. Last updated: 2026-03-21.
 - CORRECTION: Memory with complex metadata
 - CORRECTION: Memory with complex metadata
 - CORRECTION: Memory with complex metadata
+- CORRECTION: Memory with complex metadata
+- CORRECTION: License copyright should include user's name instead of 'Claude Recall Contributors'
 - CORRECTION: Replace expired access token with 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
 - CORRECTION: use spaces not tabs for indentation
+- CORRECTION: License copyright should list your name instead of 'Claude Recall Contributors'
 - CORRECTION: cited (loaded 5+ times): 19
 - CORRECTION: cited (loaded 5+ times): 19
 - CORRECTION: cited (loaded 5+ times): 19

package/.claude/skills/auto-corrections/manifest.json

@@ -1,12 +1,13 @@
 {
   "topicId": "corrections",
-  "sourceHash": "2c220ace8666e38374662c19a60f76118e125327cc273019414c6e8383e5e120",
-  "memoryCount": 17,
-  "generatedAt": "2026-03-21T15:18:51.279Z",
+  "sourceHash": "be94895a3ad6a5999508be2c149a1a2742178fff9f9adc97b5da6185c9a30398",
+  "memoryCount": 20,
+  "generatedAt": "2026-03-22T15:58:29.733Z",
   "memoryKeys": [
+    "memory_1774195109722_gij039r4m",
+    "memory_1774191618092_vuxyvq3mw",
     "memory_1774106331272_kg5w7ztfj",
     "memory_1774104588311_65kg08e05",
-    "memory_1774020789453_x9xkjhbug",
     "memory_1773140547102_2wmy0cfga",
     "memory_1773065886725_rscm7v2qx",
     "memory_1773063478046_x0ryr9bk4",
@@ -14,8 +15,10 @@
     "memory_1772641994141_ddvzwdkd9",
     "memory_1772641570519_wmnb2b08w",
     "memory_1772641026962_tqm8ow04r",
+    "hook_correction_1774180798682_9b5a2hadq",
     "hook_correction_1772101108419_le80cln1w",
     "hook_correction_1771112125882_99ihypf8x",
+    "hook_correction_1774180805192_4ft4zhfsa",
     "hook_correction_1772638229134_otn9za2il",
     "hook_correction_1772636083381_th3eluwzv",
     "hook_correction_1772635851763_y91ugnjgy",

package/.claude/skills/auto-failure-lessons/SKILL.md

@@ -8,14 +8,12 @@ source: claude-recall
 
 # Failure Lessons
 
-Auto-generated from 26 memories. Last updated: 2026-03-21.
+Auto-generated from 24 memories. Last updated: 2026-03-22.
 
 ## Rules
 
-- Check command syntax, file paths, and prerequisites before running
 - SQLite query syntax error: LIKE clause requires single quotes around string literal, not double quotes
 - Avoid: Command failed: claude-recall outcomes 2>&1 → Instead: Check command syntax, file paths, and prerequisites before running
-- Avoid: Command failed: npx jest tests/unit/outcome-storage.test.ts tests/unit/promotion-engine.test.ts tests/unit/memory... → Instead: Check command syntax, file paths, and prerequisites before running
 - Avoid: Command failed: npm whoami 2>&1 && npm config get registry 2>&1 → Instead: Check command syntax, file paths, and prerequisites before running
 - npm install -g claude-recall@0.15.36 failed with notarget error
 - claude-recall@0.15.36 does not exist on npm registry (ETARGET error)

package/.claude/skills/auto-failure-lessons/manifest.json

@@ -1,13 +1,11 @@
 {
   "topicId": "failure-lessons",
-  "sourceHash": "577fce05d7ff95d6661cf78c93b84ce7a8ff54d22964456ca73c045bac9c0986",
-  "memoryCount": 26,
-  "generatedAt": "2026-03-21T15:18:51.248Z",
+  "sourceHash": "00deb7a6c6d99c26e0d29a6a707b4c303dcb19731d27a8ce41db09fd2ff3eb55",
+  "memoryCount": 24,
+  "generatedAt": "2026-03-22T15:00:18.049Z",
   "memoryKeys": [
-    "promoted_1774019382782_acm9j0h8u",
     "hook_failure_1772637584921_0tj4rrxnt",
     "hook_failure_non-zero-exit_1774020949485_6ubuoswae",
-    "hook_failure_non-zero-exit_1773999564001_82kcdp0ag",
     "hook_failure_non-zero-exit_1773409269877_ful451241",
     "hook_failure_1773410916808_5k1r6zo4u",
     "hook_failure_1773410916789_xtrb8j9nw",

package/.claude/skills/auto-preferences/SKILL.md

@@ -8,10 +8,20 @@ source: claude-recall
 
 # Preferences
 
-Auto-generated from 16 memories. Last updated: 2026-03-21.
+Auto-generated from 22 memories. Last updated: 2026-04-01.
 
 ## Rules
 
+- axios npm package was compromised in a supply chain attack (axios@1.14.1 pulled in malicious plain-crypto-js@4.2.1). Claude Recall is NOT affected — does not use axios. Verified 2026-04-01. If axios is ever added as a dependency, pin the version and audit lockfiles.
+- Test preference 1774195109742-2
+- Test preference 1774195109742-1
+- Test preference 1774195109742-0
+- Test memory content
+- Test preference 1774191618111-2
+- Test preference 1774191618111-1
+- Test preference 1774191618111-0
+- Test memory content
+- a normal preference
 - Session test preference 1774106331339
 - Test preference 1774106331283-2
 - Test preference 1774106331283-1
@@ -23,11 +33,7 @@ Auto-generated from 16 memories. Last updated: 2026-03-21.
 - Test preference 1774104588325-0
 - Test memory content
 - Session test preference 1774020789925
-- Test preference 1774020789520-2
-- Test preference 1774020789520-1
-- Test preference 1774020789520-0
-- Test memory content
-- Session test preference 1773999187736
+- Upgrade all projects whenever a new version is pushed
 
 ---
 *Auto-generated by Claude Recall. Regenerate: `npx claude-recall skills generate`*

package/.claude/skills/auto-preferences/manifest.json

@@ -1,9 +1,19 @@
 {
   "topicId": "preferences",
-  "sourceHash": "7123394f8e4ec18013e3a3c3d5f2a4761f1a0c14c20401f566541901de6f797c",
-  "memoryCount": 16,
-  "generatedAt": "2026-03-21T15:18:51.351Z",
+  "sourceHash": "ad9e64fb51202f15dbb49b534b20617f88a6a83e890c45c794b81578a7c1374d",
+  "memoryCount": 22,
+  "generatedAt": "2026-04-01T08:07:09.378Z",
   "memoryKeys": [
+    "memory_1775030829333_64gdk8kql",
+    "memory_1774195109780_8ffmflge1",
+    "memory_1774195109763_v6olh83ct",
+    "memory_1774195109743_i79j9a9rl",
+    "memory_1774195109624_nnh3wrwca",
+    "memory_1774191618164_wefq7s9x6",
+    "memory_1774191618139_k77izvxnq",
+    "memory_1774191618112_hzi64751y",
+    "memory_1774191617980_pzspevoct",
+    "valid1",
     "memory_1774106331340_cwt88yhle",
     "memory_1774106331311_491hg2a21",
     "memory_1774106331297_0b6bvacd7",
@@ -15,10 +25,6 @@
     "memory_1774104588325_g4o5ksubl",
     "memory_1774104588255_fy0wv845g",
     "memory_1774020789927_g99mrubvu",
-    "memory_1774020789705_xhubujrxv",
-    "memory_1774020789618_m1p55yhtz",
-    "memory_1774020789521_saryqj7kw",
-    "memory_1774020789257_wla5q38wq",
-    "memory_1773999187737_qrdwbas47"
+    "hook_preference_1774106575282_45sk4ep52"
   ]
 }

package/README.md

@@ -1,6 +1,6 @@
 # Claude Recall
 
-### Persistent, local memory for Claude Code — powered by native Claude Skills.
+### Persistent, local memory for Claude Code — learn from every session.
 
 Claude Recall is a **local memory engine + MCP server** that gives Claude Code something it's missing by default:
 **the ability to learn from you over time.**
@@ -15,7 +15,7 @@ Your preferences, project structure, workflows, corrections, and coding style ar
 - **Project-Scoped Knowledge** — each project gets its own memory namespace; switch projects and Claude switches context automatically
 - **Failure Learning** — captures what failed, why, and what to do instead — so Claude doesn't repeat mistakes
 - **Outcome-Aware Learning** — tracks action outcomes (bash results, test cycles, user corrections), synthesizes candidate lessons, and promotes validated patterns into active rules automatically
-- **Skill Crystallization** — when enough memories accumulate, auto-generates `.claude/skills/auto-*/` files that load natively without tool calls
+- **Skill Crystallization** — auto-generates `.claude/skills/auto-*/` files from accumulated memories, using Anthropic's [Agent Skills](https://agentskills.io/) open standard
 - **Local-Only** — SQLite on your machine, no telemetry, no cloud, works fully offline
 
 ---
@@ -113,7 +113,11 @@ claude-recall search "preference"
 
 ## How It Works
 
-Claude Recall runs as an MCP server exposing four tools, backed by a local SQLite database with WAL mode, content-hash deduplication, and automatic compaction. A native Claude Skill (`.claude/skills/memory-management/SKILL.md`) teaches Claude when to load, store, and search memories.
+Claude Recall runs as an MCP server exposing four tools, backed by a local SQLite database with WAL mode, content-hash deduplication, and automatic compaction.
+
+### Built on Agent Skills
+
+Claude Recall uses Anthropic's [Agent Skills](https://agentskills.io/) open standard to teach Claude when and how to use its memory tools. A core skill (`.claude/skills/memory-management/SKILL.md`) guides Claude's memory behavior using progressive disclosure — metadata loads at startup, full instructions load only when needed. When enough memories accumulate around a topic, Claude Recall auto-generates additional skills (`.claude/skills/auto-*/`) that load natively without MCP tool calls. See Anthropic's [blog post](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) for more on the Agent Skills architecture.
 
 | Tool | Purpose |
 | ---- | ------- |

package/dist/hooks/bash-failure-watcher.js

@@ -123,7 +123,7 @@ async function handleBashFailureWatcher(input) {
         }
     }
     catch (err) {
-        (0, shared_1.hookLog)(HOOK_NAME, `Error: ${err}`);
+        (0, shared_1.hookLog)(HOOK_NAME, `Error: ${(0, shared_1.safeErrorMessage)(err)}`);
         // Never throw — hooks must not block Claude
     }
 }
@@ -166,7 +166,7 @@ async function handleFailure(command, exitCode, output, sessionId) {
         });
     }
     catch (err) {
-        (0, shared_1.hookLog)(HOOK_NAME, `Outcome event error: ${err}`);
+        (0, shared_1.hookLog)(HOOK_NAME, `Outcome event error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
     (0, shared_1.hookLog)(HOOK_NAME, `Stored failure: ${truncate(command, 60)} (exit ${exitCode})`);
     // Track pending failure for fix pairing
@@ -215,14 +215,14 @@ async function handleSuccess(command, sessionId) {
                     });
                 }
                 catch (err) {
-                    (0, shared_1.hookLog)(HOOK_NAME, `Positive outcome event error: ${err}`);
+                    (0, shared_1.hookLog)(HOOK_NAME, `Positive outcome event error: ${(0, shared_1.safeErrorMessage)(err)}`);
                 }
                 (0, shared_1.hookLog)(HOOK_NAME, `Paired fix: "${truncate(command, 60)}" → ${pf.memoryKey}`);
                 matched = true;
                 // Don't add to remaining — consumed
             }
             catch (err) {
-                (0, shared_1.hookLog)(HOOK_NAME, `Fix pairing error: ${err}`);
+                (0, shared_1.hookLog)(HOOK_NAME, `Fix pairing error: ${(0, shared_1.safeErrorMessage)(err)}`);
                 remaining.push(pf);
             }
         }

package/dist/hooks/correction-detector.js

@@ -40,7 +40,7 @@ async function handleCorrectionDetector(input) {
         }
     }
     catch (err) {
-        (0, shared_1.hookLog)('correction-detector', `Reask signal detection error: ${err}`);
+        (0, shared_1.hookLog)('correction-detector', `Reask signal detection error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
     const result = await (0, shared_1.classifyContent)(prompt);
     if (!result)

package/dist/hooks/memory-stop-hook.js

@@ -127,7 +127,18 @@ async function handleMemoryStop(input) {
         }
     }
     catch (err) {
-        (0, shared_1.hookLog)('memory-stop', `Promotion error: ${err}`);
+        (0, shared_1.hookLog)('memory-stop', `Promotion error: ${(0, shared_1.safeErrorMessage)(err)}`);
+    }
+    // Prune old outcome data to prevent unbounded table growth
+    try {
+        const pruned = outcomeStorage.pruneOldData();
+        const total = pruned.episodes + pruned.events + pruned.lessons + pruned.stats;
+        if (total > 0) {
+            (0, shared_1.hookLog)('memory-stop', `Pruned: ${pruned.episodes} episodes, ${pruned.events} events, ${pruned.lessons} lessons, ${pruned.stats} orphaned stats`);
+        }
+    }
+    catch (err) {
+        (0, shared_1.hookLog)('memory-stop', `Prune error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
 }
 /**
@@ -331,7 +342,7 @@ function generateCandidateLessons(failures, episodeId, projectId) {
         }
     }
     catch (err) {
-        (0, shared_1.hookLog)('memory-stop', `Candidate lesson generation error: ${err}`);
+        (0, shared_1.hookLog)('memory-stop', `Candidate lesson generation error: ${(0, shared_1.safeErrorMessage)(err)}`);
     }
 }
 function extractTagsFromContext(context) {

package/dist/hooks/shared.js

@@ -41,6 +41,7 @@ exports.jaccardSimilarity = jaccardSimilarity;
 exports.isDuplicate = isDuplicate;
 exports.storeMemory = storeMemory;
 exports.searchExisting = searchExisting;
+exports.safeErrorMessage = safeErrorMessage;
 exports.hookLog = hookLog;
 exports.readTranscriptTail = readTranscriptTail;
 exports.isUserEntry = isUserEntry;
@@ -193,6 +194,16 @@ function searchExisting(query) {
     const memoryService = memory_1.MemoryService.getInstance();
     return memoryService.search(query);
 }
+/**
+ * Extract a safe error message without exposing stack traces or internal paths.
+ */
+function safeErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return 'unknown error';
+}
 /**
  * Append a log line to ~/.claude-recall/hook-logs/{hookName}.log
  */

package/dist/mcp/tools/memory-tools.js

@@ -297,8 +297,23 @@ class MemoryTools {
             if (lowCompliance.length > 0) {
                 sections.push('## Rule Health\nThese rules are loaded frequently but never cited — consider rewording or removing:\n' +
                     lowCompliance.map(r => {
-                        const val = typeof r.value === 'string' ? (JSON.parse(r.value)?.content || r.value) : r.value;
-                        return `- "${String(val).substring(0, 80)}" (loaded ${r.load_count}x, cited 0x)`;
+                        let val;
+                        if (typeof r.value === 'string') {
+                            try {
+                                const parsed = JSON.parse(r.value);
+                                val = typeof parsed === 'string' ? parsed : (parsed?.content || parsed?.value || r.value);
+                            }
+                            catch {
+                                val = r.value;
+                            }
+                        }
+                        else if (typeof r.value === 'object' && r.value !== null) {
+                            val = r.value.content || r.value.value || JSON.stringify(r.value);
+                        }
+                        else {
+                            val = String(r.value ?? '');
+                        }
+                        return `- "${val.substring(0, 80)}" (loaded ${r.load_count}x, cited 0x)`;
                     }).join('\n'));
             }
             const totalRules = rules.preferences.length + rules.corrections.length +

package/dist/services/outcome-storage.js

@@ -193,6 +193,22 @@ class OutcomeStorage {
         times_unhelpful = times_unhelpful + 1
     `).run(key);
     }
+    /**
+     * Prune old data from outcome tables to prevent unbounded growth.
+     * - Episodes older than 90 days
+     * - Outcome events older than 90 days
+     * - Rejected/archived candidate lessons older than 14 days
+     * - Orphaned memory_stats entries (key no longer in memories table)
+     */
+    pruneOldData() {
+        const cutoff90 = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString();
+        const cutoff14 = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000).toISOString();
+        const episodes = this.db.prepare('DELETE FROM episodes WHERE created_at < ?').run(cutoff90).changes;
+        const events = this.db.prepare('DELETE FROM outcome_events WHERE created_at < ?').run(cutoff90).changes;
+        const lessons = this.db.prepare("DELETE FROM candidate_lessons WHERE status IN ('rejected', 'archived') AND updated_at < ?").run(cutoff14).changes;
+        const stats = this.db.prepare('DELETE FROM memory_stats WHERE memory_key NOT IN (SELECT key FROM memories)').run().changes;
+        return { episodes, events, lessons, stats };
+    }
 }
 exports.OutcomeStorage = OutcomeStorage;
 // --- Helpers ---

package/dist/services/promotion-engine.js

@@ -34,13 +34,18 @@ class PromotionEngine {
         let promoted = 0;
         let archived = 0;
         for (const candidate of candidates) {
-            if (this.shouldPromote(candidate)) {
-                this.promote(candidate.id);
-                promoted++;
+            try {
+                if (this.shouldPromote(candidate)) {
+                    this.promote(candidate.id);
+                    promoted++;
+                }
+                else if (this.shouldReject(candidate)) {
+                    outcomeStorage.updateLessonStatus(candidate.id, 'rejected');
+                    archived++;
+                }
             }
-            else if (this.shouldReject(candidate)) {
-                outcomeStorage.updateLessonStatus(candidate.id, 'rejected');
-                archived++;
+            catch (err) {
+                console.error(`PromotionEngine: failed to process candidate ${candidate.id}`);
             }
         }
         // Check for demotion of existing memories
@@ -108,7 +113,13 @@ class PromotionEngine {
         // Not retrieved in 90 days with low strength
         if (stats.last_retrieved_at) {
             const daysSinceRetrieved = (Date.now() - new Date(stats.last_retrieved_at).getTime()) / (1000 * 60 * 60 * 24);
-            const strength = retrieval_1.MemoryRetrieval.computeStrength(memory);
+            let strength = 0;
+            try {
+                strength = retrieval_1.MemoryRetrieval.computeStrength(memory);
+            }
+            catch {
+                strength = 0;
+            }
             if (daysSinceRetrieved > 90 && strength < 0.2) {
                 return true;
             }
@@ -159,8 +170,8 @@ class PromotionEngine {
                 }
             }
         }
-        catch {
-            // Non-critical
+        catch (err) {
+            console.error('PromotionEngine: demotion sweep failed');
         }
         return archived;
     }

package/docs/20260323_equipping-agents-for-the-real-world-with-agent-skills.md

@@ -0,0 +1,569 @@
+---
+description: Discover how Anthropic builds AI agents with practical capabilities through modular skills, enabling them to handle complex real-world tasks more effectively and reliably.
+title: Equipping agents for the real world with Agent Skills \ Anthropic | Claude
+image: https://cdn.prod.website-files.com/6889473510b50328dbb70ae6/68c469d23594abeb9ab6ee48_og-claude-generic.jpg
+---
+
+* Platform
+* Solutions
+* Pricing
+* Resources
+* [Login](https://claude.ai/login)
+* Contact sales  
+[Contact sales](/contact-sales)Contact sales
+* Try Claude  
+[Try Claude](https://claude.ai/)Try Claude
+* Contact sales  
+[Contact sales](/contact-sales)Contact sales
+* Try Claude  
+[Try Claude](https://claude.ai/)Try Claude
+
+* Platform
+* Solutions
+* Pricing
+* Resources
+* [Login](https://claude.ai/login)
+
+* Contact sales  
+[Contact sales](/contact-sales)Contact sales
+* Try Claude  
+[Try Claude](https://claude.ai/)Try Claude
+* Contact sales  
+[Contact sales](/contact-sales)Contact sales
+* Try Claude  
+[Try Claude](https://claude.ai/)Try Claude
+
+Explore here
+
+
+
+# Equipping agents for the real world with Agent Skills
+
+Claude is powerful, but real work requires procedural knowledge and organizational context. Introducing Agent Skills, a new way to build specialized agents using files and folders.
+
+* Category  
+[Claude Code](https://claude.com/blog/category/claude-code)  
+[Agents](https://claude.com/blog/category/agents)
+* Product  
+Claude Code  
+Claude Platform
+* Date  
+October 16, 2025
+* Reading time  
+5  
+min
+* Share  
+[Copy link](#)  
+https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills
+
+_Update: We've published_ [_Agent Skills_](https://agentskills.io/) _as an open standard for cross-platform portability. (December 18, 2025)_
+
+As model capabilities improve, we can now build general-purpose agents that interact with full-fledged computing environments. [Claude Code](https://claude.com/product/claude-code), for example, can accomplish complex tasks across domains using local code execution and filesystems. But as these agents become more powerful, we need more composable, scalable, and portable ways to equip them with domain-specific expertise.
+
+This led us to create [**Agent Skills**](https://www.anthropic.com/news/skills): organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.Skills extend Claude’s capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized agents that fit your needs.
+
+Building a skill for an agent is like putting together an onboarding guide for a new hire. Instead of building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities by capturing and sharing their procedural knowledge. In this article, we explain what Skills are, show how they work, and share best practices for building your own.
+
+
+
+A skill is a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities.
+
+## The anatomy of a skill
+
+To see Skills in action, let’s walk through a real example: one of the skills that powers [Claude’s recently launched document editing abilities](https://www.anthropic.com/news/create-files). Claude already knows a lot about understanding PDFs, but is limited in its ability to manipulate them directly (e.g. to fill out a form). This [PDF skill](https://github.com/anthropics/skills/tree/main/document-skills/pdf) lets us give Claude these new abilities.
+
+At its simplest, a skill is a directory that contains a `SKILL.md file`. This file must start with YAML frontmatter that contains some required metadata: `name` and `description`. At startup, the agent pre-loads the `name` and `description` of every installed skill into its system prompt.
+
+This metadata is the **first level** of _progressive disclosure_: it provides just enough information for Claude to know when each skill should be used without loading all of it into context. The actual body of this file is the **second level** of detail. If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full `SKILL.md` into context.
+
+
+
+A SKILL.md file must begin with YAML Frontmatter that contains a file name and description, which is loaded into its system prompt at startup.
+
+As skills grow in complexity, they may contain too much context to fit into a single `SKILL.md`, or context that’s relevant only in specific scenarios. In these cases, skills can bundle additional files within the skill directory and reference them by name from `SKILL.md`. These additional linked files are the **third level** (and beyond) of detail, which Claude can choose to navigate and discover only as needed.
+
+In the PDF skill shown below, the `SKILL.md` refers to two additional files (`reference.md` and `forms.md`) that the skill author chooses to bundle alongside the core `SKILL.md`. By moving the form-filling instructions to a separate file (`forms.md`), the skill author is able to keep the core of the skill lean, trusting that Claude will read `forms.md` only when filling out a form.
+
+
+
+You can incorporate more context (via additional files) into your skill that can then be triggered by Claude based on the system prompt.
+
+Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed:
+
+
+
+Agents with a filesystem and code execution tools don’t need to read the entirety of a skill into their context window when working on a particular task. This means that the amount of context that can be bundled into a skill is effectively unbounded.
+
+### Skills and the context window
+
+The following diagram shows how the context window changes when a skill is triggered by a user’s message.
+
+
+
+Skills are triggered in the context window via your system prompt.
+
+The sequence of operations shown:
+
+1. To start, the context window has the core system prompt and the metadata for each of the installed skills, along with the user’s initial message;
+2. Claude triggers the PDF skill by invoking a Bash tool to read the contents of `pdf/SKILL.md`;
+3. Claude chooses to read the `forms.md` file bundled with the skill;
+4. Finally, Claude proceeds with the user’s task now that it has loaded relevant instructions from the PDF skill.
+
+### Skills and code execution
+
+Skills can also include code for Claude to execute as tools at its discretion.
+
+Large language models excel at many tasks, but certain operations are better suited for traditional code execution. For example, sorting a list via token generation is far more expensive than simply running a sorting algorithm. Beyond efficiency concerns, many applications require the deterministic reliability that only code can provide.
+
+In our example, the PDF skill includes a pre-written Python script that reads a PDF and extracts all form fields. Claude can run this script without loading either the script or the PDF into context. And because code is deterministic, this workflow is consistent and repeatable.
+
+
+
+Skills can also include code for Claude to execute as tools at its discretion based on the nature of the task.
+
+## Developing and evaluating skills
+
+Here are some helpful guidelines for getting started with authoring and testing skills:
+
+* **Start with evaluation:** Identify specific gaps in your agents’ capabilities by running them on representative tasks and observing where they struggle or require additional context. Then build skills incrementally to address these shortcomings.
+* **Structure for scale:** When the `SKILL.md` file becomes unwieldy, split its content into separate files and reference them. If certain contexts are mutually exclusive or rarely used together, keeping the paths separate will reduce the token usage. Finally, code can serve as both executable tools and as documentation. It should be clear whether Claude should run scripts directly or read them into context as reference.
+* **Think from Claude’s perspective:** Monitor how Claude uses your skill in real scenarios and iterate based on observations: watch for unexpected trajectories or overreliance on certain contexts. Pay special attention to the `name` and `description` of your skill. Claude will use these when deciding whether to trigger the skill in response to its current task.
+* **Iterate with Claude:** As you work on a task with Claude, ask Claude to capture its successful approaches and common mistakes into reusable context and code within a skill. If it goes off track when using a skill to complete a task, ask it to self-reflect on what went wrong. This process will help you discover what context Claude actually needs, instead of trying to anticipate it upfront.
+
+### Security considerations when using Skills
+
+Skills provide Claude with new capabilities through instructions and code. While this makes them powerful, it also means that malicious skills may introduce vulnerabilities in the environment where they’re used or direct Claude to exfiltrate data and take unintended actions.
+
+We recommend installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use. Start by reading the contents of the files bundled in the skill to understand what it does, paying particular attention to code dependencies and bundled resources like images or scripts. Similarly, pay attention to instructions or code within the skill that instruct Claude to connect to potentially untrusted external network sources.
+
+## The future of Skills
+
+Agent Skills are [supported today](https://www.anthropic.com/news/skills) across [Claude.ai](http://claude.ai/redirect/website.v1.bdb29daa-1a07-41ec-87f6-579dc33634bd), Claude Code, the Claude Agent SDK, and the Claude Developer Platform.
+
+In the coming weeks, we’ll continue to add features that support the full lifecycle of creating, editing, discovering, sharing, and using Skills. We’re especially excited about the opportunity for Skills to help organizations and individuals share their context and workflows with Claude. We’ll also explore how Skills can complement [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers by teaching agents more complex workflows that involve external tools and software.
+
+Looking further ahead, we hope to enable agents to create, edit, and evaluate Skills on their own, letting them codify their own patterns of behavior into reusable capabilities.
+
+Skills are a simple concept with a correspondingly simple format. This simplicity makes it easier for organizations, developers, and end users to build customized agents and give them new capabilities.
+
+We’re excited to see what people build with Skills. Get started today by checking out our Skills [docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) and [cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills).
+
+## Acknowledgements
+
+Written by Barry Zhang, Keith Lazuka, and Mahesh Murag, who all really like folders. Special thanks to the many others across Anthropic who championed, supported, and built Skills.
+
+No items found.
+
+[Prev](#)Prev
+
+0/5
+
+[Next](#)Next
+
+eBook
+
+## 
+
+
+
+
+
+FAQ
+
+No items found.
+
+Get Claude Code
+
+curl -fsSL https://claude.ai/install.sh | bash
+
+Copy command to clipboard
+
+irm https://claude.ai/install.ps1 | iex
+
+Copy command to clipboard
+
+Or read the [documentation](https://code.claude.com/docs/en/overview)
+
+Try Claude Code
+
+[Try Claude Code](https://claude.ai/code)Try Claude Code
+
+Developer docs
+
+[Developer docs](https://code.claude.com/docs/en/overview)Developer docs
+
+## Related posts
+
+Explore more product news and best practices for teams building with Claude.
+
+
+
+Mar 19, 2026
+
+### Product management on the AI exponential 
+
+Claude Code
+
+[Product management on the AI exponential ](#)Product management on the AI exponential 
+
+[Product management on the AI exponential ](/blog/product-management-on-the-ai-exponential)Product management on the AI exponential 
+
+
+
+Mar 18, 2026
+
+### Code with Claude comes to San Francisco, London, and Tokyo
+
+Claude Code
+
+[Code with Claude comes to San Francisco, London, and Tokyo](#)Code with Claude comes to San Francisco, London, and Tokyo
+
+[Code with Claude comes to San Francisco, London, and Tokyo](/blog/code-with-claude-san-francisco-london-tokyo)Code with Claude comes to San Francisco, London, and Tokyo
+
+
+
+Mar 9, 2026
+
+### Bringing Code Review to Claude Code
+
+Claude Code
+
+[Bringing Code Review to Claude Code](#)Bringing Code Review to Claude Code
+
+[Bringing Code Review to Claude Code](/blog/code-review)Bringing Code Review to Claude Code
+
+
+
+Mar 5, 2026
+
+### Common workflow patterns for AI agents—and when to use them
+
+Agents
+
+[Common workflow patterns for AI agents—and when to use them](#)Common workflow patterns for AI agents—and when to use them
+
+[Common workflow patterns for AI agents—and when to use them](/blog/common-workflow-patterns-for-ai-agents-and-when-to-use-them)Common workflow patterns for AI agents—and when to use them
+
+## Transform how your organization operates with Claude
+
+See pricing
+
+[See pricing](https://claude.com/pricing#api)See pricing
+
+Contact sales
+
+[Contact sales](https://claude.com/contact-sales)Contact sales
+
+Get the developer newsletter
+
+Product updates, how-tos, community spotlights, and more. Delivered monthly to your inbox.
+
+[Subscribe](#)Subscribe
+
+Please provide your email address if you'd like to receive our monthly developer newsletter. You can unsubscribe at any time.
+
+Thank you! You’re subscribed.
+
+Sorry, there was a problem with your submission, please try again later.
+
+[Homepage](https://claude.com)Homepage
+
+[Next](#)Next
+
+Thank you! Your submission has been received!
+
+Oops! Something went wrong while submitting the form.
+
+Write
+
+[Button Text](#)Button Text
+
+Learn
+
+[Button Text](#)Button Text
+
+Code
+
+[Button Text](#)Button Text
+
+Write
+
+* Help me develop a unique voice for an audience  
+Hi Claude! Could you help me develop a unique voice for an audience? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Improve my writing style  
+Hi Claude! Could you improve my writing style? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Brainstorm creative ideas  
+Hi Claude! Could you brainstorm creative ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+
+Learn
+
+* Explain a complex topic simply  
+Hi Claude! Could you explain a complex topic simply? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Help me make sense of these ideas  
+Hi Claude! Could you help me make sense of these ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Prepare for an exam or interview  
+Hi Claude! Could you prepare for an exam or interview? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+
+Code
+
+* Explain a programming concept  
+Hi Claude! Could you explain a programming concept? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Look over my code and give me tips  
+Hi Claude! Could you look over my code and give me tips? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Vibe code with me  
+Hi Claude! Could you vibe code with me? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+
+More
+
+* Write case studies  
+This is another test
+* Write grant proposals  
+Hi Claude! Could you write grant proposals? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to — like Google Drive, web search, etc. — if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational.  
+    
+Please execute the task as soon as you can - an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help!
+* Write video scripts  
+this is a test
+
+[Anthropic](https://www.anthropic.com/)Anthropic
+
+© \[year\] Anthropic PBC
+
+Products
+
+* Claude  
+[Claude](/product/overview)Claude
+* Claude Code  
+[Claude Code](/product/claude-code)Claude Code
+* Claude Code for Enterprise  
+[Claude Code for Enterprise](/product/claude-code/enterprise)Claude Code for Enterprise
+* Claude Cowork  
+[Claude Cowork](/product/cowork)Claude Cowork
+* Max plan  
+[Max plan](/pricing/max)Max plan
+* Team plan  
+[Team plan](/pricing/team)Team plan
+* Enterprise plan  
+[Enterprise plan](/pricing/enterprise)Enterprise plan
+* Download app  
+[Download app](/download)Download app
+* Pricing  
+[Pricing](/pricing)Pricing
+* Log in  
+[Log in](https://claude.ai/login)Log in
+
+Features
+
+* Claude for Chrome  
+[Claude for Chrome](/claude-for-chrome)Claude for Chrome
+* Claude for Slack  
+[Claude for Slack](/claude-for-slack)Claude for Slack
+* Claude for Excel  
+[Claude for Excel](/claude-for-excel)Claude for Excel
+* Claude for PowerPoint  
+[Claude for PowerPoint](/claude-for-powerpoint)Claude for PowerPoint
+* Skills  
+[Skills](/skills)Skills
+
+Models
+
+* Opus  
+[Opus](https://www.anthropic.com/claude/opus)Opus
+* Sonnet  
+[Sonnet](https://www.anthropic.com/claude/sonnet)Sonnet
+* Haiku  
+[Haiku](https://www.anthropic.com/claude/haiku)Haiku
+
+Solutions
+
+* AI agents  
+[AI agents](/solutions/agents)AI agents
+* Claude Code Security  
+[Claude Code Security](/solutions/claude-code-security)Claude Code Security
+* Code modernization  
+[Code modernization](/solutions/code-modernization)Code modernization
+* Coding  
+[Coding](/solutions/coding)Coding
+* Customer support  
+[Customer support](/solutions/customer-support)Customer support
+* Education  
+[Education](/solutions/education)Education
+* Financial services  
+[Financial services](/solutions/financial-services)Financial services
+* Government  
+[Government](/solutions/government)Government
+* Healthcare  
+[Healthcare](/solutions/healthcare)Healthcare
+* Life sciences  
+[Life sciences](/solutions/life-sciences)Life sciences
+* Nonprofits  
+[Nonprofits](/solutions/nonprofits)Nonprofits
+
+Claude Platform
+
+* Overview  
+[Overview](/platform/api)Overview
+* Developer docs  
+[Developer docs](https://platform.claude.com/docs)Developer docs
+* Pricing  
+[Pricing](https://claude.com/pricing#api)Pricing
+* Marketplace  
+[Marketplace](/platform/marketplace)Marketplace
+* Amazon Bedrock  
+[Amazon Bedrock](/partners/amazon-bedrock)Amazon Bedrock
+* Google Cloud’s Vertex AI  
+[Google Cloud’s Vertex AI](/partners/google-cloud-vertex-ai)Google Cloud’s Vertex AI
+* Microsoft Foundry  
+[Microsoft Foundry](/partners/microsoft-foundry)Microsoft Foundry
+* Regional compliance  
+[Regional compliance](/regional-compliance)Regional compliance
+* Console login  
+[Console login](https://platform.claude.com/)Console login
+
+Resources
+
+* Blog  
+[Blog](/blog)Blog
+* Claude partner network  
+[Claude partner network](/partners)Claude partner network
+* Community  
+[Community](/community)Community
+* Connectors  
+[Connectors](/connectors)Connectors
+* Courses  
+[Courses](https://www.anthropic.com/learn)Courses
+* Customer stories  
+[Customer stories](/customers)Customer stories
+* Engineering at Anthropic  
+[Engineering at Anthropic](https://www.anthropic.com/engineering)Engineering at Anthropic
+* Events  
+[Events](https://www.anthropic.com/events)Events
+* Plugins  
+[Plugins](/plugins)Plugins
+* Powered by Claude  
+[Powered by Claude](/partners/powered-by-claude)Powered by Claude
+* Service partners  
+[Service partners](/partners/services)Service partners
+* Startups program  
+[Startups program](/programs/startups)Startups program
+* Tutorials  
+[Tutorials](/resources/tutorials)Tutorials
+* Use cases  
+[Use cases](/resources/use-cases)Use cases
+
+Company
+
+* Anthropic  
+[Anthropic](https://www.anthropic.com/)Anthropic
+* Careers  
+[Careers](https://www.anthropic.com/careers)Careers
+* Economic Futures  
+[Economic Futures](https://www.anthropic.com/economic-futures)Economic Futures
+* Research  
+[Research](https://www.anthropic.com/research)Research
+* News  
+[News](https://www.anthropic.com/news)News
+* Responsible Scaling Policy  
+[Responsible Scaling Policy](https://www.anthropic.com/news/announcing-our-updated-responsible-scaling-policy)Responsible Scaling Policy
+* Security and compliance  
+[Security and compliance](https://trust.anthropic.com/)Security and compliance
+* Transparency  
+[Transparency](https://anthropic.com/transparency)Transparency
+
+Help and security
+
+* Availability  
+[Availability](https://www.anthropic.com/supported-countries)Availability
+* Status  
+[Status](https://status.anthropic.com/)Status
+* Support center  
+[Support center](https://support.claude.com/en/)Support center
+
+Terms and policies
+
+* Privacy choices  
+### Cookie settings  
+ We use cookies to deliver and improve our services, analyze site usage, and if you agree, to customize or personalize your experience and market our services to you. You can read our Cookie Policy [here](https://www.anthropic.com/legal/cookies).  
+ Customize cookie settings  Reject all cookies  Accept all cookies  
+###### Necessary  
+Enables security and basic functionality.  
+Required  
+###### Analytics  
+Enables tracking of site performance.  
+Off  
+###### Marketing  
+Enables ads personalization and tracking.  
+Off  
+ Save preferences
+* Privacy policy  
+[Privacy policy](https://www.anthropic.com/legal/privacy)Privacy policy
+* Responsible disclosure policy  
+[Responsible disclosure policy](https://www.anthropic.com/responsible-disclosure-policy)Responsible disclosure policy
+* Terms of service: Commercial  
+[Terms of service: Commercial](https://www.anthropic.com/legal/commercial-terms)Terms of service: Commercial
+* Terms of service: Consumer  
+[Terms of service: Consumer](https://www.anthropic.com/legal/consumer-terms)Terms of service: Consumer
+* Usage policy  
+[Usage policy](https://www.anthropic.com/legal/aup)Usage policy
+
+[x.com](https://x.com/claudeai)x.com
+
+[LinkedIn](https://www.linkedin.com/showcase/claude/)LinkedIn
+
+[YouTube](https://www.youtube.com/@anthropic-ai)YouTube
+
+[Instagram](https://www.instagram.com/claudeai)Instagram
+
+English (US)
+
+[](/blog-product/claude-code)
+
+Claude Code
+
+[](/blog-product/claude-platform)
+
+Claude Platform
+
+[](/blog-usecases/agents)
+
+Agents
+
+[](/blog-usecases/coding)
+
+Coding
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BlogPosting",
+  "headline": "Equipping agents for the real world with Agent Skills",
+  "description": "Discover how Anthropic builds AI agents with practical capabilities through modular skills, enabling them to handle complex real-world tasks more effectively and reliably.",
+  "image": "",
+  "publisher": {
+    "@id": "https://claude.com/#organization"
+  },
+  "datePublished": "Oct 16, 2025",
+  "dateModified": "Jan 28, 2026",
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills"
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.18.7",
+  "version": "0.18.9",
   "description": "Persistent memory for Claude Code with native Skills integration, automatic capture, failure learning, and project scoping via MCP server",
   "main": "dist/index.js",
   "bin": {