oh-my-claude-sisyphus 3.4.3 → 3.5.0

package/skills/local-skills-setup/SKILL.md

@@ -0,0 +1,465 @@
+---
+name: local-skills-setup
+description: Set up and manage local skills for automatic matching and invocation
+argument-hint: "[list|add|scan]"
+---
+
+# Local Skills Setup
+
+This skill provides a guided wizard for setting up and managing your local learned skills. Skills are reusable problem-solving patterns that Claude automatically applies when it detects matching triggers.
+
+## Why Local Skills?
+
+Local skills allow you to capture hard-won insights and solutions that are specific to your codebase or workflow:
+- **Project-level skills** (.omc/skills/) - Version-controlled with your repo
+- **User-level skills** (~/.claude/skills/omc-learned/) - Portable across all your projects
+
+When you solve a tricky bug or discover a non-obvious workaround, you can extract it as a skill. Claude will automatically detect and apply these skills in future conversations when it sees matching triggers.
+
+## Interactive Workflow
+
+### Step 1: Directory Check and Setup
+
+First, check if skill directories exist and create them if needed:
+
+```bash
+# Check and create user-level skills directory
+USER_SKILLS_DIR="$HOME/.claude/skills/omc-learned"
+if [ -d "$USER_SKILLS_DIR" ]; then
+  echo "User skills directory exists: $USER_SKILLS_DIR"
+else
+  mkdir -p "$USER_SKILLS_DIR"
+  echo "Created user skills directory: $USER_SKILLS_DIR"
+fi
+
+# Check and create project-level skills directory
+PROJECT_SKILLS_DIR=".omc/skills"
+if [ -d "$PROJECT_SKILLS_DIR" ]; then
+  echo "Project skills directory exists: $PROJECT_SKILLS_DIR"
+else
+  mkdir -p "$PROJECT_SKILLS_DIR"
+  echo "Created project skills directory: $PROJECT_SKILLS_DIR"
+fi
+```
+
+### Step 2: Skill Scan and Inventory
+
+Scan both directories and show a comprehensive inventory:
+
+```bash
+# Scan user-level skills
+echo "=== USER-LEVEL SKILLS (~/.claude/skills/omc-learned/) ==="
+if [ -d "$HOME/.claude/skills/omc-learned" ]; then
+  USER_COUNT=$(find "$HOME/.claude/skills/omc-learned" -name "*.md" 2>/dev/null | wc -l)
+  echo "Total skills: $USER_COUNT"
+
+  if [ $USER_COUNT -gt 0 ]; then
+    echo ""
+    echo "Skills found:"
+    find "$HOME/.claude/skills/omc-learned" -name "*.md" -type f -exec sh -c '
+      FILE="$1"
+      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
+      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
+      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
+      echo "  - $NAME"
+      [ -n "$DESC" ] && echo "    Description: $DESC"
+      echo "    Modified: $MODIFIED"
+      echo ""
+    ' sh {} \;
+  fi
+else
+  echo "Directory not found"
+fi
+
+echo ""
+echo "=== PROJECT-LEVEL SKILLS (.omc/skills/) ==="
+if [ -d ".omc/skills" ]; then
+  PROJECT_COUNT=$(find ".omc/skills" -name "*.md" 2>/dev/null | wc -l)
+  echo "Total skills: $PROJECT_COUNT"
+
+  if [ $PROJECT_COUNT -gt 0 ]; then
+    echo ""
+    echo "Skills found:"
+    find ".omc/skills" -name "*.md" -type f -exec sh -c '
+      FILE="$1"
+      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
+      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
+      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
+      echo "  - $NAME"
+      [ -n "$DESC" ] && echo "    Description: $DESC"
+      echo "    Modified: $MODIFIED"
+      echo ""
+    ' sh {} \;
+  fi
+else
+  echo "Directory not found"
+fi
+
+# Summary
+TOTAL=$((USER_COUNT + PROJECT_COUNT))
+echo "=== SUMMARY ==="
+echo "Total skills across all directories: $TOTAL"
+```
+
+### Step 3: Quick Actions Menu
+
+After scanning, use the AskUserQuestion tool to offer these options:
+
+**Question:** "What would you like to do with your local skills?"
+
+**Options:**
+1. **Add new skill** - Start the skill creation wizard
+2. **List all skills with details** - Show comprehensive skill inventory with triggers
+3. **Scan conversation for patterns** - Analyze current conversation for skill-worthy patterns
+4. **Import skill** - Import a skill from URL or paste content
+5. **Done** - Exit the wizard
+
+#### Option 1: Add New Skill
+
+If user chooses "Add new skill", invoke the learner skill:
+
+```
+Use the Skill tool to invoke: learner
+```
+
+This will guide them through the extraction process with quality validation.
+
+#### Option 2: List All Skills with Details
+
+Show detailed information including trigger keywords:
+
+```bash
+echo "=== DETAILED SKILL INVENTORY ==="
+echo ""
+
+# Function to show skill details
+show_skill_details() {
+  FILE="$1"
+  LOCATION="$2"
+
+  echo "---"
+  echo "Location: $LOCATION"
+  echo "File: $(basename "$FILE")"
+
+  # Extract frontmatter
+  NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
+  DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
+  TRIGGERS=$(grep -m1 "^triggers:" "$FILE" 2>/dev/null | sed "s/triggers: //")
+  QUALITY=$(grep -m1 "^quality:" "$FILE" 2>/dev/null | sed "s/quality: //")
+
+  [ -n "$NAME" ] && echo "Name: $NAME"
+  [ -n "$DESC" ] && echo "Description: $DESC"
+  [ -n "$TRIGGERS" ] && echo "Triggers: $TRIGGERS"
+  [ -n "$QUALITY" ] && echo "Quality: $QUALITY"
+
+  # Last modified
+  MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null | cut -d. -f1 || stat -f "%Sm" "$FILE" 2>/dev/null)
+  echo "Last modified: $MODIFIED"
+  echo ""
+}
+
+# Export function for subshell
+export -f show_skill_details
+
+# Show user-level skills
+if [ -d "$HOME/.claude/skills/omc-learned" ]; then
+  echo "USER-LEVEL SKILLS:"
+  find "$HOME/.claude/skills/omc-learned" -name "*.md" -type f -exec bash -c 'show_skill_details "$0" "user-level"' {} \;
+fi
+
+# Show project-level skills
+if [ -d ".omc/skills" ]; then
+  echo "PROJECT-LEVEL SKILLS:"
+  find ".omc/skills" -name "*.md" -type f -exec bash -c 'show_skill_details "$0" "project-level"' {} \;
+fi
+```
+
+#### Option 3: Scan Conversation for Patterns
+
+Analyze the current conversation context to identify potential skill-worthy patterns. Look for:
+- Recent debugging sessions with non-obvious solutions
+- Tricky bugs that required investigation
+- Codebase-specific workarounds discovered
+- Error patterns that took time to resolve
+
+Report findings and ask if user wants to extract any as skills.
+
+#### Option 4: Import Skill
+
+Ask user to provide either:
+- **URL**: Download skill from a URL (e.g., GitHub gist)
+- **Paste content**: Paste skill markdown content directly
+
+Then ask for scope:
+- **User-level** (~/.claude/skills/omc-learned/) - Available across all projects
+- **Project-level** (.omc/skills/) - Only for this project
+
+Validate the skill format and save to the chosen location.
+
+### Step 4: Skill Templates
+
+Provide quick templates for common skill types. When user wants to create a skill, offer these starting points:
+
+#### Error Solution Template
+
+```markdown
+---
+id: error-[unique-id]
+name: [Error Name]
+description: Solution for [specific error in specific context]
+source: conversation
+triggers: ["error message fragment", "file path", "symptom"]
+quality: high
+---
+
+# [Error Name]
+
+## The Insight
+What is the underlying cause of this error? What principle did you discover?
+
+## Why This Matters
+What goes wrong if you don't know this? What symptom led here?
+
+## Recognition Pattern
+How do you know when this applies? What are the signs?
+- Error message: "[exact error]"
+- File: [specific file path]
+- Context: [when does this occur]
+
+## The Approach
+Step-by-step solution:
+1. [Specific action with file/line reference]
+2. [Specific action with file/line reference]
+3. [Verification step]
+
+## Example
+\`\`\`typescript
+// Before (broken)
+[problematic code]
+
+// After (fixed)
+[corrected code]
+\`\`\`
+```
+
+#### Workflow Skill Template
+
+```markdown
+---
+id: workflow-[unique-id]
+name: [Workflow Name]
+description: Process for [specific task in this codebase]
+source: conversation
+triggers: ["task description", "file pattern", "goal keyword"]
+quality: high
+---
+
+# [Workflow Name]
+
+## The Insight
+What makes this workflow different from the obvious approach?
+
+## Why This Matters
+What fails if you don't follow this process?
+
+## Recognition Pattern
+When should you use this workflow?
+- Task type: [specific task]
+- Files involved: [specific patterns]
+- Indicators: [how to recognize]
+
+## The Approach
+1. [Step with specific commands/files]
+2. [Step with specific commands/files]
+3. [Verification]
+
+## Gotchas
+- [Common mistake and how to avoid it]
+- [Edge case and how to handle it]
+```
+
+#### Code Pattern Template
+
+```markdown
+---
+id: pattern-[unique-id]
+name: [Pattern Name]
+description: Pattern for [specific use case in this codebase]
+source: conversation
+triggers: ["code pattern", "file type", "problem domain"]
+quality: high
+---
+
+# [Pattern Name]
+
+## The Insight
+What's the key principle behind this pattern?
+
+## Why This Matters
+What problems does this pattern solve in THIS codebase?
+
+## Recognition Pattern
+When do you apply this pattern?
+- File types: [specific files]
+- Problem: [specific problem]
+- Context: [codebase-specific context]
+
+## The Approach
+Decision-making heuristic, not just code:
+1. [Principle-based step]
+2. [Principle-based step]
+
+## Example
+\`\`\`typescript
+[Illustrative example showing the principle]
+\`\`\`
+
+## Anti-Pattern
+What NOT to do and why:
+\`\`\`typescript
+[Common mistake to avoid]
+\`\`\`
+```
+
+#### Integration Skill Template
+
+```markdown
+---
+id: integration-[unique-id]
+name: [Integration Name]
+description: How [system A] integrates with [system B] in this codebase
+source: conversation
+triggers: ["system name", "integration point", "config file"]
+quality: high
+---
+
+# [Integration Name]
+
+## The Insight
+What's non-obvious about how these systems connect?
+
+## Why This Matters
+What breaks if you don't understand this integration?
+
+## Recognition Pattern
+When are you working with this integration?
+- Files: [specific integration files]
+- Config: [specific config locations]
+- Symptoms: [what indicates integration issues]
+
+## The Approach
+How to work with this integration correctly:
+1. [Configuration step with file paths]
+2. [Setup step with specific details]
+3. [Verification step]
+
+## Gotchas
+- [Integration-specific pitfall #1]
+- [Integration-specific pitfall #2]
+```
+
+## Usage Modes
+
+### Direct Command Mode
+
+When invoked with an argument, skip the interactive wizard:
+
+- `/oh-my-claudecode:local-skills-setup list` - Show detailed skill inventory
+- `/oh-my-claudecode:local-skills-setup add` - Start skill creation (invoke learner)
+- `/oh-my-claudecode:local-skills-setup scan` - Scan both skill directories
+
+### Interactive Mode
+
+When invoked without arguments, run the full guided wizard (Steps 1-4).
+
+## Skill Quality Guidelines
+
+Remind users that good skills are:
+
+1. **Non-Googleable** - Can't easily find via search
+   - BAD: "How to read files in TypeScript" ❌
+   - GOOD: "This codebase uses custom path resolution requiring fileURLToPath" ✓
+
+2. **Context-Specific** - References actual files/errors from THIS codebase
+   - BAD: "Use try/catch for error handling" ❌
+   - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError" ✓
+
+3. **Actionable with Precision** - Tells exactly WHAT to do and WHERE
+   - BAD: "Handle edge cases" ❌
+   - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution" ✓
+
+4. **Hard-Won** - Required significant debugging effort
+   - BAD: Generic programming patterns ❌
+   - GOOD: "Race condition in worker.ts - Promise.all at line 89 needs await" ✓
+
+## Benefits of Local Skills
+
+When introducing the skill system, explain these benefits:
+
+**Automatic Application**: Claude detects triggers and applies skills automatically - no need to remember or search for solutions.
+
+**Version Control**: Project-level skills (.omc/skills/) are committed with your code, so the whole team benefits.
+
+**Evolving Knowledge**: Skills improve over time as you discover better approaches and refine triggers.
+
+**Reduced Token Usage**: Instead of re-solving the same problems, Claude applies known patterns efficiently.
+
+**Codebase Memory**: Preserves institutional knowledge that would otherwise be lost in conversation history.
+
+## Related Skills
+
+- `/oh-my-claudecode:learner` - Extract a skill from current conversation
+- `/oh-my-claudecode:note` - Save quick notes (less formal than skills)
+- `/oh-my-claudecode:deepinit` - Generate AGENTS.md codebase hierarchy
+
+## Example Session
+
+Show users what a typical session looks like:
+
+```
+> /oh-my-claudecode:local-skills-setup
+
+Checking skill directories...
+✓ User skills directory exists: ~/.claude/skills/omc-learned/
+✓ Project skills directory exists: .omc/skills/
+
+Scanning for skills...
+
+=== USER-LEVEL SKILLS ===
+Total skills: 3
+  - async-network-error-handling
+    Description: Pattern for handling independent I/O failures in async network code
+    Modified: 2026-01-20 14:32:15
+
+  - esm-path-resolution
+    Description: Custom path resolution in ESM requiring fileURLToPath
+    Modified: 2026-01-19 09:15:42
+
+=== PROJECT-LEVEL SKILLS ===
+Total skills: 5
+  - session-timeout-fix
+    Description: Fix for sessionId undefined after restart in session.ts
+    Modified: 2026-01-22 16:45:23
+
+  - build-cache-invalidation
+    Description: When to clear TypeScript build cache to fix phantom errors
+    Modified: 2026-01-21 11:28:37
+
+=== SUMMARY ===
+Total skills: 8
+
+What would you like to do?
+1. Add new skill
+2. List all skills with details
+3. Scan conversation for patterns
+4. Import skill
+5. Done
+```
+
+## Tips for Users
+
+- Run `/oh-my-claudecode:local-skills-setup scan` periodically to review your skill library
+- After solving a tricky bug, immediately run learner to capture it
+- Use project-level skills for codebase-specific knowledge
+- Use user-level skills for general patterns that apply everywhere
+- Review and refine triggers over time to improve matching accuracy