metame-cli 1.5.11 → 1.5.13

package/skills/skill-creator/scripts/align_all.py

@@ -0,0 +1,32 @@
+import os
+import sys
+import subprocess
+
+def align_all(skills_root):
+    if not os.path.exists(skills_root):
+        print(f"Error: {skills_root} not found")
+        return
+
+    stitch_script = os.path.join(os.path.dirname(__file__), "smart_stitch.py")
+    
+    count = 0
+    for item in os.listdir(skills_root):
+        skill_dir = os.path.join(skills_root, item)
+        if not os.path.isdir(skill_dir):
+            continue
+            
+        evolution_json = os.path.join(skill_dir, "evolution.json")
+        if os.path.exists(evolution_json):
+            print(f"Aligning {item}...")
+            # Run the smart_stitch script for this skill
+            subprocess.run([sys.executable, stitch_script, skill_dir])
+            count += 1
+            
+    print(f"\nFinished. Aligned {count} skills.")
+
+if __name__ == "__main__":
+    # Use standard skills path
+    skills_path = r"C:\Users\20515\.claude\skills"
+    if len(sys.argv) > 1:
+        skills_path = sys.argv[1]
+    align_all(skills_path)

package/skills/skill-creator/scripts/auto_evolve_hook.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+/**
+ * skill-creator Auto-Evolve Hook
+ *
+ * Runs as a Claude Code "Stop" hook. After each session:
+ *   1. Detects which skills were active in this session
+ *   2. Extracts tool failures and interaction signals
+ *   3. If ANTHROPIC_API_KEY is set: uses Haiku to generate structured insights
+ *      Otherwise: persists raw failure signals directly
+ *   4. Calls merge_evolution.py + smart_stitch.py to persist into each skill's SKILL.md
+ *
+ * Zero MetaMe dependency. Self-contained.
+ * Performance target: <50ms when no skills detected, <3s with Haiku analysis.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const { execSync } = require('child_process');
+
+// Paths derived from __dirname (scripts/) — works regardless of install location
+const SKILL_CREATOR_DIR = path.dirname(__dirname);  // scripts/ → skill-creator/
+const SKILLS_DIR = path.dirname(SKILL_CREATOR_DIR); // skill-creator/ → skills/
+const MERGE_SCRIPT = path.join(SKILL_CREATOR_DIR, 'scripts', 'merge_evolution.py');
+const STITCH_SCRIPT = path.join(SKILL_CREATOR_DIR, 'scripts', 'smart_stitch.py');
+
+const TAIL_BYTES = 40 * 1024; // 40KB — covers ~15-25 turns
+
+const IS_CODEX = process.argv.includes('--codex');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  (IS_CODEX ? mainCodex() : mainCC()).catch(() => {}).finally(() => process.exit(0));
+});
+
+// ── Claude Code mode: full transcript analysis ────────────────────────────────
+
+async function mainCC() {
+  let data;
+  try { data = JSON.parse(input); } catch { return; }
+
+  const transcriptPath = data.transcript_path;
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return;
+
+  const tail = readTail(transcriptPath, TAIL_BYTES);
+  if (!tail) return;
+
+  const installedSkills = getInstalledSkills();
+  if (installedSkills.length === 0) return;
+
+  const activeSkills = detectActiveSkills(tail, installedSkills);
+  if (activeSkills.length === 0) return;
+
+  const failures = extractFailures(tail);
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+
+  for (const skillName of activeSkills) {
+    const skillDir = path.join(SKILLS_DIR, skillName);
+    if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) continue;
+
+    let experience;
+    if (apiKey) {
+      experience = await analyzeWithHaiku(skillName, tail, failures, apiKey);
+    } else {
+      experience = buildRawExperience(failures);
+    }
+
+    if (!experience) continue;
+    persistExperience(skillDir, experience);
+  }
+}
+
+// ── Codex CLI mode: per-turn signal capture (no transcript available) ─────────
+// Codex notify fires on agent-turn-complete but passes no stdin data.
+// We can only record a timestamped turn event — no Haiku analysis possible.
+
+async function mainCodex() {
+  const signalFile = path.join(SKILLS_DIR, '.codex_turn_signals.jsonl');
+  const entry = JSON.stringify({ ts: new Date().toISOString(), cwd: process.cwd() }) + '\n';
+  try { fs.appendFileSync(signalFile, entry); } catch { /* non-fatal */ }
+  // No transcript → nothing to evolve right now.
+  // Signals accumulate and can be analyzed manually via /evolve.
+}
+
+// ── Transcript utilities ──────────────────────────────────────────────────────
+
+function readTail(filePath, maxBytes) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size === 0) return null;
+    const size = Math.min(stat.size, maxBytes);
+    const buf = Buffer.alloc(size);
+    const fd = fs.openSync(filePath, 'r');
+    try { fs.readSync(fd, buf, 0, size, Math.max(0, stat.size - size)); }
+    finally { fs.closeSync(fd); }
+    const text = buf.toString('utf8');
+    // Skip first (possibly truncated) line
+    const nl = text.indexOf('\n');
+    return nl >= 0 ? text.slice(nl + 1) : text;
+  } catch { return null; }
+}
+
+function extractFailures(tail) {
+  const failures = [];
+  for (const line of tail.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      const content = entry?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block.type === 'tool_result' && block.is_error === true) {
+          const errText = typeof block.content === 'string'
+            ? block.content
+            : (block.content || []).map(c => c.text || '').join('\n');
+          failures.push(errText.slice(0, 300));
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return failures;
+}
+
+// ── Skill detection ───────────────────────────────────────────────────────────
+
+function getInstalledSkills() {
+  try {
+    return fs.readdirSync(SKILLS_DIR).filter(name => {
+      const skillMd = path.join(SKILLS_DIR, name, 'SKILL.md');
+      return fs.existsSync(skillMd);
+    });
+  } catch { return []; }
+}
+
+function detectActiveSkills(tail, installedSkills) {
+  // A skill is "active" if its name appears in the transcript
+  // (skill bodies are injected into the system prompt when triggered)
+  return installedSkills.filter(name => tail.includes(name));
+}
+
+// ── Haiku analysis ────────────────────────────────────────────────────────────
+
+async function analyzeWithHaiku(skillName, tail, failures, apiKey) {
+  // Build a compact summary for Haiku (avoid sending full transcript)
+  const truncatedTail = tail.slice(-8000); // last ~8KB for prompt efficiency
+  const failureSummary = failures.length > 0
+    ? `Tool failures:\n${failures.slice(0, 5).map((f, i) => `${i + 1}. ${f}`).join('\n')}`
+    : 'No tool failures detected.';
+
+  const prompt = `You are analyzing a Claude Code session to extract experience for improving the "${skillName}" skill.
+
+Session tail (last portion of conversation):
+<session>
+${truncatedTail.slice(0, 6000)}
+</session>
+
+${failureSummary}
+
+Extract only concrete, reusable insights about the "${skillName}" skill. Respond with ONLY a JSON object or the string NO_EVOLUTION:
+
+{
+  "preferences": ["user preference observed, e.g. always use X format"],
+  "fixes": ["bug or workaround discovered, e.g. path needs quoting on Windows"],
+  "custom_prompts": "persistent instruction to inject, if any (or omit)"
+}
+
+Rules:
+- Only include insights directly related to "${skillName}"
+- "preferences": recurring user preferences (omit if none)
+- "fixes": concrete bugs/workarounds (omit if none)
+- "custom_prompts": only if a specific instruction should always apply (omit otherwise)
+- If nothing useful found, respond: NO_EVOLUTION`;
+
+  try {
+    const result = await callHaiku(prompt, apiKey);
+    if (!result || result.trim() === 'NO_EVOLUTION') return null;
+    const json = result.match(/\{[\s\S]*\}/)?.[0];
+    if (!json) return null;
+    const parsed = JSON.parse(json);
+    // Only return if there's actual content
+    const hasContent = (parsed.preferences?.length > 0) ||
+                       (parsed.fixes?.length > 0) ||
+                       parsed.custom_prompts;
+    return hasContent ? parsed : null;
+  } catch { return null; }
+}
+
+function callHaiku(prompt, apiKey) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 512,
+      messages: [{ role: 'user', content: prompt }],
+    });
+
+    const req = https.request({
+      hostname: 'api.anthropic.com',
+      path: '/v1/messages',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      timeout: 10000,
+    }, res => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          resolve(parsed?.content?.[0]?.text || null);
+        } catch { resolve(null); }
+      });
+    });
+
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    req.write(body);
+    req.end();
+  });
+}
+
+// ── Fallback: raw failure signals (no API key) ────────────────────────────────
+
+function buildRawExperience(failures) {
+  if (failures.length === 0) return null;
+  return {
+    fixes: failures.slice(0, 3).map(f => `[auto-captured] ${f.slice(0, 150)}`),
+  };
+}
+
+// ── Persist ───────────────────────────────────────────────────────────────────
+
+function persistExperience(skillDir, experience) {
+  try {
+    const jsonStr = JSON.stringify(experience).replace(/'/g, "\\'");
+    execSync(`python3 "${MERGE_SCRIPT}" "${skillDir}" '${jsonStr}'`, { stdio: 'ignore' });
+    execSync(`python3 "${STITCH_SCRIPT}" "${skillDir}"`, { stdio: 'ignore' });
+  } catch { /* non-fatal */ }
+}

package/skills/skill-creator/scripts/init_skill.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path>
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-api-helper --path skills/private
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"❌ Error: Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"✅ Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"❌ Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(
+        skill_name=skill_name,
+        skill_title=skill_title
+    )
+
+    skill_md_path = skill_dir / 'SKILL.md'
+    try:
+        skill_md_path.write_text(skill_content)
+        print("✅ Created SKILL.md")
+    except Exception as e:
+        print(f"❌ Error creating SKILL.md: {e}")
+        return None
+
+    # Create resource directories with example files
+    try:
+        # Create scripts/ directory with example script
+        scripts_dir = skill_dir / 'scripts'
+        scripts_dir.mkdir(exist_ok=True)
+        example_script = scripts_dir / 'example.py'
+        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+        example_script.chmod(0o755)
+        print("✅ Created scripts/example.py")
+
+        # Create references/ directory with example reference doc
+        references_dir = skill_dir / 'references'
+        references_dir.mkdir(exist_ok=True)
+        example_reference = references_dir / 'api_reference.md'
+        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+        print("✅ Created references/api_reference.md")
+
+        # Create assets/ directory with example asset placeholder
+        assets_dir = skill_dir / 'assets'
+        assets_dir.mkdir(exist_ok=True)
+        example_asset = assets_dir / 'example_asset.txt'
+        example_asset.write_text(EXAMPLE_ASSET)
+        print("✅ Created assets/example_asset.txt")
+    except Exception as e:
+        print(f"❌ Error creating resource directories: {e}")
+        return None
+
+    # Print next steps
+    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    print("2. Customize or delete the example files in scripts/, references/, and assets/")
+    print("3. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    if len(sys.argv) < 4 or sys.argv[2] != '--path':
+        print("Usage: init_skill.py <skill-name> --path <path>")
+        print("\nSkill name requirements:")
+        print("  - Kebab-case identifier (e.g., 'my-data-analyzer')")
+        print("  - Lowercase letters, digits, and hyphens only")
+        print("  - Max 64 characters")
+        print("  - Must match directory name exactly")
+        print("\nExamples:")
+        print("  init_skill.py my-new-skill --path skills/public")
+        print("  init_skill.py my-api-helper --path skills/private")
+        print("  init_skill.py custom-skill --path /custom/location")
+        sys.exit(1)
+
+    skill_name = sys.argv[1]
+    path = sys.argv[3]
+
+    print(f"🚀 Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    print()
+
+    result = init_skill(skill_name, path)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-creator/scripts/merge_evolution.py

@@ -0,0 +1,70 @@
+import os
+import sys
+import json
+import datetime
+
+def merge_evolution(skill_dir, new_data_json_str):
+    """
+    Merges new evolution data into existing evolution.json.
+    Deduplicates list items.
+    """
+    evolution_json_path = os.path.join(skill_dir, "evolution.json")
+    
+    # Load existing or create new
+    if os.path.exists(evolution_json_path):
+        try:
+            with open(evolution_json_path, 'r', encoding='utf-8') as f:
+                current_data = json.load(f)
+        except Exception:
+            current_data = {}
+    else:
+        current_data = {}
+
+    try:
+        new_data = json.loads(new_data_json_str)
+    except json.JSONDecodeError as e:
+        print(f"Error decoding new data JSON: {e}", file=sys.stderr)
+        return False
+
+    # Merge logic
+    # 1. Update timestamp
+    current_data['last_updated'] = datetime.datetime.now().isoformat()
+    
+    # 2. Merge Lists (preferences, fixes, contexts) with deduplication
+    for list_key in ['preferences', 'fixes', 'contexts']:
+        if list_key in new_data:
+            existing_list = current_data.get(list_key, [])
+            new_items = new_data[list_key]
+            if isinstance(new_items, list):
+                # Simple dedupe by string equality
+                for item in new_items:
+                    if item not in existing_list:
+                        existing_list.append(item)
+                current_data[list_key] = existing_list
+                
+    # 3. Overwrite/Append Custom Prompts (Concatenate if exists to preserve history? Or overwrite?)
+    # Decision: Overwrite if provided, as prompts usually need to be coherent. 
+    # Or, the Agent should have read the old one and combined it before sending here.
+    # We assume Agent sends the FINAL desired state for custom_prompts if it wants to merge.
+    if 'custom_prompts' in new_data:
+        current_data['custom_prompts'] = new_data['custom_prompts']
+
+    # 4. Update last_evolved_hash if provided
+    if 'last_evolved_hash' in new_data:
+        current_data['last_evolved_hash'] = new_data['last_evolved_hash']
+
+    # Save back
+    with open(evolution_json_path, 'w', encoding='utf-8') as f:
+        json.dump(current_data, f, indent=2, ensure_ascii=False)
+        
+    print(f"Successfully merged evolution data for {os.path.basename(skill_dir)}")
+    return True
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: python merge_evolution.py <skill_dir> <json_string>")
+        sys.exit(1)
+        
+    skill_dir = sys.argv[1]
+    json_str = sys.argv[2]
+    merge_evolution(skill_dir, json_str)