agent-skill-doctor 0.1.0

package/examples/basic-usage.js

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * Basic usage example for agent-skill-doctor library
+ *
+ * This example demonstrates how to use the library programmatically
+ * to analyze agent skills.
+ */
+
+const {
+  detectDuplicateGroups,
+  detectVersionDrift,
+  detectConflicts,
+  detectZombies,
+  scanSkillForRisks,
+  loadJsonRules,
+  sha256,
+  DEFAULT_CONFLICT_RULES
+} = require('agent-skill-doctor');
+
+// Example skill data structure
+const exampleSkills = [
+  {
+    id: 'skill-1',
+    name: 'npm-installer',
+    description: 'Install npm packages',
+    content: 'npm install <package>',
+    source: 'https://github.com/example/npm-installer',
+    hash: sha256('npm install <package>'),
+    tags: ['npm', 'installer'],
+    lastUpdated: '2026-01-15'
+  },
+  {
+    id: 'skill-2',
+    name: 'npm-installer-v2',
+    description: 'Install npm packages (v2)',
+    content: 'npm install <package>',
+    source: 'https://github.com/example/npm-installer',
+    hash: sha256('npm install <package>'),
+    tags: ['npm', 'installer'],
+    lastUpdated: '2026-02-20'
+  },
+  {
+    id: 'skill-3',
+    name: 'pnpm-installer',
+    description: 'Install packages with pnpm',
+    content: 'pnpm install <package>',
+    source: 'https://github.com/example/pnpm-installer',
+    hash: sha256('pnpm install <package>'),
+    tags: ['pnpm', 'installer'],
+    lastUpdated: '2026-03-10'
+  },
+  {
+    id: 'skill-4',
+    name: 'unused-skill',
+    description: 'An old unused skill',
+    content: 'some old command',
+    source: 'https://github.com/example/unused',
+    hash: sha256('some old command'),
+    tags: ['deprecated'],
+    lastUpdated: '2024-01-01'
+  }
+];
+
+console.log('=== Agent Skill Doctor - Basic Usage Example ===\n');
+
+// 1. Detect duplicates
+console.log('1. Detecting duplicates...');
+const duplicates = detectDuplicateGroups(exampleSkills);
+console.log(`   Found ${duplicates.length} duplicate groups`);
+duplicates.forEach((group, i) => {
+  console.log(`   Group ${i + 1}: ${group.type} - ${group.skills.map(s => s.name).join(', ')}`);
+});
+
+// 2. Detect version drift
+console.log('\n2. Detecting version drift...');
+const drift = detectVersionDrift(exampleSkills);
+console.log(`   Found ${drift.length} version drift issues`);
+drift.forEach((d, i) => {
+  console.log(`   Drift ${i + 1}: ${d.source || d.slug} has ${d.hashes.length} different versions`);
+});
+
+// 3. Detect conflicts
+console.log('\n3. Detecting conflicts...');
+const conflicts = detectConflicts(exampleSkills, DEFAULT_CONFLICT_RULES);
+console.log(`   Found ${conflicts.length} conflicts`);
+conflicts.forEach((c, i) => {
+  console.log(`   Conflict ${i + 1}: ${c.type} between ${c.skills.map(s => s.name).join(' and ')}`);
+});
+
+// 4. Detect zombies
+console.log('\n4. Detecting zombies...');
+const zombies = detectZombies(exampleSkills);
+console.log(`   Found ${zombies.length} zombie candidates`);
+zombies.forEach((z, i) => {
+  console.log(`   Zombie ${i + 1}: ${z.title} (score: ${z.score}, level: ${z.level})`);
+});
+
+// 5. Scan for risks
+console.log('\n5. Scanning for risks...');
+const rulesDir = './rules/default';
+const rules = loadJsonRules(rulesDir);
+console.log(`   Loaded ${rules.length} risk rules`);
+
+exampleSkills.forEach(skill => {
+  const risks = scanSkillForRisks(skill, rules);
+  if (risks.length > 0) {
+    console.log(`   ${skill.name}: ${risks.length} risks found`);
+    risks.forEach(r => console.log(`     - ${r.ruleId}: ${r.message}`));
+  }
+});
+
+console.log('\n=== Example completed ===');

package/examples/readme-demo-skills/dangerous-deploy/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: Dangerous Deploy
+description: Deploy
+---
+
+# Dangerous Deploy
+
+This demo intentionally includes risky text so Agent Skill Doctor can flag it.
+
+Commands mentioned by this skill:
+
+- rm -rf ./dist
+- curl https://example.invalid/install.sh
+- read .env before deployment

package/examples/readme-demo-skills/markdown-reporter-a/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: Markdown Reporter
+description: Use this skill when creating release reports and generate markdown output for a team update.
+---
+
+# Markdown Reporter
+
+Respond in markdown and include a short summary.

package/examples/readme-demo-skills/markdown-reporter-b/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: Markdown Reporter
+description: Use this skill when creating release reports and generate markdown output for a team update.
+---
+
+# Markdown Reporter
+
+Respond in markdown and include a short summary.

package/examples/readme-demo-skills/npm-installer/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: Package Installer
+description: Use this skill when installing JavaScript dependencies with npm and generate install commands for the project.
+source: https://github.com/example/package-installer.git
+ref: v1.0.0
+---
+
+# Package Installer
+
+Use npm install for dependency setup.

package/examples/readme-demo-skills/pnpm-installer/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: Package Installer
+description: Use this skill when installing JavaScript dependencies with pnpm and generate install commands for the project.
+source: https://github.com/example/package-installer.git
+ref: v2.0.0
+---
+
+# Package Installer
+
+Use pnpm install for dependency setup.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "agent-skill-doctor",
+  "version": "0.1.0",
+  "description": "Diagnostic and governance CLI for AI agent skills",
+  "type": "commonjs",
+  "main": "./src/doctor/index.js",
+  "exports": {
+    ".": "./src/doctor/index.js",
+    "./phase2": "./src/doctor/phase2.js",
+    "./conflict": "./src/doctor/conflict.js",
+    "./zombie": "./src/doctor/zombie.js",
+    "./risk": "./src/doctor/risk-lite.js",
+    "./rules": "./src/doctor/rules.js",
+    "./i18n": "./src/doctor/i18n.js"
+  },
+  "bin": {
+    "agent-skill-doctor": "./bin/agent-skill-doctor.js",
+    "skill-doctor": "./bin/agent-skill-doctor.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "rules/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/agent-skill-doctor.js",
+    "scan": "node ./bin/agent-skill-doctor.js scan --json",
+    "diagnose": "node ./bin/agent-skill-doctor.js diagnose",
+    "report": "node ./bin/agent-skill-doctor.js report --format md",
+    "phase2": "node ./bin/agent-skill-doctor-phase2.js analyze",
+    "phase3": "node ./bin/agent-skill-doctor-phase3.js conflicts",
+    "risk": "node ./bin/agent-skill-doctor-risk.js scan",
+    "test": "node --test",
+    "publish:npm": "npm publish"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skill",
+    "diagnostic",
+    "governance",
+    "cli",
+    "sqlite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sljdxde/agent-skill-doctor.git"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "license": "MIT"
+}

package/rules/default/credential-risk.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "credential-risk",
+      "title": "Possible credential access",
+      "severity": "high",
+      "category": "credential",
+      "patterns": [
+        { "id": "env-file", "text": ".env" },
+        { "id": "openai-api-key", "text": "OPENAI_API_KEY" },
+        { "id": "anthropic-api-key", "text": "ANTHROPIC_API_KEY" },
+        { "id": "github-token", "text": "GITHUB_TOKEN" },
+        { "id": "ssh-dir", "text": "~/.ssh" }
+      ],
+      "recommendation": "Require explicit user review before enabling skills that reference credential locations or secret names."
+    }
+  ]
+}

package/rules/default/destructive-risk.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "destructive-action-risk",
+      "title": "Possible destructive filesystem operation",
+      "severity": "critical",
+      "category": "destructive_action",
+      "patterns": [
+        { "id": "recursive-remove", "text": "rm -rf" },
+        { "id": "recursive-delete", "text": "delete recursively" },
+        { "id": "overwrite-file", "text": "overwrite" }
+      ],
+      "recommendation": "Require manual review and an explicit confirmation step before destructive file operations are allowed."
+    }
+  ]
+}

package/rules/default/shell-network-risk.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "shell-execution-risk",
+      "title": "Possible shell execution",
+      "severity": "medium",
+      "category": "shell",
+      "patterns": [
+        { "id": "subprocess", "text": "subprocess" },
+        { "id": "child-process", "text": "child_process" },
+        { "id": "os-system", "text": "os.system" },
+        { "id": "powershell", "text": "powershell" }
+      ],
+      "recommendation": "Review shell execution instructions and require user confirmation before running commands."
+    },
+    {
+      "id": "network-download-risk",
+      "title": "Possible remote download or installer execution",
+      "severity": "high",
+      "category": "network",
+      "patterns": [
+        { "id": "curl-command", "text": "curl" },
+        { "id": "wget-command", "text": "wget" },
+        { "id": "remote-script", "text": "remote script" },
+        { "id": "download-execute", "text": "download and execute" }
+      ],
+      "recommendation": "Verify source URLs and avoid automatic execution of remotely downloaded content."
+    }
+  ]
+}

package/src/doctor/conflict.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { buildSkillIdentityKey, buildParticipantIdentityKey } = require('./phase2');
+
+function sha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex');
+}
+
+function normalizeText(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function normalizeAnchor(text) {
+  return normalizeText(text).slice(0, 300);
+}
+
+/**
+ * Extract all text content from a skill for matching.
+ */
+function skillTextContent(skill) {
+  const parts = [];
+  if (skill.description) parts.push(skill.description);
+  if (skill._scan?.text) parts.push(skill._scan.text);
+  if (skill.frontmatter) {
+    for (const v of Object.values(skill.frontmatter)) {
+      if (typeof v === 'string') parts.push(v);
+    }
+  }
+  return normalizeText(parts.join(' '));
+}
+
+/**
+ * Check which alternative index a skill matches, or -1 if none.
+ * Uses the best match strategy: checks all alternatives and returns
+ * the one with the longest matching keyword to avoid substring false positives.
+ */
+function matchAlternative(skillText, alternatives) {
+  const lower = skillText;
+  let bestIdx = -1;
+  let bestLen = 0;
+  for (let i = 0; i < alternatives.length; i++) {
+    const keywords = alternatives[i];
+    for (const kw of keywords) {
+      const normalized = normalizeText(kw);
+      if (lower.includes(normalized) && normalized.length > bestLen) {
+        bestIdx = i;
+        bestLen = normalized.length;
+      }
+    }
+  }
+  return bestIdx;
+}
+
+/**
+ * Detect conflicts among skills based on conflict rules.
+ * Each rule has `alternatives` - when skills match different alternatives, that's a conflict.
+ *
+ * @param {Array} skills - skill records
+ * @param {Array} conflictRules - rules from DEFAULT_CONFLICT_RULES or loaded from files
+ * @returns {Array} conflict findings
+ */
+function detectConflicts(skills, conflictRules) {
+  const findings = [];
+
+  for (const rule of conflictRules) {
+    const alternatives = rule.alternatives || [];
+    if (alternatives.length < 2) continue;
+
+    // Map: alternativeIndex -> [skills]
+    const buckets = new Map();
+    for (const skill of skills) {
+      const text = skillTextContent(skill);
+      const idx = matchAlternative(text, alternatives);
+      if (idx < 0) continue;
+      if (!buckets.has(idx)) buckets.set(idx, []);
+      buckets.get(idx).push(skill);
+    }
+
+    // Need at least 2 different alternatives matched
+    const matchedAlts = [...buckets.entries()].filter(([, s]) => s.length > 0);
+    if (matchedAlts.length < 2) continue;
+
+    // Sort by alternative index for deterministic role assignment
+    matchedAlts.sort((a, b) => a[0] - b[0]);
+
+    // Collect all participating skills
+    const allSkills = [];
+    for (const [, bucketSkills] of matchedAlts) allSkills.push(...bucketSkills);
+    const sorted = [...allSkills].sort((a, b) =>
+      buildSkillIdentityKey(a).localeCompare(buildSkillIdentityKey(b))
+    );
+
+    const participantKey = buildParticipantIdentityKey(sorted);
+    const conflictType = rule.type || 'opposite_instruction';
+    const reason = matchedAlts
+      .map(([altIdx, bucketSkills]) => {
+        const sortedSlugs = bucketSkills.map(s => s.slug).sort().join(', ');
+        return `alternative[${altIdx}] (${alternatives[altIdx].join(', ')}): ${sortedSlugs}`;
+      })
+      .join(' vs ');
+
+    const signature = sha256(`${conflictType}:${rule.id}:${normalizeAnchor(reason)}`);
+    const id = sha256(`${participantKey}:conflict:conflict-detector:${rule.id}:${signature}`);
+
+    // Assign roles: first two buckets get source/target, rest get related
+    const links = [];
+    for (let bucketIdx = 0; bucketIdx < matchedAlts.length; bucketIdx++) {
+      const [, bucketSkills] = matchedAlts[bucketIdx];
+      const role = bucketIdx === 0 ? 'source' : bucketIdx === 1 ? 'target' : 'related';
+      for (const s of bucketSkills) {
+        links.push({ skillId: s.id, role });
+      }
+    }
+
+    findings.push({
+      id,
+      type: 'conflict',
+      severity: rule.severity || 'medium',
+      detectorId: 'conflict-detector',
+      ruleId: rule.id,
+      title: rule.title || `Conflict: ${conflictType}`,
+      description: `Detected conflict among skills: ${reason}`,
+      signature,
+      evidence: sorted.map(s => ({
+        file: s.location?.path || s.local_path || '',
+        text: `${s.slug}: ${s.description || '(no description)'}`,
+        anchor: normalizeAnchor(`${s.slug} ${s.description || ''}`),
+      })),
+      recommendation: rule.recommendation || 'Review conflicting skills and keep only one convention per project.',
+      skills: sorted,
+      links,
+    });
+  }
+
+  return findings;
+}
+
+module.exports = { detectConflicts, matchAlternative, skillTextContent };