agent-skills-doctor 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +1 -0
  2. package/cli.mjs +91 -13
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -93,6 +93,7 @@ Options:
93
93
  --no-global skip user-level global roots
94
94
  --no-project skip project-level roots
95
95
  --root <dir> extra root to scan (repeatable)
96
+ --ignore <name> ignore drift for a skill (repeatable)
96
97
  -h, --help show this help text
97
98
  ```
98
99
 
package/cli.mjs CHANGED
@@ -91,7 +91,52 @@ function expand(path, project) {
91
91
  return isAbsolute(path) ? path : join(project, path);
92
92
  }
93
93
 
94
- const hash = (text) => createHash('sha256').update(text.trimEnd()).digest('hex');
94
+ const IGNORED_DIRS = new Set(['.git', 'node_modules']);
95
+
96
+ // Deterministic hash + latest mtime across the whole skill directory so drift
97
+ // catches changes in companion scripts/references as well as SKILL.md.
98
+ function hashSkillDir(rootDir) {
99
+ const hasher = createHash('sha256');
100
+ const visited = new Set();
101
+ let latestMtime = 0;
102
+
103
+ function walkDir(dir, prefix) {
104
+ const real = safeRealpath(dir);
105
+ if (visited.has(real)) return;
106
+ visited.add(real);
107
+
108
+ let entries;
109
+ try {
110
+ entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
111
+ } catch {
112
+ return;
113
+ }
114
+ for (const entry of entries) {
115
+ if (IGNORED_DIRS.has(entry.name) || entry.name === '.DS_Store') continue;
116
+ const full = join(dir, entry.name);
117
+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
118
+ let stats;
119
+ try {
120
+ stats = statSync(full);
121
+ } catch {
122
+ continue;
123
+ }
124
+ if (stats.isDirectory()) {
125
+ walkDir(full, rel);
126
+ } else if (stats.isFile()) {
127
+ hasher.update(`${rel}\0`);
128
+ try {
129
+ const buf = readFileSync(full);
130
+ hasher.update(buf);
131
+ if (stats.mtimeMs > latestMtime) latestMtime = stats.mtimeMs;
132
+ } catch {}
133
+ }
134
+ }
135
+ }
136
+
137
+ walkDir(rootDir, '');
138
+ return { hash: hasher.digest('hex'), mtimeMs: latestMtime };
139
+ }
95
140
 
96
141
  // Only `name` and `description` are read; a full YAML parser is not worth it
97
142
  // here. Values are unquoted so `name: "foo"` and `name: foo` behave the same.
@@ -201,13 +246,15 @@ function loadSkill(dir, file) {
201
246
  }
202
247
  const chars = name.trim().length + description.trim().length;
203
248
  const payloadChars = text.length;
249
+ const dirDigest = hashSkillDir(dir);
204
250
  return {
205
251
  name: name.trim() || dirName,
206
252
  declaredName: name.trim(),
207
253
  dir,
208
254
  path: join(dir, file),
209
255
  description: description.trim(),
210
- hash: hash(text),
256
+ hash: dirDigest.hash,
257
+ mtimeMs: dirDigest.mtimeMs,
211
258
  chars,
212
259
  tokens: Math.ceil(chars / 4),
213
260
  payloadChars,
@@ -302,6 +349,7 @@ export function findDuplicates(roots) {
302
349
  path: skill.path || skill.dir,
303
350
  dir: skill.dir,
304
351
  hash: skill.hash,
352
+ mtimeMs: skill.mtimeMs || 0,
305
353
  real: safeRealpath(skill.dir),
306
354
  linked: skill.linked,
307
355
  });
@@ -359,11 +407,15 @@ export function cmdCatalog(project, { includeUser = true } = {}) {
359
407
  const shadowed = [];
360
408
  for (const root of roots) {
361
409
  for (const skill of root.skills) {
410
+ const real = safeRealpath(skill.dir);
362
411
  if (winners.has(skill.name)) {
363
- shadowed.push({ name: skill.name, kept: winners.get(skill.name).root, dropped: root.rel });
412
+ const winner = winners.get(skill.name);
413
+ if (winner.real !== real) {
414
+ shadowed.push({ name: skill.name, kept: winner.root, dropped: root.rel });
415
+ }
364
416
  continue;
365
417
  }
366
- winners.set(skill.name, { skill, root: root.rel });
418
+ winners.set(skill.name, { skill, root: root.rel, real });
367
419
  }
368
420
  }
369
421
  const entries = [...winners.values()];
@@ -442,7 +494,10 @@ export function audit(options = {}) {
442
494
  );
443
495
  const scanned = roots.map((root) => scanRoot(root, project));
444
496
  const present = scanned.filter((root) => root.exists);
445
- const duplicates = findDuplicates(present);
497
+ const ignored = new Set(options.ignore || []);
498
+ const duplicates = findDuplicates(present).map((d) =>
499
+ ignored.has(d.name) ? { ...d, ignored: true } : d,
500
+ );
446
501
  const cmd = cmdCatalog(project, { includeUser: options.includeGlobal !== false });
447
502
  const invalid = present.flatMap((root) =>
448
503
  root.skills.filter((s) => s.problems.length).map((s) => ({ root: root.rel, dir: s.dir, name: s.name, problems: s.problems })),
@@ -480,20 +535,29 @@ function pct(tokens, window) {
480
535
  return `${((tokens / window) * 100).toFixed(1)}%`;
481
536
  }
482
537
 
538
+ function formatDate(ms) {
539
+ if (!ms) return '';
540
+ return new Date(ms).toISOString().slice(0, 10);
541
+ }
542
+
483
543
  function groupByHash(copies) {
484
544
  const groups = new Map();
485
545
  for (const copy of copies) {
486
- const group = groups.get(copy.hash) || { hash: copy.hash, roots: [] };
487
- groups.set(copy.hash, { hash: copy.hash, roots: [...group.roots, copy.root] });
546
+ const group = groups.get(copy.hash) || { hash: copy.hash, roots: [], mtimeMs: 0 };
547
+ groups.set(copy.hash, {
548
+ hash: copy.hash,
549
+ roots: [...group.roots, copy.root],
550
+ mtimeMs: Math.max(group.mtimeMs, copy.mtimeMs || 0),
551
+ });
488
552
  }
489
- return [...groups.values()].sort((a, b) => b.roots.length - a.roots.length);
553
+ return [...groups.values()].sort((a, b) => b.mtimeMs - a.mtimeMs || b.roots.length - a.roots.length);
490
554
  }
491
555
 
492
556
  function report(result) {
493
557
  const lines = [];
494
558
  const scanned = result.scanned.filter((r) => r.exists);
495
559
  const absent = result.scanned.length - scanned.length;
496
- const drift = result.duplicates.filter((d) => d.status === 'drift');
560
+ const drift = result.duplicates.filter((d) => d.status === 'drift' && !d.ignored);
497
561
  const identical = result.duplicates.filter((d) => d.status === 'identical');
498
562
  const linked = result.duplicates.filter((d) => d.status === 'linked');
499
563
 
@@ -580,8 +644,16 @@ function report(result) {
580
644
  issues.push(`drift: ${drift.length} skill(s) have copies with different content`);
581
645
  for (const d of drift) {
582
646
  issues.push(` ${d.name} (${d.copies.length} copies)`);
583
- for (const group of groupByHash(d.copies)) {
584
- issues.push(` [${group.roots.length}] ${group.roots.join(', ')} (${group.hash.slice(0, 8)})`);
647
+ const groups = groupByHash(d.copies);
648
+ const maxMtime = Math.max(...groups.map((g) => g.mtimeMs));
649
+ const minMtime = Math.min(...groups.map((g) => g.mtimeMs));
650
+ const showNewest = groups.length > 1 && maxMtime - minMtime > 1000;
651
+ for (const group of groups) {
652
+ const meta = [group.hash.slice(0, 8)];
653
+ const date = formatDate(group.mtimeMs);
654
+ if (date) meta.push(date);
655
+ if (showNewest && group.mtimeMs === maxMtime) meta.push('newest');
656
+ issues.push(` [${group.roots.length}] ${group.roots.join(', ')} (${meta.join(', ')})`);
585
657
  }
586
658
  }
587
659
  }
@@ -623,6 +695,7 @@ function help() {
623
695
  ' --no-global skip user-level global roots',
624
696
  ' --no-project skip project-level roots',
625
697
  ' --root <dir> extra root to scan (repeatable)',
698
+ ' --ignore <name> ignore drift for a skill (repeatable)',
626
699
  ' -h, --help show this help text',
627
700
  '',
628
701
  'exit: 0 clean, 1 problems found, 2 usage error',
@@ -630,7 +703,7 @@ function help() {
630
703
  }
631
704
 
632
705
  function parseArgs(argv) {
633
- const options = { extraRoots: [] };
706
+ const options = { extraRoots: [], ignore: [] };
634
707
  for (let i = 0; i < argv.length; i++) {
635
708
  const arg = argv[i];
636
709
  if (arg === '--json') options.json = true;
@@ -648,6 +721,11 @@ function parseArgs(argv) {
648
721
  options.by = val;
649
722
  }
650
723
  else if (arg === '--root') options.extraRoots.push(argv[++i]);
724
+ else if (arg === '--ignore') {
725
+ const val = argv[++i];
726
+ if (!val || val.startsWith('-')) return { error: 'missing value for --ignore' };
727
+ options.ignore.push(val);
728
+ }
651
729
  else if (arg === '--help' || arg === '-h') options.help = true;
652
730
  else return { error: `unknown argument: ${arg}` };
653
731
  }
@@ -671,7 +749,7 @@ function main(argv) {
671
749
  result.invalid.length +
672
750
  result.broken.length +
673
751
  (result.missing?.length || 0) +
674
- result.duplicates.filter((d) => d.status === 'drift').length;
752
+ result.duplicates.filter((d) => d.status === 'drift' && !d.ignored).length;
675
753
  if (result.budget?.exceeded) count++;
676
754
 
677
755
  if (options.json) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-skills-doctor",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "Zero-dependency health check, linter, and token auditor for AI agent skills across Claude Code, OpenCode, Cursor, and 13 other harnesses",
5
5
  "type": "module",
6
6
  "main": "cli.mjs",