@icarusmx/creta 1.5.12 → 1.5.14

package/lib/exercises/12-install-skills.md

@@ -0,0 +1,755 @@
+# install-skills Command Design
+
+**Exercise**: Design a safe, intelligent skill installer inspired by art-vandeley
+
+## Overview
+
+The `install-skills` command automates skill setup by:
+1. Analyzing the project structure (using git analytics)
+2. Recommending 3 most relevant skills from a registry
+3. Installing skills to `~/.claude/skills/` directory
+4. Validating skill structure (SKILL.md, scripts, permissions)
+5. Optionally updating project's `.claude/CLAUDE.md`
+
+**Inspired by:** The art-vandeley skill - the "importer-exporter of well-architected skills"
+
+## Command Behavior
+
+```bash
+# Via creta CLI
+creta install-skills
+
+# Direct installation (one-liner)
+curl -s https://skills.icarus.mx/install.sh | bash -s art-vandeley
+
+# Manual installation
+mkdir -p ~/.claude/skills/art-vandeley
+curl -o ~/.claude/skills/art-vandeley/SKILL.md https://vandeley.art/art-vandeley.md
+```
+
+### Interactive Flow
+
+```
+🔍 Analyzing project structure...
+   - Detected: React + Express (Node.js)
+   - Git commits: 247
+   - Files: 89
+
+📦 Recommended skills for your project:
+
+   1. component-review - Analyze React components for best practices
+   2. api-security - Review Express endpoints for security issues
+   3. refactor-detector - Suggest refactors for files over 300 lines
+
+❓ Install these skills? [Y/n]: _
+```
+
+## Real-World Skill Structure (art-vandeley)
+
+Skills installed to `~/.claude/skills/[skill-name]/`:
+
+```
+~/.claude/skills/art-vandeley/
+├── SKILL.md              # Claude's instructions (required)
+├── README.md             # Human documentation (required)
+└── scripts/              # Helper utilities (optional)
+    ├── analyze-git.sh
+    ├── create-architecture.sh
+    ├── create-sequence.sh
+    ├── create-erd.sh
+    ├── create-interfaces.sh
+    └── create-class-diagram.sh
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: art-vandeley
+description: Create comprehensive Spanish README.md documentation and Mermaid diagrams
+allowed-tools: [Read, Write, Glob, Grep, Bash, Task]
+---
+
+# Art Vandeley - Documentation Architect
+
+[Detailed instructions for Claude on how to use this skill...]
+
+## When to Invoke
+[Trigger conditions...]
+
+## Core Responsibilities
+[What the skill does...]
+
+## Workflow Protocol
+[Step-by-step process...]
+```
+
+**Key components:**
+1. **Frontmatter** - YAML with name, description, allowed-tools
+2. **Instructions** - Detailed guidance for Claude
+3. **Triggers** - When to activate this skill
+4. **Workflow** - Step-by-step protocol
+
+## Project Analysis Strategy (Real Implementation)
+
+### Git-Based Detection
+
+Based on art-vandeley's `analyze-git.sh`:
+
+```bash
+#!/bin/bash
+# Detect tech stack from project files
+
+detect_tech_stack() {
+    # Svelte
+    if [ -f "svelte.config.js" ] || grep -q "\"svelte\"" package.json 2>/dev/null; then
+        echo "svelte"
+    # React
+    elif grep -q "\"react\"" package.json 2>/dev/null; then
+        echo "react"
+    # Vue
+    elif grep -q "\"vue\"" package.json 2>/dev/null; then
+        echo "vue"
+    # Python
+    elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+        echo "python"
+    # Rust
+    elif [ -f "Cargo.toml" ]; then
+        echo "rust"
+    # Go
+    elif [ -f "go.mod" ]; then
+        echo "go"
+    # Node.js generic
+    elif [ -f "package.json" ]; then
+        echo "nodejs"
+    else
+        echo "unknown"
+    fi
+}
+
+# Output structured JSON
+cat <<EOF
+{
+  "tech_stack": "$(detect_tech_stack)",
+  "commit_count": $(git rev-list --count HEAD),
+  "file_count": $(find . -type f | wc -l),
+  "has_tests": $([ -d "test" ] || [ -d "__tests__" ] && echo "true" || echo "false")
+}
+EOF
+```
+
+### Old Simple Detection (Reference)
+
+```javascript
+const analyzers = {
+  // Tech stack detection
+  react: () => hasFile('package.json') && hasDep('react'),
+  express: () => hasFile('package.json') && hasDep('express'),
+  svelte: () => hasFile('package.json') && hasDep('svelte'),
+
+  // Project characteristics
+  largeCodebase: () => countFiles('**/*.js') > 100,
+  hasTests: () => hasFile('**/*.test.js'),
+  activeRepo: () => gitCommitCount() > 50,
+}
+```
+
+### Skill Recommendation Matrix
+
+| Project Type | Recommended Skills |
+|-------------|-------------------|
+| React + Large | component-review, refactor-detector, bundle-analyzer |
+| Express API | api-security, endpoint-review, performance-audit |
+| Svelte | component-review, store-analyzer, bundle-optimizer |
+| Open Source | changelog-generator, release-notes, contributor-guide |
+
+## Safe Implementation Approach
+
+### Dry-Run Mode (Default)
+
+```bash
+npm run install-skills --dry-run
+
+# Output:
+Would create:
+  .skillful/skills/component-review/SKILL.md
+  .skillful/skills/api-security/SKILL.md
+  .skillful/skills/refactor-detector/SKILL.md
+
+Would update .claude/CLAUDE.md with:
+  ## Skillful Framework
+  Available skills: component-review, api-security, refactor-detector
+```
+
+### Actual Installation (Opt-in)
+
+```bash
+npm run install-skills --confirm
+```
+
+Only runs after user explicitly confirms.
+
+## CLAUDE.md Integration
+
+### Auto-Generated Section
+
+```markdown
+## Skillful Framework
+This project uses Skillful for progressive skill loading.
+
+Available skills in `.skillful/skills/`:
+- **component-review** - Analyze React components for best practices
+- **api-security** - Review Express endpoints for security issues
+- **refactor-detector** - Suggest refactors for files over 300+ lines
+
+Use skills via the Skill tool when tasks match skill descriptions.
+Load only when needed to preserve context window.
+```
+
+### Smart Merging
+
+If `.claude/CLAUDE.md` already exists:
+- Detect existing "Skillful Framework" section
+- Update skill list without touching other sections
+- Preserve user customizations
+
+If doesn't exist:
+- Prompt: "Create .claude/CLAUDE.md with Skillful section? [Y/n]"
+- Create minimal file with just framework instructions
+
+## Skill Source Strategy (art-vandeley approach)
+
+### Phase 1: Registry-Based Installation
+
+Art-vandeley uses a **remote registry** approach with curl:
+
+```bash
+# 1. Analyze project and detect tech stack
+ANALYTICS=$(bash analyze-git.sh)
+TECH_STACK=$(echo "$ANALYTICS" | jq -r '.tech_stack')
+
+# 2. Fetch skills registry
+REGISTRY=$(curl -s https://vandeley.art/skills/registry.json)
+
+# 3. Find appropriate skill for tech stack
+SKILL_URL=$(echo "$REGISTRY" | jq -r ".skills[\"skillful-${TECH_STACK}\"].url")
+
+# 4. Download skill template
+SKILL_CONTENT=$(curl -s "https://vandeley.art${SKILL_URL}")
+
+# 5. Install to ~/.claude/skills/
+mkdir -p ~/.claude/skills/skillful-${TECH_STACK}
+echo "$SKILL_CONTENT" > ~/.claude/skills/skillful-${TECH_STACK}/SKILL.md
+```
+
+**Registry format (registry.json):**
+```json
+{
+  "skills": {
+    "art-vandeley": {
+      "name": "art-vandeley",
+      "description": "Spanish README documentation architect",
+      "url": "/art-vandeley.md",
+      "category": "documentation",
+      "tags": ["readme", "mermaid", "spanish"]
+    },
+    "skillful-svelte": {
+      "name": "skillful-svelte",
+      "description": "Svelte 5 documentation specialist",
+      "url": "/skillful/svelte/SKILL.md",
+      "category": "framework",
+      "tags": ["svelte", "documentation"]
+    },
+    "skillful-react": {
+      "name": "skillful-react",
+      "description": "React documentation specialist",
+      "url": "/skillful/react/SKILL.md",
+      "category": "framework",
+      "tags": ["react", "documentation"]
+    }
+  }
+}
+```
+
+### Phase 2: Bundled Skills Fallback
+
+If curl fails (offline mode), fall back to bundled skills:
+
+```
+creta/lib/bundled-skills/
+  art-vandeley/
+    SKILL.md
+    README.md
+    scripts/
+  incident-report/
+  vim-architect/
+```
+
+Copy to `~/.claude/skills/` during installation.
+
+## Safety Features
+
+### 1. Never Overwrite
+
+```javascript
+if (fs.existsSync('.skillful/skills/component-review')) {
+  console.log('⚠️  component-review already exists, skipping...')
+  continue
+}
+```
+
+### 2. Backup Before Changes
+
+```javascript
+if (fs.existsSync('.claude/CLAUDE.md')) {
+  fs.copyFileSync(
+    '.claude/CLAUDE.md',
+    `.claude/CLAUDE.md.backup-${Date.now()}`
+  )
+}
+```
+
+### 3. Rollback Support
+
+```bash
+npm run install-skills --rollback
+```
+
+Restore from most recent backup.
+
+### 4. Validation (Real Implementation)
+
+Based on art-vandeley's structure:
+
+```javascript
+function validateSkill(skillPath) {
+  const skillMdPath = `${skillPath}/SKILL.md`
+  const readmePath = `${skillPath}/README.md`
+
+  // 1. Check required files exist
+  if (!fs.existsSync(skillMdPath)) {
+    throw new Error(`Missing SKILL.md in ${skillPath}`)
+  }
+  if (!fs.existsSync(readmePath)) {
+    console.warn(`⚠️  Missing README.md in ${skillPath}`)
+  }
+
+  const skillMd = fs.readFileSync(skillMdPath, 'utf8')
+
+  // 2. Validate YAML frontmatter
+  const frontmatterMatch = skillMd.match(/^---\n([\s\S]*?)\n---/)
+  if (!frontmatterMatch) {
+    throw new Error('Invalid SKILL.md: missing YAML frontmatter')
+  }
+
+  // 3. Parse frontmatter
+  const frontmatter = parseFrontmatter(frontmatterMatch[1])
+
+  // Required fields
+  if (!frontmatter.name) throw new Error('Missing "name" in frontmatter')
+  if (!frontmatter.description) throw new Error('Missing "description" in frontmatter')
+  if (!frontmatter['allowed-tools']) {
+    console.warn('⚠️  No "allowed-tools" specified - skill has access to all tools')
+  }
+
+  // 4. Validate allowed-tools is array
+  if (frontmatter['allowed-tools'] && !Array.isArray(frontmatter['allowed-tools'])) {
+    throw new Error('allowed-tools must be an array')
+  }
+
+  // 5. Check scripts directory (optional but recommended)
+  const scriptsPath = `${skillPath}/scripts`
+  if (fs.existsSync(scriptsPath)) {
+    // Verify scripts are executable
+    const scripts = fs.readdirSync(scriptsPath)
+    scripts.forEach(script => {
+      const scriptPath = `${scriptsPath}/${script}`
+      const stat = fs.statSync(scriptPath)
+      if (!stat.mode & 0o111) {
+        console.warn(`⚠️  Script not executable: ${script}`)
+        console.log(`   Fix: chmod +x ${scriptPath}`)
+      }
+    })
+  }
+
+  return {
+    valid: true,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    hasScripts: fs.existsSync(scriptsPath),
+    scriptCount: fs.existsSync(scriptsPath) ? fs.readdirSync(scriptsPath).length : 0
+  }
+}
+
+function parseFrontmatter(yaml) {
+  // Simple YAML parser for frontmatter
+  const lines = yaml.split('\n')
+  const data = {}
+
+  for (const line of lines) {
+    if (line.includes(':')) {
+      const [key, ...valueParts] = line.split(':')
+      let value = valueParts.join(':').trim()
+
+      // Handle arrays: [Read, Write, Bash]
+      if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(s => s.trim())
+      }
+
+      data[key.trim()] = value
+    }
+  }
+
+  return data
+}
+```
+
+**Validation checks:**
+1. ✅ SKILL.md exists (required)
+2. ✅ README.md exists (recommended)
+3. ✅ Frontmatter has name, description
+4. ✅ allowed-tools is valid array
+5. ✅ Scripts are executable (if present)
+
+## Example Output
+
+### Using creta CLI
+
+```bash
+$ creta install-skills
+
+🎯 Skill Installer (art-vandeley approach)
+
+🔍 Analyzing project...
+   📊 Running git analytics...
+   ✓ Tech stack: svelte
+   ✓ Commits: 247
+   ✓ Files: 89
+   ✓ Has tests: true
+
+📡 Fetching skills registry...
+   ✓ Connected to https://vandeley.art/skills/registry.json
+
+📦 Recommended skills for Svelte projects:
+   1. ✓ art-vandeley - Spanish README documentation
+   2. ✓ skillful-svelte - Svelte 5 documentation specialist
+   3. ✓ vim-architect - File navigation with fold markers
+
+❓ Install these skills? [Y/n]: Y
+
+📥 Installing skills to ~/.claude/skills/...
+
+   [1/3] art-vandeley
+   ✓ Downloaded SKILL.md (10.9 KB)
+   ✓ Downloaded README.md (3.5 KB)
+   ✓ Downloaded 6 scripts
+   ✓ Made scripts executable
+   ✓ Validated skill structure
+
+   [2/3] skillful-svelte
+   ✓ Downloaded SKILL.md (8.2 KB)
+   ✓ Validated skill structure
+
+   [3/3] vim-architect
+   ✓ Downloaded SKILL.md (6.1 KB)
+   ✓ Downloaded README.md (2.8 KB)
+   ✓ Validated skill structure
+
+📝 Update .claude/CLAUDE.md? [Y/n]: Y
+   ✓ Backed up to .claude/CLAUDE.md.backup-1698260400
+   ✓ Added skills section
+
+✨ Installation complete!
+
+Installed skills:
+  ~/.claude/skills/art-vandeley/
+  ~/.claude/skills/skillful-svelte/
+  ~/.claude/skills/vim-architect/
+
+Next steps:
+  - Try: "Document this project" (triggers art-vandeley)
+  - View: ~/.claude/skills/art-vandeley/README.md
+  - Add more: creta install-skills --add
+
+📚 Docs: https://icarus.mx/creta/skills
+```
+
+### Manual Installation (One-liner)
+
+```bash
+$ curl -s https://vandeley.art/install.sh | bash -s art-vandeley
+
+🔽 Installing art-vandeley...
+   ✓ Created ~/.claude/skills/art-vandeley/
+   ✓ Downloaded SKILL.md
+   ✓ Downloaded README.md
+   ✓ Downloaded scripts (6 files)
+   ✓ Made scripts executable
+   ✓ Validated installation
+
+✅ art-vandeley installed successfully!
+
+Try: "Document this project" in Claude Code
+Docs: https://vandeley.art/art-vandeley
+```
+
+## Edge Cases
+
+### No package.json
+
+```
+⚠️  No package.json found.
+   Cannot analyze project type.
+
+   Install default skills? [Y/n]: _
+   Default: code-review, bug-investigator, refactor-detector
+```
+
+### Empty/New Project
+
+```
+🆕 New project detected!
+
+   Choose skill category:
+   1. Web Development (React, Vue, Svelte)
+   2. API Development (Express, Fastify)
+   3. CLI Tools (Node.js scripts)
+   4. General Purpose (code review, refactoring)
+
+   Select [1-4]: _
+```
+
+### Existing Skills
+
+```
+Found existing skills:
+  - custom-validator (user-created)
+  - legacy-analyzer (project-specific)
+
+Keep these? [Y/n]: Y
+
+Adding new skills alongside existing ones...
+```
+
+## User Control
+
+### Flags
+
+```bash
+--dry-run          # Show what would happen (default)
+--confirm          # Actually run installation
+--add              # Add more skills to existing setup
+--remove           # Remove skills interactively
+--list             # Show available skills
+--registry <url>   # Custom skill source
+--no-claude        # Skip CLAUDE.md update
+--force            # Overwrite existing skills
+```
+
+### Configuration File
+
+`.skillfulrc.json`:
+```json
+{
+  "autoInstall": false,
+  "defaultSkills": ["code-review", "bug-investigator"],
+  "skillSources": [
+    "bundled",
+    "https://skills.icarus.mx/registry"
+  ],
+  "updateClaude": true
+}
+```
+
+## Complete Installation Script Example
+
+Based on art-vandeley's pattern:
+
+```bash
+#!/bin/bash
+# install-skill.sh - Install a skill to ~/.claude/skills/
+# Usage: ./install-skill.sh <skill-name> [registry-url]
+
+set -e
+
+SKILL_NAME="$1"
+REGISTRY_URL="${2:-https://vandeley.art/skills/registry.json}"
+SKILLS_DIR="$HOME/.claude/skills"
+
+echo "🔽 Installing ${SKILL_NAME}..."
+
+# 1. Fetch registry
+echo "   📡 Fetching registry..."
+REGISTRY=$(curl -s "$REGISTRY_URL")
+
+# 2. Get skill info
+SKILL_URL=$(echo "$REGISTRY" | jq -r ".skills[\"${SKILL_NAME}\"].url")
+if [ "$SKILL_URL" = "null" ]; then
+  echo "   ❌ Skill '${SKILL_NAME}' not found in registry"
+  exit 1
+fi
+
+# 3. Create skill directory
+SKILL_DIR="${SKILLS_DIR}/${SKILL_NAME}"
+mkdir -p "$SKILL_DIR"
+echo "   ✓ Created ${SKILL_DIR}/"
+
+# 4. Download SKILL.md
+echo "   ⬇️  Downloading SKILL.md..."
+curl -s "https://vandeley.art${SKILL_URL}" -o "${SKILL_DIR}/SKILL.md"
+echo "   ✓ Downloaded SKILL.md"
+
+# 5. Download README.md (if exists)
+README_URL="${SKILL_URL/SKILL.md/README.md}"
+if curl -s -f "https://vandeley.art${README_URL}" -o "${SKILL_DIR}/README.md" 2>/dev/null; then
+  echo "   ✓ Downloaded README.md"
+fi
+
+# 6. Download scripts directory (if exists)
+SCRIPTS_URL="${SKILL_URL%/*}/scripts"
+SCRIPTS_DIR="${SKILL_DIR}/scripts"
+
+# Try to list scripts
+SCRIPTS=$(curl -s "https://vandeley.art${SCRIPTS_URL}/" 2>/dev/null | grep -oP 'href="\K[^"]+\.sh' || echo "")
+
+if [ -n "$SCRIPTS" ]; then
+  mkdir -p "$SCRIPTS_DIR"
+  echo "   ⬇️  Downloading scripts..."
+
+  while IFS= read -r script; do
+    curl -s "https://vandeley.art${SCRIPTS_URL}/${script}" -o "${SCRIPTS_DIR}/${script}"
+    chmod +x "${SCRIPTS_DIR}/${script}"
+  done <<< "$SCRIPTS"
+
+  SCRIPT_COUNT=$(echo "$SCRIPTS" | wc -l)
+  echo "   ✓ Downloaded ${SCRIPT_COUNT} scripts"
+  echo "   ✓ Made scripts executable"
+fi
+
+# 7. Validate installation
+echo "   🔍 Validating installation..."
+
+if [ ! -f "${SKILL_DIR}/SKILL.md" ]; then
+  echo "   ❌ Validation failed: SKILL.md missing"
+  exit 1
+fi
+
+# Check frontmatter
+if ! grep -q "^---" "${SKILL_DIR}/SKILL.md"; then
+  echo "   ❌ Validation failed: Invalid SKILL.md format"
+  exit 1
+fi
+
+echo "   ✓ Validated skill structure"
+
+# 8. Success
+echo ""
+echo "✅ ${SKILL_NAME} installed successfully!"
+echo ""
+echo "Location: ${SKILL_DIR}/"
+echo "Try it: Mention its use case in Claude Code"
+echo ""
+```
+
+## Implementation Notes
+
+**art-vandeley approach:**
+- ✅ Registry-based with curl (network required)
+- ✅ Skills installed to `~/.claude/skills/` (global)
+- ✅ Validation checks SKILL.md structure
+- ✅ Scripts made executable automatically
+- ✅ Graceful fallback if optional files missing
+
+**Key principles:**
+- Use remote registry for latest versions
+- Fall back to bundled skills if offline
+- Prioritize safety over convenience
+- Make everything reversible
+- Never touch files without explicit confirmation
+- Provide clear output showing exactly what happened
+- Skills are user-level, not project-level
+
+## Future Enhancements
+
+1. **Skill Marketplace** - Browse/search community skills
+2. **Skill Updates** - `npm run update-skills` to get latest versions
+3. **Skill Generator** - `npm run create-skill` to scaffold new skills
+4. **Analytics** - Track which skills are most useful
+5. **Dependencies** - Skills that require other skills
+6. **Skill Packs** - Pre-configured bundles (frontend-pack, backend-pack)
+
+## How Claude Code Discovers Skills
+
+**Skill Discovery Protocol:**
+
+```bash
+# 1. User triggers a skill use case
+User: "Document this project"
+
+# 2. Claude checks ~/.claude/skills/ for matching skills
+$ ls ~/.claude/skills/
+art-vandeley/
+incident-report/
+session-handoff/
+vim-architect/
+
+# 3. Claude reads matching SKILL.md frontmatter
+$ cat ~/.claude/skills/art-vandeley/SKILL.md | head -5
+---
+name: art-vandeley
+description: Create comprehensive Spanish README.md documentation and Mermaid diagrams
+allowed-tools: [Read, Write, Glob, Grep, Bash, Task]
+---
+
+# 4. Claude loads the skill and follows its instructions
+# 5. Skill has access only to allowed-tools
+# 6. Skill can call helper scripts in scripts/
+```
+
+**Key insights from art-vandeley:**
+- Skills live in `~/.claude/skills/` (user-level, not project-level)
+- Claude auto-discovers skills by reading SKILL.md frontmatter
+- Skills have their own helper scripts (bash utilities)
+- Skills can orchestrate framework-specific behavior (skillful-svelte, skillful-react)
+- Skills can call remote registries for dynamic content
+
+---
+
+## Real-World Example: art-vandeley Installation
+
+```bash
+# What actually happens when you install art-vandeley:
+
+# 1. Create directory
+mkdir -p ~/.claude/skills/art-vandeley
+
+# 2. Download core files
+curl https://vandeley.art/art-vandeley.md > ~/.claude/skills/art-vandeley/SKILL.md
+curl https://vandeley.art/README.md > ~/.claude/skills/art-vandeley/README.md
+
+# 3. Download helper scripts
+mkdir -p ~/.claude/skills/art-vandeley/scripts
+cd ~/.claude/skills/art-vandeley/scripts
+curl -O https://vandeley.art/scripts/analyze-git.sh
+curl -O https://vandeley.art/scripts/create-architecture.sh
+curl -O https://vandeley.art/scripts/create-sequence.sh
+curl -O https://vandeley.art/scripts/create-erd.sh
+curl -O https://vandeley.art/scripts/create-interfaces.sh
+curl -O https://vandeley.art/scripts/create-class-diagram.sh
+
+# 4. Make scripts executable
+chmod +x *.sh
+
+# 5. Validate
+if grep -q "^---" ~/.claude/skills/art-vandeley/SKILL.md; then
+  echo "✅ art-vandeley installed"
+else
+  echo "❌ Installation failed"
+fi
+```
+
+---
+
+**Philosophy**: Make it easy to get started, hard to mess up, and simple to undo.
+
+**Inspired by**: [art-vandeley](https://vandeley.art) - The importer-exporter of well-architected skills.