@letta-ai/letta-code 0.34.16 → 0.34.18

package/npm-shrinkwrap.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.16",
+  "version": "0.34.18",
   "lockfileVersion": 3,
   "packages": {
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -61,15 +61,15 @@
       }
     },
     "node_modules/@aws-sdk/core": {
-      "version": "3.978.3",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.978.3.tgz",
-      "integrity": "sha512-nslpzUCTI9b2IQMWSd6mSAXldBexPc8rr0d3dXUutXYFLFaTdsHa2GD7sJdsn3PhyjK0O5K8ypd6zi+RXXPVlg==",
+      "version": "3.978.4",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.978.4.tgz",
+      "integrity": "sha512-JvGp6y9sPX8FSs2K/EmFMZcUfdkHxqGE45+oxwGC75OIh50j2e4cbx7zcR3BwNs2DSGqJdBja5h6Vy89iIDmRQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
         "@aws-sdk/xml-builder": "^3.972.41",
         "@aws/lambda-invoke-store": "^0.3.0",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/signature-v4": "^5.7.4",
         "@smithy/types": "^4.19.0",
         "bowser": "^2.11.0",
@@ -80,14 +80,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-env": {
-      "version": "3.972.74",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.74.tgz",
-      "integrity": "sha512-rsRJcW2iFUhCgclyD6OSbMEaPl8Eu0qSeRZb2uuCK1ViZ66hl5wOe/p6Vr6MO3b+ydyKgFeqza2p6tZThvILlw==",
+      "version": "3.972.75",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.75.tgz",
+      "integrity": "sha512-nc8Epg98PcYoKNx0VFlwtmZSCP+tuJ1FLWqpslET/gp4h/WYuULSJqtxppM6ywKKDdzNJPvLD7ceRfmxm3Qdxw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -96,14 +96,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-http": {
-      "version": "3.972.76",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.76.tgz",
-      "integrity": "sha512-pnKdh0Br7OJPj+7qKjzgTfDTFW0RhEMKXNDR2jv9CAM4oHuG/4z3hRh8KtutLfpmItuRtDbKBmwWkDqHwwAWXw==",
+      "version": "3.972.77",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.77.tgz",
+      "integrity": "sha512-KkYFdIQwuw9IOHfEzK78slxmVWuhcm1w6YgE3V3WVxAeRRj9q5J9jlwzpY/oszWxd4SD96FTFkDdRGBdMFF2Mw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/node-http-handler": "^4.12.1",
         "@smithy/types": "^4.19.0",
@@ -114,21 +114,21 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-ini": {
-      "version": "3.973.19",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.19.tgz",
-      "integrity": "sha512-kcjvAxqQEV8yuwkX58RelNn3ne65o7JgRWf3Z/gVvbi7Xuw1qSDLJlatrLD76+40cmRxmNkLxBoyp/vAQChQ5g==",
+      "version": "3.973.20",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.20.tgz",
+      "integrity": "sha512-OSl2R/0zLkoeKEIy6oP2tu/bsSdY+DGgro2eOffMD2CcP8POv7rS14FY5Jzc5bjnqB1G9wv/aM1akHC2mdlhZw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/credential-provider-env": "^3.972.74",
-        "@aws-sdk/credential-provider-http": "^3.972.76",
-        "@aws-sdk/credential-provider-login": "^3.972.81",
-        "@aws-sdk/credential-provider-process": "^3.972.74",
-        "@aws-sdk/credential-provider-sso": "^3.973.18",
-        "@aws-sdk/credential-provider-web-identity": "^3.972.80",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/credential-provider-env": "^3.972.75",
+        "@aws-sdk/credential-provider-http": "^3.972.77",
+        "@aws-sdk/credential-provider-login": "^3.972.82",
+        "@aws-sdk/credential-provider-process": "^3.972.75",
+        "@aws-sdk/credential-provider-sso": "^3.973.19",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.81",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/credential-provider-imds": "^4.5.2",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
@@ -138,15 +138,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-login": {
-      "version": "3.972.81",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.81.tgz",
-      "integrity": "sha512-CeQHSbE2CnVdaHIJ/NayRaCecIER+Pm9faUPkmRATO54rCoMTEPSbVieGHzEwvm1dZM2HIs6qQZCznhayNTWJQ==",
+      "version": "3.972.82",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.82.tgz",
+      "integrity": "sha512-8jyDPtf1WPxeQ/5xlNpyxAD6P7YKwkYeNk8B2vFEDwkPWDvb7c3tQJG5/jbNWbF2yTMIH9tDTueBkdfovYIAPw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -155,19 +155,19 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-node": {
-      "version": "3.972.86",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.86.tgz",
-      "integrity": "sha512-WNttSyr6e8innPtBSty//CdnqJcgZN6eAbtw3v/CR2IObz6MYZEo8eusdtuCHJ2ujwFqC2bSPHVyhXGHx8HruQ==",
+      "version": "3.972.87",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.87.tgz",
+      "integrity": "sha512-TKj2C0x4IMPSSOAlmeryX8fCPvvPS2pFJz2ikV9IGqyh6Ehsg4leMalCTVfV2rvMTrlGAe7X7nK0HZ3P0KZR9g==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/credential-provider-env": "^3.972.74",
-        "@aws-sdk/credential-provider-http": "^3.972.76",
-        "@aws-sdk/credential-provider-ini": "^3.973.19",
-        "@aws-sdk/credential-provider-process": "^3.972.74",
-        "@aws-sdk/credential-provider-sso": "^3.973.18",
-        "@aws-sdk/credential-provider-web-identity": "^3.972.80",
+        "@aws-sdk/credential-provider-env": "^3.972.75",
+        "@aws-sdk/credential-provider-http": "^3.972.77",
+        "@aws-sdk/credential-provider-ini": "^3.973.20",
+        "@aws-sdk/credential-provider-process": "^3.972.75",
+        "@aws-sdk/credential-provider-sso": "^3.973.19",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.81",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/credential-provider-imds": "^4.5.2",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
@@ -177,14 +177,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-process": {
-      "version": "3.972.74",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.74.tgz",
-      "integrity": "sha512-Yj6kZFJQdbR+PygTkqdVLPHHpdDpOS9GCYVcDCuweCRRig9LF24ELQBMfyUw1vspvrZJUfnOGVyMjhaL094ahw==",
+      "version": "3.972.75",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.75.tgz",
+      "integrity": "sha512-ZNm8T/HJNhpS8MikDVAsym8QyUSUuOUGiCkmI3TTya7G6xhOgfRLd2iK91HhQQyvRM36eo6Xm845hHVyfToA2w==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -193,16 +193,16 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-sso": {
-      "version": "3.973.18",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.18.tgz",
-      "integrity": "sha512-FnpPhdY4qUGtX/8X6eKxh+uD+9Y19i9FYibgk4SBe0M935s9vocHkHzaxaMNk+YkHmvzgdu8cHA5SCoeU+kkew==",
+      "version": "3.973.19",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.19.tgz",
+      "integrity": "sha512-qHGDAGesyWtRw3BapyFkYSUzVNrC1CWPS6+S2lf/MLMEkWB2gR3Bl6imVHy1nhImXKS+gcuUDzbu39BnsHJc1Q==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
-        "@aws-sdk/token-providers": "3.1150.0",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
+        "@aws-sdk/token-providers": "3.1153.0",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -211,15 +211,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-sso/node_modules/@aws-sdk/token-providers": {
-      "version": "3.1150.0",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1150.0.tgz",
-      "integrity": "sha512-wDU36ofhabZYu+d2KSriyDbwzxNoaOp+4dG0p3qkabk7HeALR5nIWyQbjoyJZLn3iqWkv/xNdyUfbfevDVDzzg==",
+      "version": "3.1153.0",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1153.0.tgz",
+      "integrity": "sha512-6bKJ2OfLboxhzeJ3hBDeB8L6emCYf9DfdrjBAharLrY42J1RV/6jA6G8jvfNghzID8Yb40BdSY7jQMtWx9Ot0Q==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -228,15 +228,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-web-identity": {
-      "version": "3.972.80",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.80.tgz",
-      "integrity": "sha512-TJF25Ndwy2HxcVj6oxMgp8qVlJAawlExHYBXqhuC6Zt2m+A7WpdkjBD6QglNbiArlteYljZHEY3R7KKmno6ISA==",
+      "version": "3.972.81",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.81.tgz",
+      "integrity": "sha512-nHkgkMIC6NHgqfI6UAQq5cCS4bUkNxkT+r9fXCq/X4IKfX/DHGZ8UM3T4b78OXpWK5OlzEzN4kxwyax0W/MUCA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -245,13 +245,13 @@
       }
     },
     "node_modules/@aws-sdk/eventstream-handler-node": {
-      "version": "3.972.36",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.36.tgz",
-      "integrity": "sha512-HFaKXA6ugPVvpR7W/3UT3hylWIPndqGMwduwNVrmGsRT5+OESHN8/ven4eeofraQF5Kxp8A8QgGVrv7iQsTRKQ==",
+      "version": "3.972.37",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.37.tgz",
+      "integrity": "sha512-vU0v4d6anhLqBCpPq7Q7hD2Av3/5qOR5O30Ze8ALLysgB3iMQTPHQ/P2aTgfrY2ZjnVJUCi7NiTSNqa1mDF+5w==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -260,13 +260,13 @@
       }
     },
     "node_modules/@aws-sdk/middleware-eventstream": {
-      "version": "3.972.31",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.31.tgz",
-      "integrity": "sha512-4yvdTVwPGKCnrwuwlYEmwLqQXKwk0unx3f/FvBi4FA9ruK/WGoPJyqfK7hOYurheIyQL44FR0ovgOHqvkfdpAQ==",
+      "version": "3.972.32",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.32.tgz",
+      "integrity": "sha512-D3ayeW/K2lTQI8+SyzDvAKfM3N4SFJjfgqeHbS3DOZmmQebZyve6WUyJiqOKqeOxmIcFxTzpSdsijnRF035J3g==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -275,14 +275,14 @@
       }
     },
     "node_modules/@aws-sdk/middleware-websocket": {
-      "version": "3.972.56",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.56.tgz",
-      "integrity": "sha512-32d9EnnNM5UMwjVp/qnL0K4XYiZv+YlSbULI3BaoBdJvebAS6cD0bKfPJ7lzovN0qrelvmSh5jo/3tk0KoTuGQ==",
+      "version": "3.972.57",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.57.tgz",
+      "integrity": "sha512-mPNUOedufUwZXISOEySSP7l7owyY0Ypp1ajsd1GsB4E5Vpaf8NtfmmNygyPPeGPsRZ1sOcS90aAhQ03yPy/pFg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/signature-v4": "^5.7.4",
         "@smithy/types": "^4.19.0",
@@ -293,15 +293,15 @@
       }
     },
     "node_modules/@aws-sdk/nested-clients": {
-      "version": "3.997.48",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.48.tgz",
-      "integrity": "sha512-B01jdXJtAW/XOiUzGdI2mz67WyEHbGEc9X6Euzw3bjLAa+txTqdZDER4X2FsIEcXzV2ABqudVZ5thali8tCCzQ==",
+      "version": "3.997.49",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.49.tgz",
+      "integrity": "sha512-zjqIqzTYLRKhT7TPJDUreK9vG9PjhmnfLCaTaqArkRT7j+Ogl0tuXB7MpSd8rlRfRT+xTOeyNFWaOfyNcf51hg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/signature-v4-multi-region": "^3.996.48",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/node-http-handler": "^4.12.1",
         "@smithy/types": "^4.19.0",
@@ -5452,7 +5452,7 @@
     },
     "": {
       "name": "@letta-ai/letta-code",
-      "version": "0.34.16",
+      "version": "0.34.18",
       "dependencies": {
         "@earendil-works/pi-ai": "^0.99.1",
         "@janhapke/sharp-electron": "0.35.3-electron.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.16",
+  "version": "0.34.18",
   "lettaStartupLogProtocol": 1,
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
@@ -275,5 +275,5 @@
   },
   "lettaLifecycleProtocol": 1,
   "lettaRuntimeGraphProtocol": 1,
-  "lettaRuntimeGraphSha512": "sha512-NGzNq0UmSHPiPqvc6bflUL57U2h5xZSgf9HvpbR98ocuoM1dHLN1hiXv6qNEa3lOlj2paYI/clNKR+U1YW0TiA=="
+  "lettaRuntimeGraphSha512": "sha512-cubBaizY8rbgiq9dfHU/uRyZBgkGvLfJc+8+ovpV1raZnQjE+tRsAKFAKP69UHWhNFRE49viVTyqmLIiSK8v8Q=="
 }

package/scripts/source-file-size-baseline.json

@@ -1,5 +1,5 @@
 {
-  "src/agent/client-skills.test.ts": 1134,
+  "src/agent/client-skills.test.ts": 1132,
   "src/agent/memory-git.ts": 2013,
   "src/backend/local-backend.test.ts": 2472,
   "src/backend/local/local-store.ts": 3261,
@@ -19,7 +19,7 @@
   "src/cli/mods/local-mod-loader.test.ts": 1043,
   "src/cli/reflection-transcript.test.ts": 1084,
   "src/cli/subcommands/skills.ts": 1264,
-  "src/headless.ts": 4778,
+  "src/headless.ts": 4771,
   "src/hooks/integration.test.ts": 1147,
   "src/index.ts": 2575,
   "src/mods/learning-harness.ts": 2434,
@@ -33,7 +33,7 @@
   "src/providers/chatgpt-usage-service.ts": 1112,
   "src/settings-manager.test.ts": 1635,
   "src/settings-manager.ts": 2092,
-  "src/tools/manager.ts": 2609,
+  "src/tools/manager.ts": 2606,
   "src/tools/tool-execution-context.test.ts": 1092,
   "src/types/protocol_v2.ts": 2532,
   "src/websocket/listener/message-router.ts": 1005,

package/skills/creating-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-skills
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations.
+description: Guide for creating effective skills. Use when creating a new skill or updating an existing one that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations, whether a user asks for it or a reusable workflow is worth capturing.
 ---
 
 # Creating Skills
@@ -206,7 +206,7 @@ Skill creation involves these steps:
 2. Plan reusable skill contents (scripts, references, assets)
 3. Initialize the skill (run init-skill.ts)
 4. Edit the skill (implement resources and write SKILL.md)
-5. Package the skill (run package-skill.ts)
+5. Package the skill if it will be distributed (run package-skill.ts)
 6. Iterate based on real usage
 
 Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
@@ -215,16 +215,15 @@ Follow these steps in order, skipping only if there is a clear reason why they a
 
 Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
 
-To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+To create an effective skill, clearly understand concrete examples of how the skill will be used. Draw them from the material at hand first: the conversation or transcripts that motivated the skill, the commands and tool calls that worked, and the requests that would trigger it.
 
-For example, when building an `editing-images` skill, relevant questions include:
+For example, when building an `editing-images` skill, establish:
 
-- "What functionality should the editing-images skill support? Editing, rotating, anything else?"
-- "Can you give some examples of how this skill would be used?"
-- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
-- "What would a user say that should trigger this skill?"
+- What functionality the skill should support: editing, rotating, anything else?
+- What concrete requests it should handle, such as "Remove the red-eye from this image" or "Rotate this image"
+- What a user would say that should trigger the skill
 
-To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+If you are working with a user and these remain unclear, ask the most important questions first rather than many at once. If no one is available to ask, such as in a background or automated run, do not wait for answers: scope the skill to what the source material demonstrates and leave out functionality it does not support.
 
 Conclude this step when there is a clear sense of the functionality the skill should support.
 
@@ -265,7 +264,7 @@ Usage:
 ```bash
 npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>
 ```
-Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header).
+Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header). If no Skill Directory is shown, create the skill directory and `SKILL.md` directly instead.
 
 The script:
 
@@ -291,7 +290,7 @@ These files contain established best practices for effective skill design.
 
 #### Start with Reusable Skill Contents
 
-To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Some resources come from outside the source material. For example, a `brand-guidelines` skill may need brand assets or templates in `assets/`, or documentation in `references/`. Ask the user for them if you are working with one; otherwise include only what is available and leave out resources you cannot supply.
 
 Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
 
@@ -333,7 +332,9 @@ Write instructions for using the skill and its bundled resources.
 
 ### Step 5: Packaging a Skill
 
-Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+Package the skill only when it needs to be distributed as a file, for example when sharing it with a user. Skills maintained in place, such as those under an agent's memory `skills/` directory, are used directly and need no packaging.
+
+To package a skill into a distributable .skill file, run the packaging script. The packaging process automatically validates the skill first to ensure it meets all requirements:
 
 ```bash
 npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder>
@@ -360,7 +361,7 @@ If validation fails, the script will report the errors and exit without creating
 
 ### Step 6: Iterate
 
-After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+Improve a skill when real usage shows it falling short, whether through user feedback or sessions where the skill was used. Usage with fresh context of how the skill performed is the best evidence.
 
 **Iteration workflow:**
 

package/skills/maintaining-core-memory/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: maintaining-core-memory
+description: Maintains an agent's core memory, the editable part of its system prompt. Use to modify the agent's core behavior, embed critical knowledge (needed on every turn), or instruct the agent on how to use deferred memory.
+---
+
+Core memory is the agent's prompt, refined over its lifetime. Treat each change as a revision of that prompt, not an append to a log: the usual edit sharpens, merges, or replaces an existing principle, and a new one earns its place only when no existing one can absorb it.
+
+## Prompt format
+
+The agent's system prompt is compiled from the Markdown files at the root of `$MEMORY_DIR`. Each root file except `MEMORY.md` becomes a block named after the file, in alphabetical order by filename, followed by the root `MEMORY.md`:
+
+```
+{{base system prompt}}
+
+<human>
+<description>{{description from human.md frontmatter}}</description>
+{{body of human.md}}
+</human>
+
+<persona>
+<description>{{description from persona.md frontmatter}}</description>
+{{body of persona.md}}
+</persona>
+
+<memory>
+{{body of root MEMORY.md}}
+<deferred-memory>
+<directory path="{{dir}}/" index="{{dir}}/MEMORY.md" />
+</deferred-memory>
+</memory>
+```
+
+Every root file except `MEMORY.md` starts with frontmatter containing exactly two fields:
+
+```markdown
+---
+name: human
+description: Who the user is and how they want to work together.
+---
+```
+
+- The file name becomes the block name, so `human.md` renders as `<human>`. Choose short, stable names.
+- The `description` is rendered into the prompt. Write it for the agent: one line saying what the block holds.
+- Root `MEMORY.md` has no frontmatter. Its body is the only part of `<memory>` you write.
+- The `<deferred-memory>` list is generated: one entry per top-level directory that has its own `MEMORY.md`, showing only the path. `skills/` is never listed; skills appear separately.
+- Edits take effect only after they are committed, and only in later system prompts. The current conversation keeps the prompt it started with.
+
+Read `$MEMORY_DIR/.memfs.config.json` if it exists. The memory repository's pre-commit hook enforces it:
+
+- `maxCoreMemoryCharacters` caps the total size of all root Markdown (default 65,536 characters).
+- `maxFileCharacters` caps each memory file, frontmatter included (default 20,000 characters). `fileCharacterLimits` overrides it per glob; the first match wins and `null` removes the cap.
+- `readOnlyFiles` lists globs whose files cannot change. Do not edit them.
+
+When the config file is absent, the defaults apply. Treat the limits as a ceiling, not a target: stay well below them. When an edit does not fit, move detail into deferred memory instead of raising a limit; change the config only when the user asks.
+
+## Writing prompts
+
+Core memory is the agent's working model: who it is, how the user thinks and what they value, and the principles that follow. It is not a list of rules.
+
+- Treat a correction or preference as evidence about that model. Find the principle it belongs to and sharpen or rewrite that principle. Add a new one only when the evidence shows something the model was missing.
+- When several rules share a cause, replace them with the one principle that explains them all, and delete the lines it absorbs in the same edit. Adding the principle while keeping the old rules is a log with a summary on top. A healthy file becomes more general over time; a growing count of narrow rules is a sign of failure.
+- State the principle with the reason that makes it generalize: "Verify claims against the running system, because Sarah trusts evidence over plausibility", not three separate rules about tests, logs, and deployments.
+- Write to the agent in the second person or imperative mood: "Lead with the answer", not "The user likes answers first". Say what to do rather than only what to avoid.
+- Leave out provenance: no names, dates, quotes, or stories about the incident. Message history already holds the events, and the commit message records why the line changed. When you edit a section that already contains provenance-laden rules, rewrite them as principles; nothing is lost, because git keeps the old text.
+- Update only from a pattern or an explicit instruction, not a single ambiguous event.
+- Check that a change does not contradict an existing line; resolve the conflict instead of adding both.
+- Write in plain language without all-caps or absolute emphasis. Overstated instructions get overapplied.
+- Leave out content the agent can cheaply rederive: file contents, command lists, current status, and recent activity.
+- Never store secrets. Reference them by name, such as `$SECRET_NAME`.
+
+## Teach with examples, not more rules
+
+A correction that reveals a gap in a principle calls for sharpening its wording. A correction the principle already covers, such as the user pointing out the same kind of mistake again, means the principle is too abstract to apply: attach a contrastive example to it instead of rewording it again or adding another rule.
+
+```markdown
+- Lead with the answer, because the user reads the first line and skims the rest.
+  - Not: "I looked at the config, then the logs, and it turns out the timeout is too low." Instead: "The timeout is too low: 5s, and the slow query takes 8s."
+```
+
+- Keep at most one or two examples per principle, and make them differ from each other. A new correction replaces the weaker example rather than adding another.
+- Write the example as a generic instance of the behavior, not a record of the incident: no dates, names, or quotes.
+- Keep the bad half short and labeled, and end on the good half. The agent imitates the details of examples, including the ones it should avoid.
+- When a principle or example starts producing the wrong behavior, revise or remove it. A memory edit is a hypothesis about the agent's behavior; later conversations test it.
+
+## Design root MEMORY.md so deferred memory gets used
+
+The agent consults deferred memory only when something in its prompt tells it to. The generated `<deferred-memory>` list gives directory paths and nothing else, so root `MEMORY.md` decides whether everything outside core memory is ever read. A directory with no useful entry here is effectively lost.
+
+- Give each directory a one-line entry saying when to open it, in the words a future request would use: "deployments, rollbacks, on-call runbooks", not "ops notes".
+- Name a specific deeper file when its topic would not be guessable from the directory entry.
+- Say what kinds of questions should send the agent to memory before it answers from assumption, such as an unfamiliar person, project, or system named in the conversation.
+- Do not re-index root files or skills; both are already in the prompt.
+- After adding a directory or file, check that a natural future request would reach it by reading only root `MEMORY.md` and the indexes beneath it.
+
+## Shrink before you grow
+
+When a root file is long or the total is near its limit:
+
+1. Delete stale, duplicated, or rederivable content.
+2. Move subject detail into deferred memory and leave a one-line pointer in root `MEMORY.md`.
+3. Move procedures into skills.