aiblueprint-cli 1.4.22 → 1.4.24

package/claude-code-config/skills/meta-skill-creator/scripts/init-skill.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+/**
+ * Skill Initializer - Creates a new skill from template
+ *
+ * Usage:
+ *   bun scripts/init-skill.ts <skill-name> --path <path>
+ *
+ * Examples:
+ *   bun scripts/init-skill.ts my-new-skill --path ~/.claude/skills
+ *   bun scripts/init-skill.ts my-api-helper --path .claude/skills
+ */
+
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "fs";
+import { join, resolve } from "path";
+
+const SKILL_TEMPLATE = `---
+name: {skill_name}
+description: [TODO: What the skill does and when to use it. Include trigger phrases like "use when..." or specific scenarios.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Quick Start
+
+[TODO: Immediate, actionable guidance - minimal working example]
+
+## Workflow
+
+[TODO: Step-by-step procedures if applicable]
+
+## Resources
+
+This skill includes example resource directories:
+
+### scripts/
+Executable code (TypeScript/Python/Bash) for automation tasks.
+
+### references/
+Documentation loaded into context as needed. Keep SKILL.md lean (<500 lines) and move detailed content here.
+
+### assets/
+Files used in output (templates, images, fonts) - not loaded into context.
+
+---
+
+**Delete unused directories.** Not every skill needs all three resource types.
+`;
+
+const EXAMPLE_SCRIPT = `#!/usr/bin/env bun
+/**
+ * Example helper script for {skill_name}
+ *
+ * Replace with actual implementation or delete if not needed.
+ */
+
+function main() {
+  console.log("This is an example script for {skill_name}");
+  // TODO: Add actual script logic here
+}
+
+main();
+`;
+
+const EXAMPLE_REFERENCE = `# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual content or delete if not needed.
+
+## When Reference Docs Are Useful
+
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+`;
+
+const EXAMPLE_ASSET = `# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual assets (templates, images, fonts) or delete if not needed.
+
+Asset files are NOT loaded into context - they're used in Claude's output.
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg
+- Fonts: .ttf, .woff2
+- Boilerplate: Project directories, starter files
+- Data: .csv, .json sample files
+`;
+
+function titleCase(skillName: string): string {
+  return skillName
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function initSkill(skillName: string, basePath: string): string | null {
+  const skillDir = resolve(basePath, skillName);
+
+  if (existsSync(skillDir)) {
+    console.log(`❌ Error: Skill directory already exists: ${skillDir}`);
+    return null;
+  }
+
+  try {
+    mkdirSync(skillDir, { recursive: true });
+    console.log(`✅ Created skill directory: ${skillDir}`);
+  } catch (e) {
+    console.log(`❌ Error creating directory: ${e}`);
+    return null;
+  }
+
+  const skillTitle = titleCase(skillName);
+
+  // Create SKILL.md
+  const skillContent = SKILL_TEMPLATE.replace(/{skill_name}/g, skillName).replace(
+    /{skill_title}/g,
+    skillTitle
+  );
+  const skillMdPath = join(skillDir, "SKILL.md");
+  try {
+    writeFileSync(skillMdPath, skillContent);
+    console.log("✅ Created SKILL.md");
+  } catch (e) {
+    console.log(`❌ Error creating SKILL.md: ${e}`);
+    return null;
+  }
+
+  try {
+    // Create scripts/
+    const scriptsDir = join(skillDir, "scripts");
+    mkdirSync(scriptsDir);
+    const exampleScript = join(scriptsDir, "example.ts");
+    writeFileSync(
+      exampleScript,
+      EXAMPLE_SCRIPT.replace(/{skill_name}/g, skillName)
+    );
+    chmodSync(exampleScript, 0o755);
+    console.log("✅ Created scripts/example.ts");
+
+    // Create references/
+    const referencesDir = join(skillDir, "references");
+    mkdirSync(referencesDir);
+    writeFileSync(
+      join(referencesDir, "api-reference.md"),
+      EXAMPLE_REFERENCE.replace(/{skill_title}/g, skillTitle)
+    );
+    console.log("✅ Created references/api-reference.md");
+
+    // Create assets/
+    const assetsDir = join(skillDir, "assets");
+    mkdirSync(assetsDir);
+    writeFileSync(join(assetsDir, "example-asset.txt"), EXAMPLE_ASSET);
+    console.log("✅ Created assets/example-asset.txt");
+  } catch (e) {
+    console.log(`❌ Error creating resource directories: ${e}`);
+    return null;
+  }
+
+  console.log(`\n✅ Skill '${skillName}' initialized at ${skillDir}`);
+  console.log("\nNext steps:");
+  console.log("1. Edit SKILL.md to complete the TODO items");
+  console.log("2. Customize or delete example files in scripts/, references/, assets/");
+  console.log("3. Run validator: bun scripts/validate.ts " + skillDir);
+
+  return skillDir;
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 3 || args[1] !== "--path") {
+    console.log("Usage: bun scripts/init-skill.ts <skill-name> --path <path>");
+    console.log("\nSkill name requirements:");
+    console.log("  - Hyphen-case (e.g., 'data-analyzer')");
+    console.log("  - Lowercase letters, digits, and hyphens only");
+    console.log("  - Max 64 characters");
+    console.log("\nExamples:");
+    console.log("  bun scripts/init-skill.ts my-skill --path ~/.claude/skills");
+    console.log("  bun scripts/init-skill.ts api-helper --path .claude/skills");
+    process.exit(1);
+  }
+
+  const skillName = args[0];
+  const basePath = args[2];
+
+  console.log(`🚀 Initializing skill: ${skillName}`);
+  console.log(`   Location: ${basePath}\n`);
+
+  const result = initSkill(skillName, basePath);
+  process.exit(result ? 0 : 1);
+}

package/claude-code-config/skills/meta-skill-creator/scripts/package-skill.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+/**
+ * Skill Packager - Creates a distributable .skill file
+ *
+ * Usage:
+ *   bun scripts/package-skill.ts <path/to/skill-folder> [output-directory]
+ *
+ * Examples:
+ *   bun scripts/package-skill.ts ~/.claude/skills/my-skill
+ *   bun scripts/package-skill.ts ~/.claude/skills/my-skill ./dist
+ */
+
+import { existsSync, mkdirSync, readdirSync, statSync, readFileSync } from "fs";
+import { join, resolve, relative, basename } from "path";
+import { validateSkill } from "./validate";
+
+async function getAllFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  function walk(currentDir: string) {
+    const entries = readdirSync(currentDir);
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      } else {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+async function packageSkill(
+  skillPath: string,
+  outputDir?: string
+): Promise<string | null> {
+  const resolvedPath = resolve(skillPath);
+
+  if (!existsSync(resolvedPath)) {
+    console.log(`❌ Error: Skill folder not found: ${resolvedPath}`);
+    return null;
+  }
+
+  const stat = statSync(resolvedPath);
+  if (!stat.isDirectory()) {
+    console.log(`❌ Error: Path is not a directory: ${resolvedPath}`);
+    return null;
+  }
+
+  const skillMdPath = join(resolvedPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) {
+    console.log(`❌ Error: SKILL.md not found in ${resolvedPath}`);
+    return null;
+  }
+
+  // Validate skill
+  console.log("🔍 Validating skill...");
+  const { valid, message } = validateSkill(resolvedPath);
+  if (!valid) {
+    console.log(`❌ Validation failed: ${message}`);
+    console.log("   Please fix the validation errors before packaging.");
+    return null;
+  }
+  console.log(`✅ ${message}\n`);
+
+  // Determine output location
+  const skillName = basename(resolvedPath);
+  const outputPath = outputDir ? resolve(outputDir) : process.cwd();
+
+  if (outputDir && !existsSync(outputPath)) {
+    mkdirSync(outputPath, { recursive: true });
+  }
+
+  const skillFilename = join(outputPath, `${skillName}.skill`);
+
+  // Create zip file using Bun's built-in zip
+  try {
+    const files = await getAllFiles(resolvedPath);
+    const zipEntries: { path: string; data: Uint8Array }[] = [];
+
+    for (const filePath of files) {
+      const relativePath = join(skillName, relative(resolvedPath, filePath));
+      const data = readFileSync(filePath);
+      zipEntries.push({ path: relativePath, data });
+      console.log(`  Added: ${relativePath}`);
+    }
+
+    // Use Bun's native zip writer
+    const zipFile = Bun.file(skillFilename);
+    const writer = zipFile.writer();
+
+    // Create a simple zip manually or use a library
+    // For now, use the 'archiver' pattern with Bun.spawn
+    const { spawn } = await import("child_process");
+
+    // Create zip using system zip command (cross-platform approach)
+    const parentDir = resolve(resolvedPath, "..");
+    const result = Bun.spawnSync(["zip", "-r", skillFilename, skillName], {
+      cwd: parentDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `zip command failed: ${Buffer.from(result.stderr).toString()}`
+      );
+    }
+
+    console.log(`\n✅ Successfully packaged skill to: ${skillFilename}`);
+    return skillFilename;
+  } catch (e) {
+    console.log(`❌ Error creating .skill file: ${e}`);
+    return null;
+  }
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.log(
+      "Usage: bun scripts/package-skill.ts <path/to/skill-folder> [output-directory]"
+    );
+    console.log("\nExamples:");
+    console.log("  bun scripts/package-skill.ts ~/.claude/skills/my-skill");
+    console.log("  bun scripts/package-skill.ts ~/.claude/skills/my-skill ./dist");
+    process.exit(1);
+  }
+
+  const skillPath = args[0];
+  const outputDir = args[1];
+
+  console.log(`📦 Packaging skill: ${skillPath}`);
+  if (outputDir) {
+    console.log(`   Output directory: ${outputDir}`);
+  }
+  console.log();
+
+  const result = await packageSkill(skillPath, outputDir);
+  process.exit(result ? 0 : 1);
+}

package/claude-code-config/skills/meta-skill-creator/scripts/validate.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env bun
+/**
+ * Skill Validator - Validates skill structure and frontmatter
+ *
+ * Usage:
+ *   bun scripts/validate.ts <skill-directory>
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+
+const ALLOWED_PROPERTIES = new Set([
+  "name",
+  "description",
+  "license",
+  "metadata",
+  "allowed-tools",
+  "disable-model-invocation",
+  "user-invocable",
+  "argument-hint",
+  "model",
+  "context",
+  "agent",
+  "hooks",
+]);
+
+interface ValidationResult {
+  valid: boolean;
+  message: string;
+}
+
+export function validateSkill(skillPath: string): ValidationResult {
+  const skillMdPath = join(skillPath, "SKILL.md");
+
+  if (!existsSync(skillMdPath)) {
+    return { valid: false, message: "SKILL.md not found" };
+  }
+
+  const content = readFileSync(skillMdPath, "utf-8");
+
+  if (!content.startsWith("---")) {
+    return { valid: false, message: "No YAML frontmatter found" };
+  }
+
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return { valid: false, message: "Invalid frontmatter format" };
+  }
+
+  let frontmatter: Record<string, unknown>;
+  try {
+    frontmatter = parseYaml(frontmatterMatch[1]);
+    if (typeof frontmatter !== "object" || frontmatter === null) {
+      return { valid: false, message: "Frontmatter must be a YAML dictionary" };
+    }
+  } catch (e) {
+    return { valid: false, message: `Invalid YAML in frontmatter: ${e}` };
+  }
+
+  const unexpectedKeys = Object.keys(frontmatter).filter(
+    (key) => !ALLOWED_PROPERTIES.has(key)
+  );
+  if (unexpectedKeys.length > 0) {
+    return {
+      valid: false,
+      message: `Unexpected key(s) in frontmatter: ${unexpectedKeys.join(", ")}. Allowed: ${[...ALLOWED_PROPERTIES].sort().join(", ")}`,
+    };
+  }
+
+  const name = frontmatter.name;
+  if (name !== undefined) {
+    if (typeof name !== "string") {
+      return { valid: false, message: `Name must be a string` };
+    }
+    const trimmedName = name.trim();
+    if (trimmedName) {
+      if (!/^[a-z0-9-]+$/.test(trimmedName)) {
+        return {
+          valid: false,
+          message: `Name '${trimmedName}' should be hyphen-case (lowercase letters, digits, and hyphens only)`,
+        };
+      }
+      if (
+        trimmedName.startsWith("-") ||
+        trimmedName.endsWith("-") ||
+        trimmedName.includes("--")
+      ) {
+        return {
+          valid: false,
+          message: `Name '${trimmedName}' cannot start/end with hyphen or contain consecutive hyphens`,
+        };
+      }
+      if (trimmedName.length > 64) {
+        return {
+          valid: false,
+          message: `Name is too long (${trimmedName.length} characters). Maximum is 64 characters.`,
+        };
+      }
+    }
+  }
+
+  const description = frontmatter.description;
+  if (description !== undefined) {
+    if (typeof description !== "string") {
+      return { valid: false, message: `Description must be a string` };
+    }
+    const trimmedDesc = description.trim();
+    if (trimmedDesc) {
+      if (trimmedDesc.includes("<") || trimmedDesc.includes(">")) {
+        return {
+          valid: false,
+          message: "Description cannot contain angle brackets (< or >)",
+        };
+      }
+      if (trimmedDesc.length > 1024) {
+        return {
+          valid: false,
+          message: `Description is too long (${trimmedDesc.length} characters). Maximum is 1024 characters.`,
+        };
+      }
+    }
+  }
+
+  return { valid: true, message: "Skill is valid!" };
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.length !== 1) {
+    console.log("Usage: bun scripts/validate.ts <skill_directory>");
+    process.exit(1);
+  }
+
+  const { valid, message } = validateSkill(args[0]);
+  console.log(message);
+  process.exit(valid ? 0 : 1);
+}