@djordje-stojanovic/sigmaskills 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to [Sigmaskills](https://github.com/Djordje-Stojanovic/Sigma
 
 ## [Unreleased]
 
+## [0.6.1] — 2026-10-06
+
+### Changed
+
+- A changed front-matter `description` in `SKILL.md` now counts as a Skill Customization. `status` reports it as `valid-customization`, not as corruption. `update --yes` keeps your description when it installs a new Release. If the new Release changes the description itself, `update` still asks for `--outside-edit` first. (#94)
+
 ## [0.6.0] — 2026-10-06
 
 ### Added
@@ -226,7 +232,8 @@ Ship high-rigor, installable agent skills (not apps): full-repo audits, performa
 | 2026-08-11 | `5dab832` | Add CHANGELOG and mark v0.1.0 as the first Sigmaskills release |
 | 2026-08-11 | `124a666` | Polish v0.1.0 docs for multi-host install and use |
 
-[Unreleased]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/Djordje-Stojanovic/Sigmaskills/compare/v0.4.0...v0.5.0

package/README.md

@@ -6,7 +6,7 @@ Portable [Agent Skills](https://agentskills.io/) that install once and run on **
 
 | | |
 |---|---|
-| **Release** | [**v0.6.0**](https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.6.0) |
+| **Release** | [**v0.6.1**](https://github.com/Djordje-Stojanovic/Sigmaskills/releases/tag/v0.6.1) |
 | **Changelog** | [CHANGELOG.md](CHANGELOG.md) |
 | **License** | [MIT](LICENSE) |
 | **Spec** | [agentskills.io](https://agentskills.io/) |

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "sigmaskills",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Portable Agent Skills monorepo and first-party Sigma Installer",
   "skills": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djordje-stojanovic/sigmaskills",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Portable Agent Skills monorepo and first-party Sigma Installer",
   "type": "module",
   "license": "MIT",

package/registry/skill-baselines.json

@@ -71,6 +71,16 @@
           "references/brief-method.md": "1bd9200bec7d41106bdff4f0ab39b86597bb2524b8d37af0eb663e9ec854770e",
           "references/prompt-contract.md": "198bc5ab7a4c27fa14f3c168fe2f79bf1851e1ab7ef89cd95e551df5e398485a"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "4ec9b13a2e3e0cf10f6f218ee5e733f290575f8870bf56feb29e7d69e6b884c0",
+        "files": {
+          "SKILL.md": "442f9ba7785a30510df995b85b89b95f429d3dd5fe051dc85850309d6361d9e5",
+          "agents/openai.yaml": "69c0219b0f8ab7974527ca9f6fb06b67b21683a42ac1de63ef6014cdef1dde85",
+          "references/brief-method.md": "1bd9200bec7d41106bdff4f0ab39b86597bb2524b8d37af0eb663e9ec854770e",
+          "references/prompt-contract.md": "198bc5ab7a4c27fa14f3c168fe2f79bf1851e1ab7ef89cd95e551df5e398485a"
+        }
       }
     ],
     "sigmaperformance": [
@@ -192,6 +202,17 @@
           "references/method.md": "659848b0d8a7e2dbcbde3fa88de09d07f20b68bb91ea808e766d526b137adc03",
           "references/report.md": "ebabc522ac35dcfd7538abe4657d4933bf795d5ea20242a968592e0c569e7b41"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "5ce9fb447bb7c3035c98cc3c8d2e46f960f93fb5ca45482a7c94233f1929e196",
+        "files": {
+          "SKILL.md": "d900e0d033861065542308c966a9e2e2ec5322a70ce2614aba6e8bddb7d9fb07",
+          "agents/openai.yaml": "fc9f585d84b751aa9978d3b275a9f8b0383a1d57cb49fec27e905e794fa14d5a",
+          "references/measure.md": "efd083364caedfce9c5e69a2267209d3317cfa218029b48455e49cdc2f9affe0",
+          "references/method.md": "659848b0d8a7e2dbcbde3fa88de09d07f20b68bb91ea808e766d526b137adc03",
+          "references/report.md": "ebabc522ac35dcfd7538abe4657d4933bf795d5ea20242a968592e0c569e7b41"
+        }
       }
     ],
     "sigmawrite": [
@@ -250,6 +271,14 @@
           "SKILL.md": "8db1872ac240efceec949d6b5e13c651b38e1de7b4c82588375c7dcd8f123cb1",
           "agents/openai.yaml": "19b53dc100195c2d8cfd03720028f577ce8e3ba95829551c6d31d96a23021144"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "ff7cf7f2ff2851b916a5ed4aa856b0b9421095e94e60e8fe88fa0614b363cc9c",
+        "files": {
+          "SKILL.md": "8db1872ac240efceec949d6b5e13c651b38e1de7b4c82588375c7dcd8f123cb1",
+          "agents/openai.yaml": "19b53dc100195c2d8cfd03720028f577ce8e3ba95829551c6d31d96a23021144"
+        }
       }
     ],
     "sigmarefactor": [
@@ -288,6 +317,15 @@
           "agents/openai.yaml": "baaa351482edffe072ae708968dcc1c70842caebf38a8aa7fd667b8da7a01c70",
           "references/scan.md": "049715a6948138109b64994e969a1ed5541cab8151b8c8d9070d5eae379d45c5"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "25b4efaa5d9d9309791dbbec0f1a32eab409137c4cd16892f646714019b04115",
+        "files": {
+          "SKILL.md": "a6bef0c53cf780c79da20204cbbd15db65fa98dac3afa0ef1c8475725cd7f4cb",
+          "agents/openai.yaml": "baaa351482edffe072ae708968dcc1c70842caebf38a8aa7fd667b8da7a01c70",
+          "references/scan.md": "049715a6948138109b64994e969a1ed5541cab8151b8c8d9070d5eae379d45c5"
+        }
       }
     ],
     "sigmaimprove": [
@@ -323,6 +361,17 @@
           "references/issue.md": "59300698c9a1d32e1d868173b22dea5fcc7ea7b7ca97198faf688256e5638300",
           "references/lenses.md": "c5f2982ed1f4330035895dabacef550a5c1b241e0e1a370547b8715f89f3f8b3"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "9efbc885f031786dd84637009a3b8c38806c50d587b84799692fe60828c32da0",
+        "files": {
+          "SKILL.md": "118dacdc212f6f359ad9be0564492451bb2dc93f1f03c8af0094994caeff3060",
+          "agents/openai.yaml": "ba80d59887cef951c006ad52ddd42fa1999d12b464dff17b6bb0b711f7eb505f",
+          "references/categories.md": "58ad43e0da22b5a67f0bec01abc13760ffa835dec9efc07343b07e8326cba7bd",
+          "references/issue.md": "59300698c9a1d32e1d868173b22dea5fcc7ea7b7ca97198faf688256e5638300",
+          "references/lenses.md": "c5f2982ed1f4330035895dabacef550a5c1b241e0e1a370547b8715f89f3f8b3"
+        }
       }
     ],
     "sigmaship": [
@@ -355,6 +404,40 @@
           "references/land.md": "a1ae956d9017a9b67af68d6d71521d969b78e97cc1f9c3997d4bcedf9d69465f",
           "references/review-round.md": "e9062112683c71c28dd3bee5329afd6b9bd555ac83a1643b5f7ae5946b09df3a"
         }
+      },
+      {
+        "release": "0.6.0",
+        "revision": "248e37ea81d74561de3600e936143dbd1b7ae5543492fb7f1f8770f61182e090",
+        "files": {
+          "SKILL.md": "572d6c64273cde938ecdb9e1bccb39bf6d72e21fc386704035a75b18930ee315",
+          "agents/openai.yaml": "29f73f7ef65b71dfd4efa27dfef26a961dae98eee2882c63084528b7abef3b96",
+          "references/land.md": "a1ae956d9017a9b67af68d6d71521d969b78e97cc1f9c3997d4bcedf9d69465f",
+          "references/review-round.md": "e9062112683c71c28dd3bee5329afd6b9bd555ac83a1643b5f7ae5946b09df3a"
+        }
+      }
+    ],
+    "easytalk": [
+      {
+        "release": "0.6.0",
+        "revision": "7e945683bf985978a80f8bddc752d9358063281729d306f537d2f542b7223fcf",
+        "files": {
+          "SKILL.md": "88d7dc079348c00ae89f5395403d93be10b45fe319799ef62ccb303c4ef64d7c",
+          "agents/openai.yaml": "2b37c8e632553692e561b7d1de7aa2d00ab7612136e5f873934bd49395c08c9e",
+          "template.html": "e59ee52b94e26f2727f4b007af4c29bc20c0c048775b74caa7fbd53988b94483"
+        }
+      }
+    ],
+    "sigmaresearch": [
+      {
+        "release": "0.6.0",
+        "revision": "7a69af76abe0c396745776dd75f94cef3e877642fe187427e4f32be92437cf7c",
+        "files": {
+          "SKILL.md": "76e09762fe34e212c9d6cd191b2a3773bad6e4446822a7e4a0d9375998ecffa0",
+          "agents/openai.yaml": "151f7a91edc15ded3969ade41ff3766c35bb73c4a0067bec4af77b42001265a3",
+          "references/public-sources.md": "97c328c261953dd19332abc3946d1c272a2572755daa61bbf93560d765667f0b",
+          "references/reddit.md": "0dfd0d2a78e40cf84103b3e0cfe29d8264c98d73b97b139e4b9f1738fdd52fcb",
+          "references/x.md": "63f24a0fb1f80e55d93ded34ba18d3721dea26f83fbaaa7041662278ec4577cc"
+        }
       }
     ]
   }

package/src/customization.js

@@ -318,6 +318,61 @@ export function injectRawCustomContent(baseMarkdownContent, rawCustomContent, sk
   return `${baseMarkdownContent.slice(0, startIndex + CUSTOM_BLOCK_START.length)}${rawCustomContent}${baseMarkdownContent.slice(endIndex)}`;
 }
 
+function descriptionSpan(markdown) {
+  const lines = markdown.split(/(?<=\n)/);
+  const bare = (line) => line.replace(/\r?\n$/, '');
+  if (bare(lines[0] || '') !== '---') return null;
+  const close = lines.findIndex((line, index) => index > 0 && bare(line) === '---');
+  const start = lines.findIndex((line, index) => index > 0 && index < close && /^description\s*:/.test(line));
+  if (close === -1 || start === -1) return null;
+  // Continuation lines are indented; blank lines inside a block scalar belong to it too.
+  let stop = start + 1;
+  for (let index = start + 1; index < close; index += 1) {
+    if (/^[ \t]+\S/.test(lines[index])) stop = index + 1;
+    else if (bare(lines[index]).trim() !== '') break;
+  }
+  return { lines, start, stop };
+}
+
+/**
+ * The raw front-matter `description` entry: its key line and indented continuation lines.
+ *
+ * @param {string} markdown
+ * @returns {string|null}
+ */
+export function readDescriptionEntry(markdown) {
+  const span = typeof markdown === 'string' ? descriptionSpan(markdown) : null;
+  return span ? span.lines.slice(span.start, span.stop).join('') : null;
+}
+
+/**
+ * Put a raw `description` entry into the front matter, in the file's own line endings.
+ * Returns the markdown unchanged when it has no description entry or no entry is given.
+ *
+ * @param {string} markdown
+ * @param {string|null} entry
+ * @returns {string}
+ */
+export function replaceDescriptionEntry(markdown, entry) {
+  const span = typeof entry === 'string' ? descriptionSpan(markdown) : null;
+  if (!span) return markdown;
+  const eol = span.lines[0].endsWith('\r\n') ? '\r\n' : '\n';
+  const lines = [...span.lines];
+  lines.splice(span.start, span.stop - span.start, entry.replace(/\r?\n/g, eol));
+  return lines.join('');
+}
+
+/**
+ * The live markdown with the official front-matter description in place of the local one.
+ *
+ * @param {string} liveMarkdown
+ * @param {string|null} officialMarkdown
+ * @returns {string}
+ */
+export function withOfficialDescription(liveMarkdown, officialMarkdown) {
+  return replaceDescriptionEntry(liveMarkdown, readDescriptionEntry(officialMarkdown));
+}
+
 export function escapeRegExp(string) {
   return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/src/status.js

@@ -3,7 +3,12 @@ import path from 'node:path';
 import { walkLiveFiles } from './backup.js';
 import { findPackageRoot } from './catalog.js';
 import { isPathInside } from './paths.js';
-import { inspectCustomizationBlock, CUSTOM_BLOCK_END, CUSTOM_BLOCK_START } from './customization.js';
+import {
+  inspectCustomizationBlock,
+  withOfficialDescription,
+  CUSTOM_BLOCK_END,
+  CUSTOM_BLOCK_START,
+} from './customization.js';
 import {
   UNIVERSAL_PROJECT_DESTINATION,
   listGlobalDestinationGroups,
@@ -60,16 +65,21 @@ function officialMarkdownShell(markdown) {
   return `${markdown.slice(0, start + CUSTOM_BLOCK_START.length)}${markdown.slice(end)}`;
 }
 
-function inspectSkillMarkdown(liveMarkdown, skillId, liveHash, bundledMarkdown, bundledHash) {
+function inspectSkillMarkdown(liveMarkdown, skillId, liveHash, bundledMarkdown, bundledHash, installedHash) {
   const inspection = inspectCustomizationBlock(liveMarkdown, skillId);
-  if (inspection.status !== 'valid') {
+  // An untouched copy of the installed Release is not a local description, even when the new Release changed it.
+  const localEdit = Boolean(installedHash) && liveHash !== installedHash;
+  const live = inspection.status === 'malformed' || !localEdit
+    ? liveMarkdown
+    : withOfficialDescription(liveMarkdown, bundledMarkdown);
+  if (inspection.status !== 'valid' && live === liveMarkdown) {
     return {
       status: inspection.status,
       officialHash: liveHash,
       hasCustomContent: false,
     };
   }
-  if (typeof bundledMarkdown === 'string' && officialMarkdownShell(liveMarkdown) === officialMarkdownShell(bundledMarkdown)) {
+  if (typeof bundledMarkdown === 'string' && officialMarkdownShell(live) === officialMarkdownShell(bundledMarkdown)) {
     return {
       status: 'valid',
       officialHash: bundledHash || liveHash,
@@ -87,7 +97,7 @@ function isPackagedResource(file) {
   return /^(references|scripts|assets|agents)\//.test(file);
 }
 
-function classifyLiveTree({ liveFiles, bundledFiles, skillId, skillMarkdown, bundledMarkdown }) {
+function classifyLiveTree({ liveFiles, bundledFiles, skillId, skillMarkdown, bundledMarkdown, installedFiles }) {
   const classifications = [];
   const officialFiles = { ...liveFiles };
 
@@ -98,6 +108,7 @@ function classifyLiveTree({ liveFiles, bundledFiles, skillId, skillMarkdown, bun
       liveFiles['SKILL.md'],
       bundledMarkdown,
       bundledFiles['SKILL.md'],
+      installedFiles?.['SKILL.md'],
     );
     officialFiles['SKILL.md'] = markdown.officialHash;
     if (markdown.status === 'malformed') classifications.push('malformed-markers');
@@ -308,6 +319,7 @@ export function collectStatus(options = {}) {
         skillId,
         skillMarkdown,
         bundledMarkdown,
+        installedFiles: copyEntry?.baseHashes || entry?.baseHashes,
       });
       destinations.push({
         relativeDestination,

package/src/transaction.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import { acquireFileLock } from './concurrency-lock.js';
 import path from 'node:path';
 import { findPackageRoot, validateSkill } from './catalog.js';
-import { injectRawCustomContent } from './customization.js';
+import { injectRawCustomContent, replaceDescriptionEntry } from './customization.js';
 import { commitSkillBackup, exportSkillTree, getBackupRoot, pruneOlderBackups } from './backup.js';
 import { createInstallPlan } from './plan.js';
 import { isForeignProjectLock, loadProjectLock, saveProjectLock, updateProjectLockSkill, PROJECT_LOCK_FILENAME } from './project-lock.js';
@@ -254,13 +254,16 @@ function stageSkill(tx) {
       );
     }
     fileHashes = validatedStaged.files;
-    if (params.preservedCustomRaw !== undefined) {
+    if (params.preservedCustomRaw !== undefined || params.preservedDescription !== undefined) {
       const stagedSkillMd = path.join(stagingDir, 'SKILL.md');
       if (pathExists(stagedSkillMd)) {
-        const stagedMarkdown = fs.readFileSync(stagedSkillMd, 'utf8');
+        let stagedMarkdown = fs.readFileSync(stagedSkillMd, 'utf8');
+        if (params.preservedCustomRaw !== undefined) {
+          stagedMarkdown = injectRawCustomContent(stagedMarkdown, params.preservedCustomRaw, skillId);
+        }
         fs.writeFileSync(
           stagedSkillMd,
-          injectRawCustomContent(stagedMarkdown, params.preservedCustomRaw, skillId),
+          replaceDescriptionEntry(stagedMarkdown, params.preservedDescription),
           'utf8',
         );
       }

package/src/update.js

@@ -8,6 +8,8 @@ import {
   extractRawCustomContent,
   injectRawCustomContent,
   inspectCustomizationBlock,
+  readDescriptionEntry,
+  withOfficialDescription,
 } from './customization.js';
 import {
   UNIVERSAL_PROJECT_DESTINATION,
@@ -190,20 +192,25 @@ function readSkillMarkdown(absDir) {
   return fs.readFileSync(skillMd, 'utf8');
 }
 
-function officialLiveFiles(liveFiles, liveMarkdown, bundledMarkdown, skillId) {
+function officialLiveFiles(liveFiles, liveMarkdown, bundledMarkdown, skillId, baseHashes) {
   const next = { ...liveFiles };
   if (typeof liveMarkdown !== 'string' || typeof bundledMarkdown !== 'string' || !next['SKILL.md']) {
-    return next;
+    return { files: next, localDescription: false };
   }
   const inspection = inspectCustomizationBlock(liveMarkdown, skillId);
-  if (inspection.status !== 'valid' && inspection.status !== 'empty') return next;
-  const emptied = injectRawCustomContent(
-    liveMarkdown,
-    extractRawCustomContent(bundledMarkdown, skillId),
-    skillId,
-  );
-  next['SKILL.md'] = hashBytes(Buffer.from(emptied, 'utf8'));
-  return next;
+  if (inspection.status !== 'valid' && inspection.status !== 'empty') return { files: next, localDescription: false };
+  const officialHash = (markdown) => hashBytes(Buffer.from(
+    injectRawCustomContent(markdown, extractRawCustomContent(bundledMarkdown, skillId), skillId),
+    'utf8',
+  ));
+  next['SKILL.md'] = officialHash(liveMarkdown);
+  // A local description counts as customization only when it is the one difference from the installed Release.
+  const withDescription = withOfficialDescription(liveMarkdown, bundledMarkdown);
+  const localDescription = withDescription !== liveMarkdown
+    && next['SKILL.md'] !== baseHashes['SKILL.md']
+    && officialHash(withDescription) === baseHashes['SKILL.md'];
+  if (localDescription) next['SKILL.md'] = baseHashes['SKILL.md'];
+  return { files: next, localDescription };
 }
 
 function customizationKind(markdown, skillId) {
@@ -236,7 +243,13 @@ function compareSkill(options) {
   const diagnosis = typeof liveMarkdown === 'string'
     ? diagnoseCustomizationMarkers(liveMarkdown, skillId)
     : { status: 'absent', shape: 'missing-file', repairable: false };
-  const officialLive = officialLiveFiles(liveFiles, liveMarkdown, bundledMarkdown, skillId);
+  const { files: officialLive, localDescription } = officialLiveFiles(
+    liveFiles,
+    liveMarkdown,
+    bundledMarkdown,
+    skillId,
+    baseHashes,
+  );
   const liveChanged = !mapsEqual(officialLive, baseHashes)
     || symlinkEffects(inventory).length > 0
     || detectTypeChanges(baseHashes, inventory).length > 0;
@@ -264,13 +277,13 @@ function compareSkill(options) {
   } else if (liveChanged) {
     comparison = 'local-only';
     changeKind = 'local-only';
-  } else if (upstreamChanged && customKind === 'populated') {
+  } else if (upstreamChanged && (customKind === 'populated' || localDescription)) {
     comparison = 'upstream-and-customization';
     changeKind = 'upstream-only';
   } else if (upstreamChanged) {
     comparison = 'upstream-only';
     changeKind = 'upstream-only';
-  } else if (customKind === 'populated') {
+  } else if (customKind === 'populated' || localDescription) {
     comparison = 'customization-only';
   }
 
@@ -348,6 +361,8 @@ function compareSkill(options) {
     rawCustom: (customKind === 'populated' || customKind === 'empty') && typeof liveMarkdown === 'string'
       ? extractRawCustomContent(liveMarkdown, skillId)
       : undefined,
+    localDescription,
+    rawDescription: localDescription ? readDescriptionEntry(liveMarkdown) : undefined,
     backup: { required: needsResolution },
     exportPath,
     exportCollision: pathExists(exportPath),
@@ -504,6 +519,7 @@ function installOptionsFor(skill, options, scope) {
     adoptChanged: 'replace',
     adoptMalformed: options.malformedMarkers === 'replace' ? 'replace' : undefined,
     preservedCustomRaw: skill.rawCustom !== undefined ? skill.rawCustom : undefined,
+    preservedDescription: skill.rawDescription,
     registry: options.registry || loadHostRegistry(findPackageRoot()),
     afterBackup: options.afterBackup,
     saveState: options.saveState,
@@ -776,6 +792,7 @@ export function formatUpdateHuman(plan) {
     lines.push(`${title}:`);
     for (const skill of skills) {
       lines.push(`  ${skill.title} (${skill.id}) [${skill.comparison}]`);
+      if (skill.localDescription) lines.push('    local description: kept');
       if (skill.changelog) {
         lines.push('    Whole-skill diff:');
         for (const line of skill.changelog.split('\n')) lines.push(`      ${line}`);