@ngxtm/devkit 3.15.0 → 3.17.0

package/scripts/build-compact-index.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * Build Compact Skill Index
+ *
+ * Creates a minimal index (~20-30KB) for auto-skill detection
+ * without overwhelming Claude's context window.
+ *
+ * Output: skills-compact.json
+ * Format: { "skill-name": { "c": "category", "d": "short description" } }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+const GRAPH_FILE = path.join(__dirname, '..', 'skills-graph.json');
+const OUTPUT_FILE = path.join(__dirname, '..', 'skills-compact.json');
+
+// Weight defaults — keep in sync with build-skill-graph.js
+const WEIGHT_DEFAULTS = { enhances: 'strong', 'pairs-with': 'moderate' };
+
+// Category short codes
+const CATEGORY_CODES = {
+  'security': 'sec',
+  'devops': 'ops',
+  'ai-ml': 'ai',
+  'testing': 'test',
+  'database': 'db',
+  'mobile': 'mob',
+  'rust': 'rs',
+  'golang': 'go',
+  'python': 'py',
+  'data': 'data',
+  'performance': 'perf',
+  'architecture': 'arch',
+  'git-workflow': 'git',
+  'documentation': 'doc',
+  'backend': 'be',
+  'frontend': 'fe',
+  'other': 'other'
+};
+
+// Category patterns — ORDER MATTERS: specific categories first, broad ones last
+const CATEGORY_PATTERNS = [
+  ['security',     /security|auth|oauth|jwt|owasp|pentest|penetration|vulnerability|exploit|xss|injection|privilege.escalation|active.directory|attack|malware|forensic|reverse.engineer|red.team|burp|shodan|metasploit|sqlmap|brute.?force|encryption|crypto(?!currency)|firewall|ids|ips|siem|soc|threat|cve|hardening|compliance|gdpr|pci|sast|dast|ctf/i],
+  ['devops',       /docker|kubernetes|k8s|ci[\/-]?cd|deploy|aws|azure|gcp|cloud|terraform|ansible|helm|istio|linkerd|jenkins|github.actions|gitlab.ci|argocd|pulumi|vagrant|prometheus|grafana|monitoring|observability|sre|incident|on.call|runbook|infrastructure|server.management|nginx|apache|load.balancer|cdn/i],
+  ['ai-ml',        /\bai\b|machine.learning|\bml\b|\bllm\b|agent(?!.assistant)|openai|anthropic|langchain|langgraph|prompt|embedding|rag\b|mcp\b|fine.tuning|hugging.face|transformer|gpt|claude|gemini|diffusion|stable|midjourney|vision|nlp|neural|deep.learning|tensor|torch|crew.?ai|autogen|semantic|vector/i],
+  ['testing',      /\btest|jest|vitest|playwright|cypress|tdd|bdd|e2e|qa\b|regression|unit.test|integration.test|mock|stub|fixture|coverage|assertion/i],
+  ['database',     /database|sql\b|postgres|mysql|mongo|redis|prisma|drizzle|supabase|firebase|dynamo|cassandra|cockroach|sqlite|migration|schema|query.optim|nosql|elasticsearch|clickhouse|neon/i],
+  ['mobile',       /mobile|react.native|flutter|ios\b|android|swift(?!ui)|kotlin(?!.specialist)|expo|dart\b|xcode|app.store|play.store/i],
+  ['rust',         /\brust\b|cargo|tokio|actix|wasm/i],
+  ['golang',       /\bgolang\b|\bgo\b(?!ogle|dot|od)|gin\b|echo\b|fiber\b/i],
+  ['python',       /\bpython\b|django|flask|fastapi|pandas|numpy|scipy|jupyter|pip\b|poetry|uv\b.*package/i],
+  ['data',         /\bdata\b.*(?:engineer|pipeline|quality|warehouse)|analytics|etl\b|spark\b|kafka\b|airflow|dbt\b|streaming/i],
+  ['performance',  /performance|profiling|optimization|cache|benchmark|latency|throughput|memory.leak/i],
+  ['architecture', /architecture|system.design|design.pattern|\bsolid\b|clean.architecture|\bddd\b|event.sourc|cqrs|hexagonal|microservice.pattern|domain.driven/i],
+  ['git-workflow', /\bgit\b|github|gitlab|pull.request|\bpr\b|code.review|branching|merge|commit|changelog|version|release/i],
+  ['documentation',/\bdoc\b|readme|api.doc|swagger|openapi|technical.writing|jsdoc|typedoc/i],
+  ['backend',      /node\.?js|express|nest\.?js|fastify|hono|backend|server|api\b|rest\b|graphql|grpc|webhook|middleware|routing|endpoint|websocket/i],
+  ['frontend',     /react(?!.native)|vue|angular|svelte|next\.?js|nuxt|remix|astro|frontend|ui\b|ux\b|css|tailwind|component|html|dom|browser|responsive|accessibility|wcag|animation|canvas|three\.?js|d3/i],
+];
+
+/**
+ * Parse YAML frontmatter
+ */
+function parseFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const yaml = match[1];
+  const result = {};
+
+  const lines = yaml.split('\n');
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Categorize skill
+ */
+function categorizeSkill(name, description) {
+  const nameText = name.toLowerCase();
+  const fullText = `${name} ${description}`.toLowerCase();
+
+  // Match on name first (more reliable), then fall back to description
+  for (const [category, pattern] of CATEGORY_PATTERNS) {
+    if (pattern.test(nameText)) {
+      return CATEGORY_CODES[category] || category;
+    }
+  }
+  for (const [category, pattern] of CATEGORY_PATTERNS) {
+    if (pattern.test(fullText)) {
+      return CATEGORY_CODES[category] || category;
+    }
+  }
+
+  return 'other';
+}
+
+/**
+ * Shorten description to max 60 chars
+ */
+function shortenDesc(desc) {
+  if (!desc) return '';
+
+  // Remove markdown, newlines, extra spaces
+  let clean = desc
+    .replace(/\r?\n/g, ' ')
+    .replace(/[#*`_\[\]]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (clean.length <= 60) return clean;
+
+  // Cut at word boundary
+  const cut = clean.slice(0, 57);
+  const lastSpace = cut.lastIndexOf(' ');
+  return (lastSpace > 40 ? cut.slice(0, lastSpace) : cut) + '...';
+}
+
+/**
+ * Build compact index
+ */
+function buildCompactIndex() {
+  console.log('Building compact skill index...\n');
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('Skills directory not found:', SKILLS_DIR);
+    process.exit(1);
+  }
+
+  const skillDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+    .map(d => d.name)
+    .sort();
+
+  console.log(`Found ${skillDirs.length} skill directories`);
+
+  const index = {
+    _categories: CATEGORY_CODES,
+    skills: {}
+  };
+  let processedCount = 0;
+
+  for (const skillName of skillDirs) {
+    const skillPath = path.join(SKILLS_DIR, skillName);
+    const skillFile = path.join(skillPath, 'SKILL.md');
+
+    if (!fs.existsSync(skillFile)) continue;
+
+    const content = fs.readFileSync(skillFile, 'utf-8');
+    const frontmatter = parseFrontmatter(content);
+
+    const description = frontmatter.description || '';
+    const category = categorizeSkill(skillName, description);
+
+    // Include category and short description for semantic matching
+    const shortDesc = shortenDesc(description);
+    index.skills[skillName] = shortDesc ? { c: category, d: shortDesc } : category;
+
+    processedCount++;
+  }
+
+  console.log(`Processed ${processedCount} skills`);
+
+  // Merge cascade fields from skills-graph.json
+  if (fs.existsSync(GRAPH_FILE)) {
+    let graph;
+    try {
+      graph = JSON.parse(fs.readFileSync(GRAPH_FILE, 'utf-8'));
+    } catch (e) {
+      console.error(`Warning: skills-graph.json is malformed, skipping cascade merge: ${e.message}`);
+      graph = null;
+    }
+
+    if (graph) {
+
+    // Build set of quarantined skills
+    const quarantined = new Set();
+    for (const [name, data] of Object.entries(graph.graph || {})) {
+      if (data._security === 'quarantined') quarantined.add(name);
+    }
+
+    // Merge cascade fields into compact skills
+    let cascadeCount = 0;
+    for (const [name, data] of Object.entries(graph.graph || {})) {
+      if (quarantined.has(name)) continue;
+      if (!index.skills[name]) continue;
+      if (!data.connections) continue;
+
+      // Ensure skill entry is an object (not just a category string)
+      if (typeof index.skills[name] === 'string') {
+        index.skills[name] = { c: index.skills[name] };
+      }
+
+      const enhances = (data.connections.enhances || []).filter(s => !quarantined.has(s));
+      const pairsWith = (data.connections['pairs-with'] || []).filter(s => !quarantined.has(s));
+      const weights = data.connections.weights || {};
+      const domain = data.connections.domain || [];
+
+      if (enhances.length) index.skills[name].e = enhances;
+      if (pairsWith.length) index.skills[name].p = pairsWith;
+
+      // Only include non-default weights
+      const nonDefaultWeights = {};
+      for (const [target, weight] of Object.entries(weights)) {
+        if (quarantined.has(target)) continue;
+        const isEnhance = enhances.includes(target);
+        const isPair = pairsWith.includes(target);
+        if (isEnhance && weight !== WEIGHT_DEFAULTS.enhances) nonDefaultWeights[target] = weight;
+        else if (isPair && weight !== WEIGHT_DEFAULTS['pairs-with']) nonDefaultWeights[target] = weight;
+      }
+      if (Object.keys(nonDefaultWeights).length) index.skills[name].w = nonDefaultWeights;
+
+      if (domain.length) index.skills[name].k = domain;
+
+      cascadeCount++;
+    }
+
+    // Copy _recipes (removing quarantined skill refs)
+    if (graph._recipes && Object.keys(graph._recipes).length) {
+      index._recipes = {};
+      for (const [name, recipe] of Object.entries(graph._recipes)) {
+        const cleanSkills = (recipe.skills || []).filter(s => !quarantined.has(s));
+        if (cleanSkills.length < 2) continue;
+        index._recipes[name] = {
+          triggers: recipe.triggers || [],
+          skills: cleanSkills,
+          workflow: recipe.workflow || []
+        };
+      }
+    }
+
+    console.log(`Merged cascade fields for ${cascadeCount} skills from graph`);
+    if (quarantined.size) console.log(`Quarantined: ${quarantined.size} skills excluded`);
+    } // if (graph)
+  }
+
+  // Write output (no pretty print for smaller size)
+  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(index));
+
+  const stats = fs.statSync(OUTPUT_FILE);
+  console.log(`\nGenerated: ${OUTPUT_FILE}`);
+  console.log(`Size: ${(stats.size / 1024).toFixed(1)} KB`);
+  console.log(`Skills: ${Object.keys(index.skills).length}`);
+
+  // Category distribution
+  const catCount = {};
+  for (const val of Object.values(index.skills)) {
+    const cat = typeof val === 'string' ? val : val.c;
+    catCount[cat] = (catCount[cat] || 0) + 1;
+  }
+
+  console.log('\nCategory distribution:');
+  Object.entries(catCount)
+    .sort((a, b) => b[1] - a[1])
+    .forEach(([cat, count]) => {
+      console.log(`  ${cat}: ${count}`);
+    });
+
+  return index;
+}
+
+// Run
+buildCompactIndex();

package/scripts/build-skill-graph.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * Build Skill Graph
+ *
+ * Validates and cleans skills-graph.json:
+ * - Removes orphaned entries (skills/commands that no longer exist)
+ * - Validates connections (removes broken links)
+ * - Validates recipes (removes broken skill refs, deletes recipes with <2 skills)
+ * - Cleans orphaned weights
+ * - Recomputes _meta.stats and _tiers
+ *
+ * Runs BEFORE build-compact-index so compact can merge cascade data.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const GRAPH_FILE = path.join(__dirname, '..', 'skills-graph.json');
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+const COMMANDS_DIR = path.join(__dirname, '..', '.claude', 'commands');
+
+// Weight defaults — keep in sync with build-compact-index.js
+const WEIGHT_DEFAULTS = { enhances: 'strong', 'pairs-with': 'moderate' };
+
+function buildSkillGraph() {
+  console.log('Building skill graph...\n');
+
+  // 1. Read or init graph
+  let graph;
+  if (fs.existsSync(GRAPH_FILE)) {
+    try {
+      graph = JSON.parse(fs.readFileSync(GRAPH_FILE, 'utf-8'));
+    } catch (e) {
+      console.error(`Error: skills-graph.json is malformed: ${e.message}`);
+      process.exit(1);
+    }
+  } else {
+    graph = {
+      _meta: {
+        version: 2,
+        lastUpdated: new Date().toISOString().split('T')[0],
+        stats: {
+          totalSkills: 0, graphedSkills: 0,
+          connections: 0, strongConnections: 0, moderateConnections: 0, weakConnections: 0,
+          density: 0.0, recipes: 0
+        }
+      },
+      _tiers: { 't1-orchestrator': [], 't2-hub': [], 't3-utility': [], 't4-connected': [], 't4-standalone': [] },
+      _recipes: {},
+      graph: {}
+    };
+  }
+
+  // Ensure sections exist
+  if (!graph._recipes) graph._recipes = {};
+  if (!graph.graph) graph.graph = {};
+
+  // 2. Get current skills list (skills/ dirs + .claude/commands/ files, recursive)
+  const skillDirs = fs.existsSync(SKILLS_DIR)
+    ? fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+        .map(d => d.name)
+    : [];
+
+  const commandNames = [];
+  if (fs.existsSync(COMMANDS_DIR)) {
+    const scanDir = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          commandNames.push(entry.name.replace('.md', ''));
+        } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          scanDir(path.join(dir, entry.name));
+        }
+      }
+    };
+    scanDir(COMMANDS_DIR);
+  }
+
+  const currentSkills = new Set([...skillDirs, ...commandNames]);
+
+  // 3. Remove orphaned graph entries
+  let orphansRemoved = 0;
+  for (const name of Object.keys(graph.graph)) {
+    if (!currentSkills.has(name)) {
+      delete graph.graph[name];
+      orphansRemoved++;
+    }
+  }
+
+  // 4. Validate connections (remove broken links) + clean weights
+  let brokenLinksRemoved = 0;
+  for (const data of Object.values(graph.graph)) {
+    if (!data.connections) continue;
+
+    for (const connType of ['enhances', 'pairs-with']) {
+      if (data.connections[connType]) {
+        const before = data.connections[connType].length;
+        data.connections[connType] = data.connections[connType]
+          .filter(target => currentSkills.has(target));
+        brokenLinksRemoved += before - data.connections[connType].length;
+      }
+    }
+
+    // Clean orphaned weights (weight entry but target not in enhances/pairs-with)
+    if (data.connections.weights) {
+      const validTargets = new Set([
+        ...(data.connections.enhances || []),
+        ...(data.connections['pairs-with'] || [])
+      ]);
+      for (const target of Object.keys(data.connections.weights)) {
+        if (!validTargets.has(target)) {
+          delete data.connections.weights[target];
+        }
+      }
+    }
+  }
+
+  // 4.5. Validate recipes (remove broken skill references)
+  let recipesRemoved = 0;
+  for (const [name, recipe] of Object.entries(graph._recipes)) {
+    if (recipe.skills) {
+      recipe.skills = recipe.skills.filter(s => currentSkills.has(s));
+    }
+    if (!recipe.skills || recipe.skills.length < 2) {
+      delete graph._recipes[name];
+      recipesRemoved++;
+    }
+  }
+
+  // 5. Recompute _meta.stats (including weight breakdown)
+  let strongCount = 0, moderateCount = 0, weakCount = 0;
+  let totalConnections = 0;
+
+  for (const data of Object.values(graph.graph)) {
+    const enhances = data.connections?.enhances || [];
+    const pairsWith = data.connections?.['pairs-with'] || [];
+    const weights = data.connections?.weights || {};
+
+    totalConnections += enhances.length + pairsWith.length;
+
+    for (const s of enhances) {
+      const w = weights[s] || WEIGHT_DEFAULTS.enhances;
+      if (w === 'strong') strongCount++;
+      else if (w === 'moderate') moderateCount++;
+      else weakCount++;
+    }
+    for (const s of pairsWith) {
+      const w = weights[s] || WEIGHT_DEFAULTS['pairs-with'];
+      if (w === 'strong') strongCount++;
+      else if (w === 'moderate') moderateCount++;
+      else weakCount++;
+    }
+  }
+
+  const graphedCount = Object.keys(graph.graph).length;
+  graph._meta.stats = {
+    totalSkills: currentSkills.size,
+    graphedSkills: graphedCount,
+    connections: totalConnections,
+    strongConnections: strongCount,
+    moderateConnections: moderateCount,
+    weakConnections: weakCount,
+    density: graphedCount > 0
+      ? parseFloat((totalConnections / graphedCount).toFixed(2))
+      : 0,
+    recipes: Object.keys(graph._recipes).length
+  };
+  graph._meta.lastUpdated = new Date().toISOString().split('T')[0];
+
+  // 6. Recompute _tiers
+  graph._tiers = {
+    't1-orchestrator': [],
+    't2-hub': [],
+    't3-utility': [],
+    't4-connected': [],
+    't4-standalone': []
+  };
+
+  for (const [name, data] of Object.entries(graph.graph)) {
+    const hasConnections = (data.connections?.enhances?.length || 0) +
+                           (data.connections?.['pairs-with']?.length || 0) > 0;
+    const tierKey = {
+      1: 't1-orchestrator',
+      2: 't2-hub',
+      3: 't3-utility',
+      4: hasConnections ? 't4-connected' : 't4-standalone'
+    }[data.tier] || 't4-standalone';
+
+    graph._tiers[tierKey].push(name);
+  }
+
+  // Sort each tier array
+  for (const arr of Object.values(graph._tiers)) arr.sort();
+
+  // 7. Write validated graph
+  fs.writeFileSync(GRAPH_FILE, JSON.stringify(graph, null, 2) + '\n');
+
+  // 8. Report
+  const s = graph._meta.stats;
+  console.log(`Graph: ${s.graphedSkills}/${s.totalSkills} skills mapped, ${s.connections} connections (${s.strongConnections} strong, ${s.moderateConnections} moderate, ${s.weakConnections} weak), ${s.recipes} recipes, density ${s.density}`);
+
+  if (orphansRemoved) console.log(`  Cleaned: ${orphansRemoved} orphaned entries`);
+  if (brokenLinksRemoved) console.log(`  Cleaned: ${brokenLinksRemoved} broken links`);
+  if (recipesRemoved) console.log(`  Cleaned: ${recipesRemoved} invalid recipes`);
+}
+
+buildSkillGraph();

package/skills/3d-web-experience/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: 3d-web-experience
-description: "Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing depth to web experiences. Use when: 3D website, three.js, WebGL, react three fiber, 3D experience."
+description: "Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing ..."
 source: vibeship-spawner-skills (Apache 2.0)
+risk: unknown
 ---
 
 # 3D Web Experience
@@ -252,3 +253,6 @@ Optimize model size.
 ## Related Skills
 
 Works well with: `scroll-experience`, `interactive-portfolio`, `frontend`, `landing-page-design`
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/ab-test-setup/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ab-test-setup
-description: Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness.
+description: "Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness."
+risk: unknown
+source: community
 ---
 
 # A/B Test Setup
@@ -230,3 +232,6 @@ It is about **learning the truth with confidence**.
 
 If you feel tempted to rush, simplify, or “just try it” —
 that is the signal to **slow down and re-check the design**.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/accessibility-compliance-accessibility-audit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: accessibility-compliance-accessibility-audit
 description: "You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance."
+risk: unknown
+source: community
 ---
 
 # Accessibility Audit and Testing

package/skills/active-directory-attacks/SKILL.md

@@ -1,9 +1,11 @@
 ---
-name: Active Directory Attacks
-description: This skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing.
+name: active-directory-attacks
+description: "This skill should be used when the user asks to \"attack Active Directory\", \"exploit AD\", \"Kerberoasting\", \"DCSync\", \"pass-the-hash\", \"BloodHound enumeration\", \"Golden Ticket\", ..."
 metadata:
   author: zebbern
   version: "1.1"
+risk: unknown
+source: community
 ---
 
 # Active Directory Attacks
@@ -381,3 +383,6 @@ python3 printerbug.py domain.local/user:pass@target 10.10.10.12
 ## Additional Resources
 
 For advanced techniques including delegation attacks, GPO abuse, RODC attacks, SCCM/WSUS deployment, ADCS exploitation, trust relationships, and Linux AD integration, see [references/advanced-attacks.md](references/advanced-attacks.md).
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.