claudecode-omc 5.2.0 → 5.3.0

package/bundled/upstream/anthropic-skills/spec/agent-skills-spec.md

@@ -0,0 +1,3 @@
+# Agent Skills Spec
+
+The spec is now located at <https://agentskills.io/specification>

package/bundled/upstream/anthropic-skills/template/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: template-skill
+description: Replace with description of the skill and when Claude should use it.
+---
+
+# Insert instructions below

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudecode-omc",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Claude Code harness — best-practice skills, agents, hooks, and configs from multiple sources",
   "bin": {
     "omc-manage": "bin/omc-manage.js"

package/src/cli/artifact.js

@@ -33,6 +33,7 @@ function loadSourcesForType(artifactType, root) {
   if (!loader) return sources;
 
   for (const [name, src] of ordered) {
+    if (src.role === 'reference') continue;
     if (!(src.artifacts || []).includes(artifactType)) continue;
     const dir = getSourceArtifactDir(name, artifactType, root);
     if (!fs.existsSync(dir)) continue;
@@ -151,4 +152,4 @@ async function artifact(args, flags = {}) {
   }
 }
 
-module.exports = { artifact };
+module.exports = { artifact, loadSourcesForType };

package/src/cli/index.js

@@ -20,6 +20,9 @@ function showHelp() {
   console.log('  source    list|add|remove|sync|status — manage sources');
   console.log('  artifact  list|prefer|conflicts [--type <type>] — manage artifacts');
   console.log('  skill     list|prefer|conflicts — alias for artifact --type skills');
+  console.log('            evaluate [name] — quality score (Anthropic-aligned)');
+  console.log('            compare [--threshold N] — cross-source overlap analysis');
+  console.log('            recommend [--apply] — preference recommendations');
   console.log('  help      Show this help');
   console.log('');
   console.log('Artifact types: skills, agents, hooks, commands, claude-md, settings, hud');
@@ -68,6 +71,9 @@ async function main(argv) {
     else if (arg === '--ref' && args[i + 1]) flags.ref = args[++i];
     else if (arg === '--priority' && args[i + 1]) flags.priority = parseInt(args[++i], 10);
     else if (arg === '--artifacts' && args[i + 1]) flags.artifacts = args[++i].split(',');
+    else if (arg === '--apply') flags.apply = true;
+    else if (arg === '--threshold' && args[i + 1]) flags.threshold = args[++i];
+    else if (arg.startsWith('--threshold=')) flags.threshold = arg.split('=')[1];
     else positional.push(arg);
   }
 

package/src/cli/setup.js

@@ -229,6 +229,9 @@ async function setup(args, flags = {}) {
     // Collect sources that have this artifact type
     const sourcesForType = [];
     for (const [name, src] of orderedSources) {
+      // Skip reference-only sources (e.g. anthropic-skills) — they provide
+      // evaluation standards, not installable artifacts.
+      if (src.role === 'reference') continue;
       const declaredArtifacts = src.artifacts || [];
       if (!declaredArtifacts.includes(artifactType)) continue;
 

package/src/cli/skill.js

@@ -1,7 +1,278 @@
 /* eslint-disable no-console */
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
 const { artifact } = require('./artifact');
+const { loadSourcesForType } = require('./artifact');
+const { getProjectRoot, getMergeConfigPath } = require('../config/paths');
+const { evaluateSkillQuality, getUpstreamValidatorPath } = require('../utils/quality');
+const { detectOverlaps, generateRecommendations } = require('../utils/overlap');
+
+// Grade thresholds
+const GRADE_THRESHOLDS = [
+  [90, 'A'],
+  [80, 'B'],
+  [65, 'C'],
+  [50, 'D'],
+  [0,  'F'],
+];
+
+function grade(score) {
+  for (const [min, letter] of GRADE_THRESHOLDS) {
+    if (score >= min) return letter;
+  }
+  return 'F';
+}
+
+function dimBar(score, max = 25) {
+  const filled = Math.round((score / max) * 10);
+  return '#'.repeat(filled) + '-'.repeat(10 - filled);
+}
+
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+
+/**
+ * omc-manage skill evaluate [name] [--verbose]
+ *
+ * Evaluate quality of all skills (or a named skill) across all sources.
+ */
+async function evaluate(args, flags) {
+  const root = getProjectRoot();
+  const filter = args[1]; // optional skill name
+  const sources = loadSourcesForType('skills', root);
+
+  if (sources.length === 0) {
+    console.log('No skill sources found. Run: omc-manage source sync');
+    return;
+  }
+
+  const results = [];
+  for (const source of sources) {
+    for (const item of source.items) {
+      if (filter && item.name !== filter) continue;
+      const quality = evaluateSkillQuality(item);
+      results.push({ name: item.name, source: source.name, quality });
+    }
+  }
+
+  if (results.length === 0) {
+    console.log(filter ? `Skill "${filter}" not found.` : 'No skills found.');
+    return;
+  }
+
+  // Sort by score descending
+  results.sort((a, b) => b.quality.score - a.quality.score);
+
+  if (filter || results.length === 1) {
+    // Detailed view for single skill
+    const r = results[0];
+    const d = r.quality.dimensions;
+    console.log(`Skill: ${r.name} (${r.source})`);
+    console.log(`Score: ${r.quality.score}/100 [${grade(r.quality.score)}]`);
+    console.log('');
+    console.log(`  Metadata:      ${d.metadata}/25  [${dimBar(d.metadata)}]`);
+    console.log(`  Content:       ${d.content}/25  [${dimBar(d.content)}]`);
+    console.log(`  Structure:     ${d.structure}/25  [${dimBar(d.structure)}]`);
+    console.log(`  Actionability: ${d.actionability}/25  [${dimBar(d.actionability)}]`);
+    if (r.quality.signals.length > 0) {
+      console.log('');
+      console.log('Issues:');
+      for (const s of r.quality.signals) {
+        console.log(`  - ${s}`);
+      }
+    }
+  } else {
+    // Table view
+    console.log(`Skill Quality Report (${results.length} skills)`);
+    console.log('='.repeat(72));
+    console.log(`${'Name'.padEnd(28)} ${'Source'.padEnd(18)} ${'Score'.padStart(5)} Grade`);
+    console.log('-'.repeat(72));
+    for (const r of results) {
+      console.log(`${r.name.padEnd(28)} ${r.source.padEnd(18)} ${String(r.quality.score).padStart(5)} ${grade(r.quality.score).padStart(5)}`);
+    }
+    console.log('-'.repeat(72));
+
+    // Summary
+    const avg = Math.round(results.reduce((s, r) => s + r.quality.score, 0) / results.length);
+    const aCount = results.filter(r => r.quality.score >= 90).length;
+    const bCount = results.filter(r => r.quality.score >= 80 && r.quality.score < 90).length;
+    const fCount = results.filter(r => r.quality.score < 50).length;
+    console.log(`Average: ${avg}/100  A:${aCount} B:${bCount} F:${fCount}`);
+
+    if (flags.verbose) {
+      console.log('');
+      console.log('Common issues:');
+      const issueCounts = {};
+      for (const r of results) {
+        for (const s of r.quality.signals) {
+          issueCounts[s] = (issueCounts[s] || 0) + 1;
+        }
+      }
+      const sorted = Object.entries(issueCounts).sort((a, b) => b[1] - a[1]);
+      for (const [issue, count] of sorted.slice(0, 10)) {
+        console.log(`  ${String(count).padStart(3)}x  ${issue}`);
+      }
+    }
+  }
+
+  // Hint about upstream validator
+  const validatorPath = getUpstreamValidatorPath(root);
+  if (validatorPath && filter) {
+    console.log('');
+    console.log(`Tip: Run Anthropic's official validator:`);
+    console.log(`  python3 ${path.relative(process.cwd(), validatorPath)} <skill-dir>`);
+  }
+}
+
+/**
+ * omc-manage skill compare [--threshold N]
+ *
+ * Detect functional overlaps across sources and compare quality.
+ */
+async function compare(args, flags) {
+  const root = getProjectRoot();
+  const threshold = flags.threshold ? parseFloat(flags.threshold) : 0.3;
+  const sources = loadSourcesForType('skills', root);
+
+  if (sources.length < 2) {
+    console.log('Need at least 2 skill sources for comparison.');
+    return;
+  }
+
+  console.log(`Cross-Source Skill Comparison (threshold: ${Math.round(threshold * 100)}%)`);
+  console.log('='.repeat(72));
+
+  const groups = detectOverlaps(sources, { threshold });
+
+  if (groups.length === 0) {
+    console.log('No functional overlaps detected above threshold.');
+    return;
+  }
+
+  for (let i = 0; i < groups.length; i++) {
+    const g = groups[i];
+    console.log('');
+    console.log(`Group ${i + 1}: ${g.domain} (${g.similarity}% similarity)`);
+    console.log('-'.repeat(50));
+
+    for (const s of g.skills) {
+      const marker = s === g.winner ? ' *BEST*' : '';
+      const domains = s.domains.length > 0 ? ` [${s.domains.join(',')}]` : '';
+      console.log(`  ${s.quality.score}/100 ${grade(s.quality.score)}  ${s.source}:${s.name}${domains}${marker}`);
+      if (flags.verbose && s.description) {
+        const desc = s.description.length > 60 ? s.description.slice(0, 57) + '...' : s.description;
+        console.log(`         ${desc}`);
+      }
+    }
+  }
+
+  console.log('');
+  console.log(`Found ${groups.length} overlap groups across ${sources.length} sources.`);
+  console.log('Run "omc-manage skill recommend" to generate preference config.');
+}
+
+/**
+ * omc-manage skill recommend [--apply] [--dry-run]
+ *
+ * Generate merge-config preferences based on quality comparison.
+ */
+async function recommend(args, flags) {
+  const root = getProjectRoot();
+  const sources = loadSourcesForType('skills', root);
+
+  if (sources.length < 2) {
+    console.log('Need at least 2 skill sources for recommendations.');
+    return;
+  }
+
+  const groups = detectOverlaps(sources, { threshold: 0.3 });
+  const newPrefs = generateRecommendations(groups);
+
+  // Load existing config
+  const configPath = getMergeConfigPath(root);
+  let config = { merge_strategy: 'version-priority', auto_merge: true, allow_namespacing: false, sources: [], preferences: {} };
+  if (fs.existsSync(configPath)) {
+    try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  }
+
+  // Merge: new recommendations + existing preferences (existing wins on conflict)
+  const merged = { ...newPrefs, ...config.preferences };
+  const added = Object.keys(newPrefs).filter(k => !config.preferences[k]);
+  const kept = Object.keys(config.preferences);
+
+  console.log('Skill Preference Recommendations');
+  console.log('='.repeat(50));
+
+  if (Object.keys(newPrefs).length === 0 && groups.length > 0) {
+    console.log('');
+    console.log('No exact-name conflicts with >10 point quality gap found.');
+    console.log(`(${groups.length} functional overlap groups exist but have`);
+    console.log(' different names — use "omc-manage skill compare" to review.)');
+  }
+
+  if (added.length > 0) {
+    console.log('');
+    console.log('New recommendations:');
+    for (const name of added) {
+      console.log(`  ${name} -> ${newPrefs[name]}`);
+    }
+  }
+
+  if (kept.length > 0) {
+    console.log('');
+    console.log('Existing preferences (unchanged):');
+    for (const name of kept) {
+      console.log(`  ${name} -> ${config.preferences[name]}`);
+    }
+  }
+
+  // Show all overlap groups as advisory
+  if (groups.length > 0) {
+    console.log('');
+    console.log('Functional overlap advisory (different names, similar purpose):');
+    for (const g of groups) {
+      const members = g.skills.map(s => `${s.source}:${s.name}(${s.quality.score})`).join(' vs ');
+      console.log(`  [${g.domain}] ${members}`);
+      console.log(`    Winner: ${g.winner.source}:${g.winner.name} (${g.winner.quality.score}/100)`);
+    }
+  }
+
+  if (flags.apply && added.length > 0) {
+    config.preferences = merged;
+    if (!flags.dryRun) {
+      await fsp.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+      console.log('');
+      console.log(`Updated ${configPath}`);
+    } else {
+      console.log('');
+      console.log('[dry-run] Would update merge-config.json');
+    }
+  } else if (added.length > 0) {
+    console.log('');
+    console.log('Run with --apply to save recommendations to merge-config.json');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
 
 async function skill(args, flags = {}) {
+  const cmd = args[0];
+
+  if (cmd === 'evaluate' || cmd === 'eval') {
+    return evaluate(args, flags);
+  }
+  if (cmd === 'compare') {
+    return compare(args, flags);
+  }
+  if (cmd === 'recommend') {
+    return recommend(args, flags);
+  }
+
+  // Fall through to artifact subcommands (list, prefer, conflicts)
   flags.type = 'skills';
   await artifact(args, flags);
 }

package/src/config/sources.js

@@ -38,6 +38,18 @@ function getDefaultConfig() {
           commands: 'commands',
         },
       },
+      'anthropic-skills': {
+        remote: 'https://github.com/anthropics/skills.git',
+        ref: 'main',
+        priority: 99,
+        artifacts: ['skills'],
+        mapping: {
+          skills: 'skills',
+          spec: 'spec',
+          template: 'template',
+        },
+        role: 'reference',
+      },
     },
     lastSync: null,
     syncHistory: [],

package/src/merge/base-merger.js

@@ -97,11 +97,12 @@ function detectConflicts(sourcesArray) {
 }
 
 /**
- * Resolve conflicts using 4-tier strategy:
+ * Resolve conflicts using 5-tier strategy:
  * 1. User config preferences
- * 2. SemVer (highest version wins)
- * 3. Local priority (local > upstream)
- * 4. Namespace (keep both with prefixes)
+ * 2. Quality score (>10 point gap wins)
+ * 3. SemVer (highest version wins)
+ * 4. Local priority (local > upstream)
+ * 5. Source priority (lower priority number wins)
  */
 function resolveConflicts(conflicts, config = {}) {
   const resolutions = [];
@@ -131,7 +132,28 @@ function resolveConflicts(conflicts, config = {}) {
       }
     }
 
-    // Tier 2: SemVer comparison
+    // Tier 2: Quality score (if evaluateSkillQuality is available)
+    try {
+      const { evaluateSkillQuality } = require('../utils/quality');
+      const scored = versions.map(v => ({
+        ...v,
+        _quality: v.path ? evaluateSkillQuality(v).score : 0,
+      }));
+      const sorted = [...scored].sort((a, b) => b._quality - a._quality);
+      // Only use quality if there's a meaningful gap (>10 points)
+      if (sorted.length >= 2 && sorted[0]._quality - sorted[1]._quality > 10) {
+        resolutions.push({
+          name, type: 'exact_name', resolution: 'quality-score',
+          winner: sorted[0], rejected: sorted.slice(1),
+          qualityScores: sorted.map(s => ({ source: s.sourceName, score: s._quality })),
+        });
+        continue;
+      }
+    } catch {
+      // quality module not available, skip this tier
+    }
+
+    // Tier 3: SemVer comparison
     const withVersions = versions.filter(v => v.metadata?.version);
     if (withVersions.length === versions.length && versions.length > 1) {
       const sorted = [...versions].sort((a, b) =>
@@ -146,7 +168,7 @@ function resolveConflicts(conflicts, config = {}) {
       }
     }
 
-    // Tier 3: Local priority
+    // Tier 4: Local priority
     const localVersion = versions.find(v => v.sourceName === 'local');
     if (localVersion) {
       resolutions.push({