Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(npm): stamp the shipped skill with version and content hash, report each agent copy on install, keep an edited copy, and add pinchtab skill status (PIN-286)

Luigi Agosti71ac9ae12ba0
diff --git a/README.md b/README.md
index f6b54d53..e0d0ccad 100644
--- a/README.md
+++ b/README.md
@@ -211,6 +211,18 @@ brew install pinchtab/tap/pinchtab
npm install -g pinchtab
```
+### Agent skill
+
+The npm package ships the `pinchtab` agent skill and copies it into every agent home it detects (`~/.claude/skills`, `~/.cursor/skills`, `~/.windsurf/skills`, `~/.codex/skills`, OpenClaw) on install and upgrade, printing what it wrote. The shipped copy carries the release version and a content hash in its frontmatter, so a stale or hand-edited copy is detectable without a source checkout:
+
+```bash
+pinchtab skill status # each detected copy vs the bundled skill; exit 1 if any is stale
+pinchtab skill update # install or refresh; an edited copy is kept and reported
+pinchtab skill update --force # replace an edited copy
+```
+
+Inside a checkout, `scripts/install-skills.sh` symlinks the repo skills instead so edits are live; the sync never writes through a symlink.
+
### Platform Support
PinchTab's primary tested operator workflow is local macOS and Linux.
diff --git a/internal/mcp/skill_click_contract_test.go b/internal/mcp/skill_click_contract_test.go
index d3066688..f7a57451 100644
--- a/internal/mcp/skill_click_contract_test.go
+++ b/internal/mcp/skill_click_contract_test.go
@@ -16,6 +16,9 @@ const clickDocPath = "docs/reference/click.md"
// release because only the docs were ever listed in a contract-changing card's
// footprint. This guard is the answer to that: the skills are checked AGAINST the
// docs, so the next contract change reds here instead of shipping stale guidance.
+// It reads the working tree, so it proves the shipped source and nothing about a
+// copy installed in an agent home; that half is covered by the version stamp the
+// npm package writes at staging and by `pinchtab skill status` (npm/scripts/sync-skills.js).
var clickContractSkills = []string{"skills/pinchtab/SKILL.md", "skills/pinchtab-mcp/SKILL.md"}
// clickContractBanned are statements the contract no longer produces. An agent
diff --git a/npm/README.md b/npm/README.md
index b541e126..d50fe0e8 100644
--- a/npm/README.md
+++ b/npm/README.md
@@ -155,6 +155,10 @@ pinchtab --version
pinchtab --help
```
+### Agent skill
+
+The package bundles the `pinchtab` agent skill, stamped with the release version and a content hash, and syncs it into detected agent homes on install and upgrade, printing what it wrote. `pinchtab skill status` reports each copy against the bundled one (exit 1 if any is stale) and `pinchtab skill update` refreshes them; a copy you edited is kept unless you pass `--force`.
+
### Shell Completion
After installing the CLI globally, you can generate shell completions:
diff --git a/npm/bin/pinchtab b/npm/bin/pinchtab
index 39ab7565..79cbe99a 100755
--- a/npm/bin/pinchtab
+++ b/npm/bin/pinchtab
@@ -25,58 +25,33 @@ function getBinaryPath() {
return platform.resolveManagedBinaryPath(__dirname);
}
-// Handle `pinchtab skill update` at the Node.js level (no Go binary needed)
+// `pinchtab skill ...` is answered at the Node.js level: the skill ships in the
+// npm package, not in the Go binary.
const args = process.argv.slice(2);
-if (args[0] === 'skill' && (args[1] === 'update' || args[1] === 'sync')) {
+if (args[0] === 'skill' && ['update', 'sync', 'status', 'list'].includes(args[1])) {
+ const check = args[1] === 'status' || args[1] === 'list';
try {
- const { syncSkills } = require('../scripts/sync-skills');
- console.log('Syncing Pinchtab skill files...\n');
- const { updated, skipped } = syncSkills({ verbose: true });
-
- if (updated.length > 0) {
- console.log(`\n✓ Updated ${updated.length} skill director${updated.length === 1 ? 'y' : 'ies'}`);
- } else {
- console.log('\nNo agent skill directories found to update.');
- console.log('Skill directories are synced only where agents are already installed.');
- }
-
- if (skipped.length > 0) {
- console.log(`⚠ Skipped ${skipped.length} (permission errors)`);
- }
- } catch (err) {
- console.error(`Failed to sync skills: ${err.message}`);
- process.exit(1);
- }
- process.exit(0);
-}
-
-if (args[0] === 'skill' && args[1] === 'list') {
- try {
- const { getTargetSkillDirs, getBundledSkillsDir } = require('../scripts/sync-skills');
- const bundled = getBundledSkillsDir();
- console.log(`Bundled skills: ${fs.existsSync(bundled) ? bundled : '(not found)'}`);
- console.log('\nDetected agent skill directories:');
- const targets = getTargetSkillDirs();
- if (targets.length === 0) {
- console.log(' (none found)');
- } else {
- targets.forEach((t) => {
- const exists = fs.existsSync(t);
- console.log(` ${exists ? '●' : '○'} ${t}${exists ? '' : ' (will be created on sync)'}`);
- });
- }
+ const { syncSkills, formatReport, isOutOfDate } = require('../scripts/sync-skills');
+ const outcome = syncSkills({ check, force: args.includes('--force') });
+ console.log(formatReport(outcome).join('\n'));
+ const failed = outcome.results.some((r) => r.action === 'failed');
+ const outOfDate = check && outcome.results.some(isOutOfDate);
+ process.exit(failed || outOfDate ? 1 : 0);
} catch (err) {
- console.error(`Failed to list skills: ${err.message}`);
+ console.error(`Failed to ${check ? 'check' : 'sync'} skills: ${err.message}`);
process.exit(1);
}
- process.exit(0);
}
if (args[0] === 'skill') {
console.log('Usage: pinchtab skill <command>\n');
console.log('Commands:');
- console.log(' update Sync bundled skill files to agent directories');
- console.log(' list Show detected agent skill directories');
+ console.log(
+ ' status Report each detected agent copy against the bundled skill (exit 1 if any is stale)'
+ );
+ console.log(
+ ' update [--force] Install or refresh the bundled skill in detected agent homes; --force replaces an edited copy'
+ );
process.exit(0);
}
diff --git a/npm/scripts/stage-skills.js b/npm/scripts/stage-skills.js
index 38aedad9..8a3cfdee 100644
--- a/npm/scripts/stage-skills.js
+++ b/npm/scripts/stage-skills.js
@@ -2,6 +2,7 @@
const fs = require('fs');
const path = require('path');
+const { stampSkill } = require('./sync-skills');
const SKILL_NAME = 'pinchtab';
const sourceDir = path.join(__dirname, '..', '..', 'skills', SKILL_NAME);
@@ -31,11 +32,14 @@ function stageSkills() {
fs.rmSync(targetDir, { recursive: true, force: true });
copyDirSync(sourceDir, targetDir);
+ return stampSkill(targetDir, require('../package.json').version);
}
if (require.main === module) {
- stageSkills();
- console.log(`Staged ${SKILL_NAME} skill into npm package`);
+ const stamp = stageSkills();
+ console.log(
+ `Staged ${SKILL_NAME} skill ${stamp.version} (${stamp.contentHash}) into npm package`
+ );
}
module.exports = { stageSkills };
diff --git a/npm/scripts/sync-skills.js b/npm/scripts/sync-skills.js
index a573f684..befeeb39 100644
--- a/npm/scripts/sync-skills.js
+++ b/npm/scripts/sync-skills.js
@@ -1,74 +1,143 @@
#!/usr/bin/env node
/**
- * Syncs bundled skill files to detected agent skill directories.
- * Only updates directories that already exist (doesn't create new ones).
+ * The USER path for the pinchtab agent skill: copies the skill bundled in the npm
+ * package into every detected agent home, and reports whether each copy matches
+ * the bundled one. Runs on npm install/update (postinstall) and on
+ * `pinchtab skill update`; `pinchtab skill status` reports without writing.
*
- * Used by:
- * - postinstall (automatic on npm install/update)
- * - `pinchtab skill update` (manual trigger)
+ * In a source checkout use scripts/install-skills.sh instead: it symlinks the
+ * repo skills so edits are reflected immediately. A symlinked target is never
+ * written to here.
*/
+const crypto = require('crypto');
const fs = require('fs');
-const path = require('path');
const os = require('os');
+const path = require('path');
const SKILL_NAME = 'pinchtab';
+const DEV_VERSION = 'dev';
+
+const stampBlock = /^ {2}pinchtab:\n {4}version: .*\n {4}contentHash: .*\n/m;
+const stampFields = /^ {2}pinchtab:\n {4}version: (.*)\n {4}contentHash: (.*)\n/m;
-/**
- * Returns the path to the bundled skills directory inside the npm package.
- */
function getBundledSkillsDir() {
const packagedDir = path.join(__dirname, '..', 'skills', SKILL_NAME);
if (fs.existsSync(packagedDir)) {
return packagedDir;
}
-
- // In a source checkout, fall back to the repo-root skill so local development
- // does not depend on prepack having staged npm/skills first.
return path.join(__dirname, '..', '..', 'skills', SKILL_NAME);
}
-/**
- * Returns candidate agent skill directories to sync to.
- * Only returns paths whose parent directory already exists.
- */
function getTargetSkillDirs() {
const home = os.homedir();
-
const candidates = [
- // Claude Code / Claude Desktop
path.join(home, '.claude', 'skills', SKILL_NAME),
- // OpenClaw
path.join(home, '.openclaw', 'workspace', '.agents', 'skills', SKILL_NAME),
- // Cursor
path.join(home, '.cursor', 'skills', SKILL_NAME),
- // Windsurf
path.join(home, '.windsurf', 'skills', SKILL_NAME),
- // Codex
path.join(home, '.codex', 'skills', SKILL_NAME),
];
+ return candidates.filter((dir) => fs.existsSync(path.dirname(dir)));
+}
- return candidates.filter((dir) => {
- // Check if the parent skills directory exists
- const parentDir = path.dirname(dir);
- return fs.existsSync(parentDir);
- });
+function listFiles(dir, prefix = '') {
+ const names = [];
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name === '.DS_Store') {
+ continue;
+ }
+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) {
+ names.push(...listFiles(path.join(dir, entry.name), rel));
+ } else {
+ names.push(rel);
+ }
+ }
+ return names.sort();
}
-/**
- * Recursively copies a directory.
- */
-function copyDirSync(src, dest) {
- if (!fs.existsSync(dest)) {
- fs.mkdirSync(dest, { recursive: true });
+function stripStamp(skillMd) {
+ return skillMd.replace(stampBlock, '').replace(/^metadata:\n(?=\S)/m, '');
+}
+
+function readStamp(skillDir) {
+ const skillPath = path.join(skillDir, 'SKILL.md');
+ if (!fs.existsSync(skillPath)) {
+ return null;
+ }
+ const match = stampFields.exec(fs.readFileSync(skillPath, 'utf8'));
+ if (!match) {
+ return null;
+ }
+ return { version: match[1].trim(), contentHash: match[2].trim() };
+}
+
+function contentHash(skillDir) {
+ const hash = crypto.createHash('sha256');
+ for (const rel of listFiles(skillDir)) {
+ hash.update(rel);
+ hash.update('\0');
+ const body = fs.readFileSync(path.join(skillDir, rel));
+ hash.update(rel === 'SKILL.md' ? stripStamp(body.toString('utf8')) : body);
+ hash.update('\0');
+ }
+ return `sha256:${hash.digest('hex')}`;
+}
+
+function stampSkill(skillDir, version) {
+ const skillPath = path.join(skillDir, 'SKILL.md');
+ const stamp = { version, contentHash: contentHash(skillDir) };
+ const block = ` pinchtab:\n version: ${stamp.version}\n contentHash: ${stamp.contentHash}\n`;
+ let body = stripStamp(fs.readFileSync(skillPath, 'utf8'));
+ if (/^metadata:\n/m.test(body)) {
+ body = body.replace(/^metadata:\n/m, `metadata:\n${block}`);
+ } else {
+ body = body.replace(/^---\n([\s\S]*?)^---\n/m, `---\n$1metadata:\n${block}---\n`);
+ }
+ fs.writeFileSync(skillPath, body);
+ return stamp;
+}
+
+function describeBundle(bundledDir) {
+ const stamp = readStamp(bundledDir);
+ return {
+ dir: bundledDir,
+ version: stamp ? stamp.version : DEV_VERSION,
+ contentHash: stamp ? stamp.contentHash : contentHash(bundledDir),
+ };
+}
+
+function inspectTarget(target, bundle) {
+ let stat;
+ try {
+ stat = fs.lstatSync(target);
+ } catch {
+ return { target, state: 'absent', installed: null };
+ }
+ if (stat.isSymbolicLink()) {
+ return { target, state: 'symlink', installed: null };
+ }
+ const installed = readStamp(target);
+ const actual = contentHash(target);
+ if (actual === bundle.contentHash) {
+ return { target, state: 'current', installed };
+ }
+ if (!installed) {
+ return { target, state: 'unversioned', installed };
+ }
+ if (actual !== installed.contentHash) {
+ return { target, state: 'edited', installed };
}
+ return { target, state: 'stale', installed };
+}
- const entries = fs.readdirSync(src, { withFileTypes: true });
- for (const entry of entries) {
+function copyDirSync(src, dest) {
+ fs.mkdirSync(dest, { recursive: true });
+ for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
const srcPath = path.join(src, entry.name);
const destPath = path.join(dest, entry.name);
-
if (entry.isDirectory()) {
copyDirSync(srcPath, destPath);
} else {
@@ -77,69 +146,116 @@ function copyDirSync(src, dest) {
}
}
-/**
- * Syncs bundled skills to all detected agent directories.
- * @param {object} options
- * @param {boolean} options.verbose - Print detailed output
- * @returns {{ updated: string[], skipped: string[] }}
- */
-function syncSkills({ verbose = false } = {}) {
- const bundledDir = getBundledSkillsDir();
- const updated = [];
- const skipped = [];
-
- if (!fs.existsSync(bundledDir)) {
- if (verbose) {
- console.error(`⚠ Bundled skills not found at ${bundledDir}`);
- }
- return { updated, skipped };
+function replaceSkill(bundle, target) {
+ fs.rmSync(target, { recursive: true, force: true });
+ copyDirSync(bundle.dir, target);
+ if (!readStamp(target)) {
+ stampSkill(target, bundle.version);
}
+}
- const targets = getTargetSkillDirs();
+const writesFor = {
+ absent: () => 'installed',
+ stale: () => 'updated',
+ edited: (force) => (force ? 'updated' : 'kept'),
+ unversioned: (force) => (force ? 'updated' : 'kept'),
+ current: () => 'unchanged',
+ symlink: () => 'unchanged',
+};
- if (targets.length === 0) {
- if (verbose) {
- console.log('No agent skill directories detected. Nothing to sync.');
- }
- return { updated, skipped };
+function syncSkills({ force = false, check = false, bundledDir = getBundledSkillsDir() } = {}) {
+ if (!fs.existsSync(bundledDir)) {
+ throw new Error(`bundled skill not found at ${bundledDir}`);
}
-
- for (const target of targets) {
- try {
- copyDirSync(bundledDir, target);
- updated.push(target);
- if (verbose) {
- console.log(` ✓ ${target}`);
- }
- } catch (err) {
- skipped.push(target);
- if (verbose) {
- console.warn(` ✗ ${target}: ${err.message}`);
+ const bundle = describeBundle(bundledDir);
+ const results = getTargetSkillDirs().map((target) => {
+ const found = inspectTarget(target, bundle);
+ const action = check ? 'checked' : writesFor[found.state](force);
+ if (action === 'installed' || action === 'updated') {
+ try {
+ replaceSkill(bundle, target);
+ } catch (err) {
+ return { ...found, action: 'failed', error: err.message };
}
}
- }
+ return { ...found, action };
+ });
+ return { bundle, results };
+}
- return { updated, skipped };
+function isOutOfDate(result) {
+ return result.state === 'stale' || result.state === 'edited' || result.state === 'unversioned';
}
-// If run directly (not required as module)
-if (require.main === module) {
- const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
- console.log('Syncing Pinchtab skill files...\n');
- const { updated, skipped } = syncSkills({ verbose });
+function shortHash(contentHash) {
+ return contentHash.replace(/^sha256:/, '').slice(0, 12);
+}
- if (updated.length > 0) {
- console.log(
- `\n✓ Updated ${updated.length} skill director${updated.length === 1 ? 'y' : 'ies'}`
- );
- } else {
- console.log('\nNo agent skill directories found to update.');
- console.log('Skill directories are synced only where agents are already installed.');
+function describeResult(result, bundle) {
+ const from = result.installed ? result.installed.version : 'unversioned';
+ switch (result.action) {
+ case 'installed':
+ return `installed ${bundle.version}`;
+ case 'updated':
+ return `updated ${from} -> ${bundle.version}`;
+ case 'failed':
+ return `failed: ${result.error}`;
+ default:
+ break;
}
+ switch (result.state) {
+ case 'current':
+ return `current (${bundle.version})`;
+ case 'symlink':
+ return 'symlink to a checkout; left alone (scripts/install-skills.sh manages it)';
+ case 'stale':
+ return `stale ${from}; run: pinchtab skill update`;
+ case 'edited':
+ return `edited locally since ${from}; kept. Replace it with: pinchtab skill update --force`;
+ case 'unversioned':
+ return 'unversioned copy that differs from the bundled skill; kept. Replace it with: pinchtab skill update --force';
+ case 'absent':
+ return `not installed; run: pinchtab skill update`;
+ default:
+ return result.state;
+ }
+}
- if (skipped.length > 0) {
- console.log(`⚠ Skipped ${skipped.length} (permission errors)`);
+function formatReport({ bundle, results }) {
+ const lines = [`pinchtab skill ${bundle.version} (${shortHash(bundle.contentHash)})`];
+ if (results.length === 0) {
+ lines.push(
+ ' no agent skill directories detected; the skill is synced only where an agent is already installed'
+ );
+ return lines;
+ }
+ for (const result of results) {
+ lines.push(` ${result.target}: ${describeResult(result, bundle)}`);
}
+ return lines;
+}
+
+if (require.main === module) {
+ const argv = process.argv.slice(2);
+ const outcome = syncSkills({
+ force: argv.includes('--force'),
+ check: argv.includes('--check'),
+ });
+ console.log(formatReport(outcome).join('\n'));
+ const failed = outcome.results.some((r) => r.action === 'failed');
+ const outOfDate = outcome.results.some(isOutOfDate);
+ process.exit(failed || (argv.includes('--check') && outOfDate) ? 1 : 0);
}
-module.exports = { syncSkills, getTargetSkillDirs, getBundledSkillsDir };
+module.exports = {
+ SKILL_NAME,
+ syncSkills,
+ formatReport,
+ isOutOfDate,
+ getTargetSkillDirs,
+ getBundledSkillsDir,
+ contentHash,
+ stampSkill,
+ readStamp,
+ stripStamp,
+};
diff --git a/npm/src/postinstall.ts b/npm/src/postinstall.ts
index fe1db5fd..7020f929 100644
--- a/npm/src/postinstall.ts
+++ b/npm/src/postinstall.ts
@@ -3,11 +3,13 @@ import * as path from 'path';
import { ensureBinary } from './download';
import { getCheckoutBinaryPath } from './platform';
-interface SkillSyncResult {
- updated: string[];
+interface SkillSync {
+ syncSkills: (opts: { force?: boolean; check?: boolean }) => unknown;
+ formatReport: (outcome: unknown) => string[];
}
-// syncBundledSkills mirrors bundled skill files into detected agent directories.
+// syncBundledSkills is the npm user path for the agent skill: it writes into the
+// user's agent homes as an install side effect, so it always prints what it did.
// Non-fatal: a sync failure must never block the install. sync-skills is a
// CommonJS script shipped alongside the package, loaded relative to the compiled
// location (dist/src -> ../../scripts).
@@ -15,17 +17,11 @@ function syncBundledSkills(): void {
try {
const syncSkillsPath = path.join(__dirname, '..', '..', 'scripts', 'sync-skills');
// eslint-disable-next-line @typescript-eslint/no-require-imports
- const { syncSkills } = require(syncSkillsPath) as {
- syncSkills: (opts: { verbose: boolean }) => SkillSyncResult;
- };
- const { updated } = syncSkills({ verbose: false });
- if (updated.length > 0) {
- console.log(
- `✓ Synced skill files to ${updated.length} agent director${updated.length === 1 ? 'y' : 'ies'}`
- );
- }
- } catch (_err) {
- // Non-fatal: skill sync failure shouldn't block install
+ const { syncSkills, formatReport } = require(syncSkillsPath) as SkillSync;
+ console.log(formatReport(syncSkills({})).join('\n'));
+ } catch (err) {
+ console.warn(`⚠ Skill sync skipped: ${err instanceof Error ? err.message : String(err)}`);
+ console.warn(' Retry with: pinchtab skill update');
}
}
diff --git a/npm/tests/skill-distribution.test.ts b/npm/tests/skill-distribution.test.ts
new file mode 100644
index 00000000..83236528
--- /dev/null
+++ b/npm/tests/skill-distribution.test.ts
@@ -0,0 +1,235 @@
+/**
+ * Skill distribution: the npm user path (scripts/sync-skills.js).
+ *
+ * The skill an agent loads is a copy in an agent home, so a stale copy teaches a
+ * contract the server no longer produces. These tests drive the sync against a
+ * fake HOME and a fake bundle and pin: the stamp, the hash that ignores the
+ * stamp, install / refresh / keep-an-edited-copy / leave-a-symlink, and that
+ * status mode writes nothing.
+ */
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import * as assert from 'node:assert';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const sync = require('../../scripts/sync-skills') as {
+ syncSkills: (opts: { force?: boolean; check?: boolean; bundledDir: string }) => Outcome;
+ formatReport: (outcome: Outcome) => string[];
+ isOutOfDate: (result: Result) => boolean;
+ contentHash: (dir: string) => string;
+ stampSkill: (dir: string, version: string) => { version: string; contentHash: string };
+ readStamp: (dir: string) => { version: string; contentHash: string } | null;
+};
+
+interface Result {
+ target: string;
+ state: string;
+ action: string;
+ installed: { version: string; contentHash: string } | null;
+}
+interface Outcome {
+ bundle: { dir: string; version: string; contentHash: string };
+ results: Result[];
+}
+
+const skillMd = (body: string) =>
+ `---\nname: pinchtab\ndescription: "browser control"\nmetadata:\n openclaw:\n requires:\n bins:\n - pinchtab\n---\n\n${body}\n`;
+
+let root: string;
+let savedHome: string | undefined;
+
+function writeBundle(name: string, body: string, version: string): string {
+ const dir = path.join(root, name);
+ fs.mkdirSync(path.join(dir, 'references'), { recursive: true });
+ fs.writeFileSync(path.join(dir, 'SKILL.md'), skillMd(body));
+ fs.writeFileSync(path.join(dir, 'references', 'commands.md'), `# commands\n${body}\n`);
+ sync.stampSkill(dir, version);
+ return dir;
+}
+
+function claudeSkillDir(): string {
+ const skills = path.join(root, 'home', '.claude', 'skills');
+ fs.mkdirSync(skills, { recursive: true });
+ return path.join(skills, 'pinchtab');
+}
+
+function only(outcome: Outcome): Result {
+ assert.strictEqual(outcome.results.length, 1, JSON.stringify(outcome.results));
+ return outcome.results[0];
+}
+
+beforeEach(() => {
+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'pinchtab-skill-sync-'));
+ savedHome = process.env.HOME;
+ process.env.HOME = path.join(root, 'home');
+ fs.mkdirSync(process.env.HOME, { recursive: true });
+});
+
+afterEach(() => {
+ process.env.HOME = savedHome;
+ fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('the version stamp', () => {
+ test('lands under metadata and hashes the content it is not part of', () => {
+ const dir = writeBundle('bundle', 'click navigates: OK navigated', '1.2.3');
+ const stamped = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
+ assert.match(
+ stamped,
+ /^metadata:\n {2}pinchtab:\n {4}version: 1\.2\.3\n {4}contentHash: sha256:[0-9a-f]{64}\n {2}openclaw:/m
+ );
+ assert.deepStrictEqual(sync.readStamp(dir), {
+ version: '1.2.3',
+ contentHash: sync.contentHash(dir),
+ });
+
+ const restamped = sync.stampSkill(dir, '9.9.9');
+ assert.strictEqual(
+ restamped.contentHash,
+ sync.contentHash(dir),
+ 'restamping must not move the hash'
+ );
+ assert.strictEqual(sync.readStamp(dir)?.version, '9.9.9');
+ });
+
+ test('is added to a frontmatter with no metadata block', () => {
+ const dir = path.join(root, 'bare');
+ fs.mkdirSync(dir);
+ fs.writeFileSync(path.join(dir, 'SKILL.md'), '---\nname: pinchtab\n---\n\nbody\n');
+ sync.stampSkill(dir, '0.1.0');
+ assert.deepStrictEqual(sync.readStamp(dir), {
+ version: '0.1.0',
+ contentHash: sync.contentHash(dir),
+ });
+ assert.match(
+ fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8'),
+ /^---\nname: pinchtab\nmetadata:\n {2}pinchtab:\n/
+ );
+ });
+
+ test('changes with any file in the tree, not just SKILL.md', () => {
+ const dir = writeBundle('bundle', 'v1', '1.0.0');
+ const before = sync.contentHash(dir);
+ fs.appendFileSync(path.join(dir, 'references', 'commands.md'), 'nav --timeout <seconds>\n');
+ assert.notStrictEqual(sync.contentHash(dir), before);
+ });
+});
+
+describe('pinchtab skill update', () => {
+ test('detects nothing when no agent home exists', () => {
+ const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
+ const outcome = sync.syncSkills({ bundledDir });
+ assert.deepStrictEqual(outcome.results, []);
+ assert.match(sync.formatReport(outcome).join('\n'), /no agent skill directories detected/);
+ });
+
+ test('installs into a detected home and the copy carries the bundled stamp', () => {
+ const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
+ const target = claudeSkillDir();
+ const result = only(sync.syncSkills({ bundledDir }));
+ assert.strictEqual(result.action, 'installed');
+ assert.deepStrictEqual(sync.readStamp(target), sync.readStamp(bundledDir));
+ assert.strictEqual(
+ fs.readFileSync(path.join(target, 'references', 'commands.md'), 'utf8'),
+ '# commands\nv1\n'
+ );
+ assert.strictEqual(only(sync.syncSkills({ bundledDir })).action, 'unchanged');
+ });
+
+ test('refreshes an untouched copy of an older bundle and drops files the new bundle removed', () => {
+ const target = claudeSkillDir();
+ only(sync.syncSkills({ bundledDir: writeBundle('old', 'treat 409 as success', '0.9.0') }));
+ fs.writeFileSync(path.join(target, 'references', 'gone.md'), 'obsolete\n');
+ const stale = sync.stampSkill(target, '0.9.0');
+ assert.strictEqual(sync.readStamp(target)?.contentHash, stale.contentHash);
+
+ const bundledDir = writeBundle('new', 'OK navigated; JSON adds refsStale', '1.0.0');
+ const result = only(sync.syncSkills({ bundledDir }));
+ assert.strictEqual(result.state, 'stale');
+ assert.strictEqual(result.action, 'updated');
+ assert.strictEqual(result.installed?.version, '0.9.0');
+ assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /refsStale/);
+ assert.ok(!fs.existsSync(path.join(target, 'references', 'gone.md')));
+ assert.match(
+ sync.formatReport(sync.syncSkills({ bundledDir, check: true })).join('\n'),
+ /current \(1\.0\.0\)/
+ );
+ });
+
+ test('keeps a copy the user edited, says so, and replaces it only under --force', () => {
+ const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
+ const target = claudeSkillDir();
+ only(sync.syncSkills({ bundledDir }));
+ fs.appendFileSync(path.join(target, 'SKILL.md'), '\nMy own note.\n');
+ const newer = writeBundle('newer', 'v2', '1.1.0');
+
+ const keptOutcome = sync.syncSkills({ bundledDir: newer });
+ const kept = only(keptOutcome);
+ assert.strictEqual(kept.state, 'edited');
+ assert.strictEqual(kept.action, 'kept');
+ assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /My own note/);
+ assert.match(
+ sync.formatReport(keptOutcome).join('\n'),
+ /edited locally since 1\.0\.0.*--force/
+ );
+
+ const forced = only(sync.syncSkills({ bundledDir: newer, force: true }));
+ assert.strictEqual(forced.action, 'updated');
+ assert.doesNotMatch(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /My own note/);
+ assert.strictEqual(sync.readStamp(target)?.version, '1.1.0');
+ });
+
+ test('keeps an unversioned copy that differs, since it cannot tell edited from stale', () => {
+ const target = claudeSkillDir();
+ fs.mkdirSync(target, { recursive: true });
+ fs.writeFileSync(path.join(target, 'SKILL.md'), skillMd('treat 409 as success'));
+ const result = only(sync.syncSkills({ bundledDir: writeBundle('bundle', 'v1', '1.0.0') }));
+ assert.strictEqual(result.state, 'unversioned');
+ assert.strictEqual(result.action, 'kept');
+ assert.ok(sync.isOutOfDate(result));
+ assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /409/);
+ });
+
+ test('never writes through a symlink, which is the developer path', () => {
+ const checkout = writeBundle('checkout', 'edited live', '1.0.0');
+ const target = claudeSkillDir();
+ fs.symlinkSync(checkout, target);
+ const result = only(
+ sync.syncSkills({ bundledDir: writeBundle('bundle', 'v2', '2.0.0'), force: true })
+ );
+ assert.strictEqual(result.state, 'symlink');
+ assert.strictEqual(result.action, 'unchanged');
+ assert.ok(fs.lstatSync(target).isSymbolicLink());
+ assert.match(fs.readFileSync(path.join(checkout, 'SKILL.md'), 'utf8'), /edited live/);
+ });
+});
+
+describe('pinchtab skill status', () => {
+ test('reports a stale copy without touching it', () => {
+ const target = claudeSkillDir();
+ only(sync.syncSkills({ bundledDir: writeBundle('old', 'v1', '0.9.0') }));
+ const before = fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8');
+ const outcome = sync.syncSkills({ bundledDir: writeBundle('new', 'v2', '1.0.0'), check: true });
+ const result = only(outcome);
+ assert.strictEqual(result.state, 'stale');
+ assert.strictEqual(result.action, 'checked');
+ assert.ok(sync.isOutOfDate(result));
+ assert.strictEqual(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), before);
+ assert.match(
+ sync.formatReport(outcome).join('\n'),
+ /stale 0\.9\.0; run: pinchtab skill update/
+ );
+ });
+
+ test('a bundle without a stamp reads as the dev version', () => {
+ const dir = path.join(root, 'src');
+ fs.mkdirSync(dir);
+ fs.writeFileSync(path.join(dir, 'SKILL.md'), skillMd('from a checkout'));
+ const outcome = sync.syncSkills({ bundledDir: dir, check: true });
+ assert.strictEqual(outcome.bundle.version, 'dev');
+ assert.strictEqual(outcome.bundle.contentHash, sync.contentHash(dir));
+ });
+});
diff --git a/scripts/README.md b/scripts/README.md
index 2143bdde..8fa30776 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -39,7 +39,7 @@ Development and CI scripts for PinchTab.
|--------|---------|
| `doctor.sh` | Verify & setup dev environment (interactive — prompts before installing) |
| `install-hooks.sh` | Install git pre-commit hook |
-| `install-skills.sh` | Symlink repo skills into `./.claude/skills` by default; set `CLAUDE_SKILLS_DIR=~/.claude/skills` for a global install |
+| `install-skills.sh` | Developer path for the agent skills: symlink repo skills into `./.claude/skills` by default; set `CLAUDE_SKILLS_DIR=~/.claude/skills` for a global install. Users of an installed binary use `pinchtab skill update` (npm package) instead |
## Testing
diff --git a/scripts/install-skills.sh b/scripts/install-skills.sh
index 7afd3c55..29754a2b 100755
--- a/scripts/install-skills.sh
+++ b/scripts/install-skills.sh
@@ -1,8 +1,13 @@
#!/usr/bin/env bash
-# Symlink every skill under ./skills into ./.claude/skills so Claude Code
-# picks them up as repo-local skills (loaded only when CWD is inside this
-# repo). Editing files under ./skills/<name>/ is reflected immediately
-# because we use symlinks.
+# The DEVELOPER path for the skills: symlinks every skill under ./skills into
+# ./.claude/skills so Claude Code picks them up as repo-local skills (loaded
+# only when CWD is inside this repo), and edits under ./skills/<name>/ are
+# reflected immediately. It needs a checkout.
+#
+# Users of an installed binary have no checkout: the npm package ships a copy
+# of the pinchtab skill and `pinchtab skill update` / `pinchtab skill status`
+# (npm/scripts/sync-skills.js) manage it. That sync never writes through a
+# symlink, so the two paths do not fight over one directory.
#
# Override the target directory with CLAUDE_SKILLS_DIR=<path> if you want
# to install into a different Claude home (e.g. ~/.claude/skills for a