cc-dev-template 0.1.5 → 0.1.7

package/src/skills/create-agent-skills/scripts/find-skills.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * find-skills.js
+ *
+ * Discovers all Claude Code skills at user and project levels.
+ * Returns JSON with skill locations and basic metadata.
+ *
+ * Usage: node find-skills.js [--json] [--verbose]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const jsonOutput = args.includes('--json');
+const verbose = args.includes('--verbose');
+
+// Skill locations to scan
+const locations = [
+  {
+    name: 'user',
+    path: path.join(os.homedir(), '.claude', 'skills'),
+    description: 'User-level skills (~/.claude/skills/)'
+  },
+  {
+    name: 'project',
+    path: path.join(process.cwd(), '.claude', 'skills'),
+    description: 'Project-level skills (.claude/skills/)'
+  },
+  {
+    name: 'source',
+    path: path.join(process.cwd(), 'src', 'skills'),
+    description: 'Source skills (src/skills/)'
+  }
+];
+
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].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();
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Get basic stats about a skill
+ */
+function getSkillStats(skillPath) {
+  const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+  if (!fs.existsSync(skillMdPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf-8');
+  const frontmatter = parseFrontmatter(content);
+
+  // Count words in body (after frontmatter)
+  const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  const body = bodyMatch ? bodyMatch[1] : content;
+  const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+
+  // Check for subdirectories
+  const hasReferences = fs.existsSync(path.join(skillPath, 'references'));
+  const hasScripts = fs.existsSync(path.join(skillPath, 'scripts'));
+  const hasAssets = fs.existsSync(path.join(skillPath, 'assets'));
+
+  return {
+    name: frontmatter?.name || path.basename(skillPath),
+    description: frontmatter?.description || null,
+    wordCount,
+    hasReferences,
+    hasScripts,
+    hasAssets,
+    frontmatterValid: !!(frontmatter?.name && frontmatter?.description)
+  };
+}
+
+/**
+ * Scan a location for skills
+ */
+function scanLocation(location) {
+  const skills = [];
+
+  if (!fs.existsSync(location.path)) {
+    return skills;
+  }
+
+  const entries = fs.readdirSync(location.path, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillPath = path.join(location.path, entry.name);
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+    if (fs.existsSync(skillMdPath)) {
+      const stats = getSkillStats(skillPath);
+
+      skills.push({
+        directory: entry.name,
+        path: skillPath,
+        location: location.name,
+        ...stats
+      });
+    }
+  }
+
+  return skills;
+}
+
+// Main execution
+const results = {
+  timestamp: new Date().toISOString(),
+  cwd: process.cwd(),
+  locations: {},
+  skills: [],
+  summary: {
+    total: 0,
+    byLocation: {}
+  }
+};
+
+for (const location of locations) {
+  const skills = scanLocation(location);
+
+  results.locations[location.name] = {
+    path: location.path,
+    exists: fs.existsSync(location.path),
+    count: skills.length
+  };
+
+  results.skills.push(...skills);
+  results.summary.byLocation[location.name] = skills.length;
+}
+
+results.summary.total = results.skills.length;
+
+// Output
+if (jsonOutput) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  console.log('\n=== Claude Code Skills Discovery ===\n');
+
+  for (const location of locations) {
+    const info = results.locations[location.name];
+    console.log(`${location.description}`);
+    console.log(`  Path: ${info.path}`);
+    console.log(`  Exists: ${info.exists ? 'Yes' : 'No'}`);
+    console.log(`  Skills found: ${info.count}`);
+    console.log();
+  }
+
+  if (results.skills.length === 0) {
+    console.log('No skills found.\n');
+  } else {
+    console.log('=== Skills ===\n');
+
+    for (const skill of results.skills) {
+      console.log(`[${skill.location}] ${skill.name}`);
+      console.log(`  Path: ${skill.path}`);
+
+      if (verbose) {
+        console.log(`  Words: ${skill.wordCount}`);
+        console.log(`  Valid frontmatter: ${skill.frontmatterValid ? 'Yes' : 'No'}`);
+        console.log(`  Has references/: ${skill.hasReferences ? 'Yes' : 'No'}`);
+        console.log(`  Has scripts/: ${skill.hasScripts ? 'Yes' : 'No'}`);
+
+        if (skill.description) {
+          const truncated = skill.description.length > 80
+            ? skill.description.slice(0, 80) + '...'
+            : skill.description;
+          console.log(`  Description: ${truncated}`);
+        }
+      }
+
+      console.log();
+    }
+
+    console.log(`Total: ${results.summary.total} skill(s)\n`);
+  }
+}

package/src/skills/create-agent-skills/scripts/validate-skill.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+
+/**
+ * validate-skill.js
+ *
+ * Validates a Claude Code skill against best practices.
+ * Returns detailed findings with severity levels.
+ *
+ * Usage: node validate-skill.js <skill-path> [--json] [--fix]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const skillPath = args.find(a => !a.startsWith('--'));
+const jsonOutput = args.includes('--json');
+const autoFix = args.includes('--fix');
+
+if (!skillPath) {
+  console.error('Usage: node validate-skill.js <skill-path> [--json] [--fix]');
+  process.exit(1);
+}
+
+// Resolve skill path
+const resolvedPath = path.resolve(skillPath);
+const skillMdPath = path.join(resolvedPath, 'SKILL.md');
+
+if (!fs.existsSync(skillMdPath)) {
+  console.error(`Error: SKILL.md not found at ${skillMdPath}`);
+  process.exit(1);
+}
+
+// Findings storage
+const findings = [];
+
+function addFinding(category, severity, message, line = null, suggestion = null) {
+  findings.push({ category, severity, message, line, suggestion });
+}
+
+/**
+ * Parse YAML frontmatter
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { valid: false, data: null, raw: null };
+
+  const raw = match[1];
+  const data = {};
+  const lines = raw.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();
+
+      // Handle multi-line values (basic support)
+      if (value === '' || value === '|' || value === '>') {
+        // Skip complex multi-line for now
+        continue;
+      }
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      data[key] = value;
+    }
+  }
+
+  return { valid: true, data, raw };
+}
+
+/**
+ * Get body content (after frontmatter)
+ */
+function getBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1] : content;
+}
+
+// Read skill content
+const content = fs.readFileSync(skillMdPath, 'utf-8');
+const frontmatter = parseFrontmatter(content);
+const body = getBody(content);
+const lines = content.split('\n');
+
+// === VALIDATION CHECKS ===
+
+// Check 1: Frontmatter exists
+if (!frontmatter.valid) {
+  addFinding('STRUCTURE', 'error', 'Missing or invalid YAML frontmatter');
+} else {
+  // Check 2: Required fields
+  if (!frontmatter.data.name) {
+    addFinding('STRUCTURE', 'error', 'Missing required field: name');
+  } else {
+    // Check name format (hyphen-case)
+    const namePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    if (!namePattern.test(frontmatter.data.name)) {
+      addFinding('STRUCTURE', 'error',
+        `Invalid name format: "${frontmatter.data.name}" - must be hyphen-case (lowercase letters, numbers, hyphens)`);
+    }
+
+    // Check name matches directory
+    const dirName = path.basename(resolvedPath);
+    if (frontmatter.data.name !== dirName) {
+      addFinding('STRUCTURE', 'warning',
+        `Name "${frontmatter.data.name}" doesn't match directory "${dirName}"`);
+    }
+
+    // Check name length
+    if (frontmatter.data.name.length > 64) {
+      addFinding('STRUCTURE', 'error',
+        `Name exceeds 64 characters (${frontmatter.data.name.length})`);
+    }
+  }
+
+  if (!frontmatter.data.description) {
+    addFinding('STRUCTURE', 'error', 'Missing required field: description');
+  } else {
+    // Check description length
+    if (frontmatter.data.description.length > 1024) {
+      addFinding('DESCRIPTION', 'error',
+        `Description exceeds 1024 characters (${frontmatter.data.description.length})`);
+    }
+
+    // Check for third person
+    const desc = frontmatter.data.description.toLowerCase();
+    if (desc.startsWith('use this') || desc.startsWith('use when')) {
+      addFinding('DESCRIPTION', 'warning',
+        'Description should use third person ("This skill should be used when...") not second person',
+        null,
+        'Start with "This skill should be used when..." or similar third-person phrasing');
+    }
+
+    // Check for trigger phrases (quoted text)
+    const hasQuotedPhrases = /"[^"]+"|'[^']+'/.test(frontmatter.data.description);
+    if (!hasQuotedPhrases) {
+      addFinding('DESCRIPTION', 'warning',
+        'Description lacks quoted trigger phrases',
+        null,
+        'Add specific phrases users might say, e.g., "create a skill", "build a new skill"');
+    }
+
+    // Check if description is too detailed (might prevent activation)
+    if (frontmatter.data.description.length > 500 && !hasQuotedPhrases) {
+      addFinding('DESCRIPTION', 'info',
+        'Long description without trigger phrases may reduce activation reliability');
+    }
+  }
+}
+
+// Check 3: Second person violations
+const secondPersonPatterns = [
+  /\byou should\b/gi,
+  /\byou can\b/gi,
+  /\byou need\b/gi,
+  /\byou might\b/gi,
+  /\byou will\b/gi,
+  /\byou must\b/gi,
+  /\byour\b/gi
+];
+
+let secondPersonCount = 0;
+const secondPersonExamples = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  // Skip frontmatter
+  if (i < 3) continue;
+
+  for (const pattern of secondPersonPatterns) {
+    const matches = line.match(pattern);
+    if (matches) {
+      secondPersonCount += matches.length;
+      if (secondPersonExamples.length < 3) {
+        secondPersonExamples.push({ line: i + 1, text: line.trim().slice(0, 60) });
+      }
+    }
+  }
+}
+
+if (secondPersonCount > 0) {
+  addFinding('STYLE', 'error',
+    `Found ${secondPersonCount} instance(s) of second person language`,
+    secondPersonExamples[0]?.line,
+    'Convert to imperative form: "You should parse" → "Parse"');
+}
+
+// Check 4: Negative framing
+const negativePatterns = [
+  /\bdon't\b/gi,
+  /\bdo not\b/gi,
+  /\bnever\b/gi,
+  /\bavoid\b/gi,
+  /\bshould not\b/gi,
+  /\bshouldn't\b/gi,
+  /\bcan't\b/gi,
+  /\bcannot\b/gi
+];
+
+let negativeCount = 0;
+const negativeExamples = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  if (i < 3) continue;
+
+  for (const pattern of negativePatterns) {
+    const matches = line.match(pattern);
+    if (matches) {
+      negativeCount += matches.length;
+      if (negativeExamples.length < 3) {
+        negativeExamples.push({ line: i + 1, text: line.trim().slice(0, 60) });
+      }
+    }
+  }
+}
+
+if (negativeCount > 3) {
+  addFinding('STYLE', 'warning',
+    `Found ${negativeCount} instance(s) of negative framing`,
+    negativeExamples[0]?.line,
+    'Use positive framing: "Don\'t do X" → "Do Y instead"');
+}
+
+// Check 5: Body size
+const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+const lineCount = body.split('\n').length;
+
+if (wordCount > 5000) {
+  addFinding('SIZE', 'error',
+    `SKILL.md body is ${wordCount} words - strongly exceeds 2,000 word recommendation`,
+    null,
+    'Move detailed content to references/ directory');
+} else if (wordCount > 3500) {
+  addFinding('SIZE', 'warning',
+    `SKILL.md body is ${wordCount} words - exceeds 2,000 word recommendation`,
+    null,
+    'Consider moving detailed content to references/ directory');
+} else if (wordCount > 2000) {
+  addFinding('SIZE', 'info',
+    `SKILL.md body is ${wordCount} words - at upper limit of recommendation`);
+}
+
+// Check 6: Progressive disclosure
+const hasReferences = fs.existsSync(path.join(resolvedPath, 'references'));
+const hasScripts = fs.existsSync(path.join(resolvedPath, 'scripts'));
+
+if (wordCount > 2000 && !hasReferences) {
+  addFinding('DISCLOSURE', 'warning',
+    'Large SKILL.md without references/ directory - not using progressive disclosure',
+    null,
+    'Create references/ and move detailed content there');
+}
+
+// Check 7: Reference integrity
+const referencePaths = body.match(/`references\/[^`]+`|references\/[\w.-]+/g) || [];
+const scriptPaths = body.match(/`scripts\/[^`]+`|scripts\/[\w.-]+/g) || [];
+
+for (const ref of referencePaths) {
+  const cleanPath = ref.replace(/`/g, '');
+  const fullPath = path.join(resolvedPath, cleanPath);
+
+  if (!fs.existsSync(fullPath)) {
+    addFinding('BROKEN', 'error',
+      `Referenced file doesn't exist: ${cleanPath}`);
+  }
+}
+
+for (const ref of scriptPaths) {
+  const cleanPath = ref.replace(/`/g, '');
+  const fullPath = path.join(resolvedPath, cleanPath);
+
+  if (!fs.existsSync(fullPath)) {
+    addFinding('BROKEN', 'error',
+      `Referenced script doesn't exist: ${cleanPath}`);
+  }
+}
+
+// Check 8: Unreferenced resources
+if (hasReferences) {
+  const refDir = path.join(resolvedPath, 'references');
+  const refFiles = fs.readdirSync(refDir);
+
+  for (const file of refFiles) {
+    const isReferenced = body.includes(`references/${file}`) ||
+                         body.includes(`references/${path.basename(file, '.md')}`);
+    if (!isReferenced && file.endsWith('.md')) {
+      addFinding('DISCLOSURE', 'info',
+        `File references/${file} exists but may not be referenced in SKILL.md`);
+    }
+  }
+}
+
+if (hasScripts) {
+  const scriptDir = path.join(resolvedPath, 'scripts');
+  const scriptFiles = fs.readdirSync(scriptDir);
+
+  for (const file of scriptFiles) {
+    const isReferenced = body.includes(`scripts/${file}`);
+    if (!isReferenced) {
+      addFinding('DISCLOSURE', 'info',
+        `File scripts/${file} exists but may not be referenced in SKILL.md`);
+    }
+  }
+}
+
+// === OUTPUT ===
+
+const result = {
+  skill: {
+    path: resolvedPath,
+    name: frontmatter.data?.name || path.basename(resolvedPath),
+    wordCount,
+    lineCount,
+    hasReferences,
+    hasScripts
+  },
+  findings,
+  summary: {
+    errors: findings.filter(f => f.severity === 'error').length,
+    warnings: findings.filter(f => f.severity === 'warning').length,
+    info: findings.filter(f => f.severity === 'info').length,
+    passed: findings.filter(f => f.severity === 'error').length === 0
+  }
+};
+
+if (jsonOutput) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(`\n=== Skill Validation: ${result.skill.name} ===\n`);
+  console.log(`Path: ${result.skill.path}`);
+  console.log(`Words: ${result.skill.wordCount}`);
+  console.log(`Has references/: ${result.skill.hasReferences ? 'Yes' : 'No'}`);
+  console.log(`Has scripts/: ${result.skill.hasScripts ? 'Yes' : 'No'}`);
+  console.log();
+
+  if (findings.length === 0) {
+    console.log('✓ All checks passed!\n');
+  } else {
+    // Group by severity
+    const errors = findings.filter(f => f.severity === 'error');
+    const warnings = findings.filter(f => f.severity === 'warning');
+    const infos = findings.filter(f => f.severity === 'info');
+
+    if (errors.length > 0) {
+      console.log('ERRORS:');
+      for (const f of errors) {
+        console.log(`  ✗ [${f.category}] ${f.message}`);
+        if (f.line) console.log(`    Line ${f.line}`);
+        if (f.suggestion) console.log(`    Suggestion: ${f.suggestion}`);
+      }
+      console.log();
+    }
+
+    if (warnings.length > 0) {
+      console.log('WARNINGS:');
+      for (const f of warnings) {
+        console.log(`  ! [${f.category}] ${f.message}`);
+        if (f.line) console.log(`    Line ${f.line}`);
+        if (f.suggestion) console.log(`    Suggestion: ${f.suggestion}`);
+      }
+      console.log();
+    }
+
+    if (infos.length > 0) {
+      console.log('INFO:');
+      for (const f of infos) {
+        console.log(`  i [${f.category}] ${f.message}`);
+      }
+      console.log();
+    }
+
+    console.log(`Summary: ${result.summary.errors} error(s), ${result.summary.warnings} warning(s), ${result.summary.info} info(s)`);
+    console.log(`Status: ${result.summary.passed ? 'PASSED' : 'FAILED'}\n`);
+  }
+}
+
+// Exit with error code if validation failed
+process.exit(result.summary.passed ? 0 : 1);

package/src/skills/orchestration/SKILL.md

@@ -23,7 +23,7 @@ Complete each step in order before proceeding to the next.
 Run the plan status script to find existing plans:
 
 ```bash
-node ~/.claude/scripts/plan-status.js
+node ~/.claude/skills/orchestration/scripts/plan-status.js
 ```
 
 This returns a list of plans with their current status (draft, approved, in_progress, completed).

package/src/skills/orchestration/scripts/plan-status.js

@@ -10,7 +10,7 @@
  * file scanning.
  *
  * Usage:
- *   node ~/.claude/scripts/plan-status.js
+ *   node ~/.claude/skills/orchestration/scripts/plan-status.js
  *
  * Output:
  *   JSON object to stdout: