feat: Personal Skills Factory - Integração Matrix + Skills

[CairoAC]

Personal Skills Factory - Matrix + Skills Integration Proposal

Context

This proposal emerges from an in-depth discussion about the relationship between Matrix solutions and Claude Code Skills, and how to unify these two approaches to maximize value.

The Current Problem

Skills vs Matrix: Fundamental Differences

Aspect	Matrix (today)	Skills
What it stores	Knowledge/pattern	Executable tool
Execution	Claude applies manually	Script runs directly
Discovery	Explicit matrix_recall	Automatic by context
Added value	Reusable pattern	Complete automation + analysis

Example: Cloud API Structure Extraction

Imagine a scenario where the user needs to extract the complete structure of a cloud service (agents, workflows, configurations, etc.) via REST API.

Using Matrix (knowledge):

• Claude executes ~15 curl/REST calls
• Encounters errors (authentication, quota, wrong endpoints)
• Manually corrects and iterates
• Result: Basic JSON without formatting
• No analysis of problems or inconsistencies

Using Skill (tool):

• 1 call python3 script.py
• Runs directly without errors (script already tested)
• Nicely formatted result
• Automatically detects warnings:
  • Resources missing required configuration
  • Inconsistent values between related fields
  • Internal URLs/paths exposed that should be abstracted
  • Circular references between components

Conclusion: Skill is not just "optimization" - it's automation with added value. The script encapsulates not only the steps, but also domain-specific analyses that Matrix (pure knowledge) doesn't offer.

---

The Real Difference

Matrix = Recipe (you still need to cook)
Skill  = Ready meal (just serve) + quality analysis

What Claude did	What Matrix saved	What Skill has
15 REST commands	API pattern	250-line script
Handled errors on the fly	"Use header X"	Complete try/except
Iterated over resources	"For each item..."	Implemented for loop
Formatted output	Nothing	Nice formatting
-	-	Warning analysis

---

Proposal: Complete Evolution Flow

Phase 1: First Resolution (no prior context)

User requests something complex
    ↓
Claude solves with difficulty (multiple steps, errors, corrections)
    ↓
matrix_store() saves:
{
  problem: "...",
  solution: "...",
  executionLog: [           // NEW: step recording
    { action: "bash", command: "...", result: "error" },
    { action: "bash", command: "...", result: "success" },
    ...
  ],
  complexity: 7,
  timeSpent: "15 min"
}

Phase 2: Subsequent Uses

matrix_recall() finds solution
    ↓
Claude applies pattern (faster, but still manual)
    ↓
Matrix updates:
{
  uses: N,
  successRate: X%,
  executionPatterns: [...]
}

Phase 3: Automatable Pattern Detection

// Matrix analyzes automatically:
automationAnalysis: {
  isRepetitive: true,           // same steps every time
  hasFixedInput: true,          // well-defined input
  hasFixedOutput: true,         // well-defined output
  requiresJudgment: false,      // no human decision needed
  stepsAreDeterministic: true,  // same sequence always
  
  automationScore: 0.85,        // HIGH
  
  suggestion: "This solution was used Nx with Y% success. 
               Would you like me to generate a draft script?"
}

Important: Not every problem is automatable. Most (~99%) are:

• Debugging (each bug is unique)
• Refactoring (depends on context)
• Architecture (requires judgment)

Only problems with:

• Repetitive and predictable operations
• Well-defined input/output
• No need for contextual judgment

Phase 4: Draft Generation

If user accepts, Matrix generates base script:

#!/usr/bin/env python3
"""
DRAFT GENERATED BY MATRIX
Based on N successful executions
Requires human review before production use
"""

# TODO: Add error handling
# TODO: Add output formatting
# TODO: Test in other contexts

def main():
    # Steps extracted from executionLog
    ...

Phase 5: Human Refinement

Human adds:

• Complete error handling
• Output formatting
• Domain-specific analyses/warnings
• Tests

Phase 6: Promotion to Skill

matrix_promote({
  solutionId: "sol_xxx",
  skillName: "cloud-extractor"
})

// Creates structure:
// ~/.claude/skills/cloud-extractor/SKILL.md
// ~/.claude/skills/cloud-extractor/scripts/main.py

// Updates solution:
{
  id: "sol_xxx",
  promotedTo: {
    type: "skill",
    name: "cloud-extractor",
    path: "~/.claude/skills/cloud-extractor",
    promotedAt: "2025-12-27"
  }
}

---

Critical Issue: Matrix as Orchestrator

The Problem

When a skill exists, Claude prefers to use it directly, ignoring Matrix:

User: "extract resources using matrix"
Claude: /cloud-extractor  ← IGNORED request, preferred skill

This breaks the learning flow:

• Matrix is not consulted
• Matrix stops learning
• If skill breaks, Matrix has outdated knowledge

Solution: Matrix Decides, Not Claude

ALWAYS:
1. matrix_recall() first
2. Matrix returns: { useSkill: "X" } OR { applySolution: "..." }
3. Claude obeys Matrix
4. After: matrix_reward() for feedback

// matrix_recall returns:
{
  recommendation: "skill",  // or "apply" or "explore"
  skill: "cloud-extractor",
  fallback: { solution: "...", codeBlocks: [...] },
  reason: "Skill available and working (last success: 2h ago)"
}

// If skill failed recently:
{
  recommendation: "apply",
  solution: "...",
  skillStatus: "broken",
  reason: "Skill cloud-extractor failed 3x in the last 24h"
}

---

Required Schema Changes

-- New field for execution recording
ALTER TABLE solutions ADD COLUMN execution_log JSON DEFAULT '[]';

-- New field for automation analysis
ALTER TABLE solutions ADD COLUMN automation_score REAL;

-- New field for promotion
ALTER TABLE solutions ADD COLUMN promoted_to JSON;
-- { "type": "skill", "name": "...", "path": "...", "promotedAt": "..." }

-- Skill execution tracking
CREATE TABLE IF NOT EXISTS skill_executions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    solution_id TEXT REFERENCES solutions(id),
    skill_name TEXT NOT NULL,
    success INTEGER NOT NULL,
    duration_ms INTEGER,
    error_message TEXT,
    executed_at TEXT DEFAULT (datetime('now'))
);

---

Proposed New Tools

matrix_promote

matrix_promote({
  solutionId: "sol_xxx",
  skillName: "cloud-extractor",
  skillPath: "~/.claude/skills/cloud-extractor"  // optional
})
// Returns: { success: true, skillPath: "...", filesCreated: [...] }

matrix_generate_draft

matrix_generate_draft({
  solutionId: "sol_xxx"
})
// Returns: { language: "python", code: "...", todos: [...] }

Modification to matrix_recall

// New field in return:
{
  solutions: [...],
  recommendation: "skill" | "apply" | "explore",
  skill: "cloud-extractor",  // if recommendation == "skill"
  automationSuggestion: "..."  // if automationScore > 0.7
}

---

Complete Visual Flow

┌─────────────────────────────────────────────────────────────────┐
│                    FIRST TIME (no context)                       │
│  Claude solves with difficulty → matrix_store(executionLog)     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SUBSEQUENT USES                               │
│  matrix_recall → Claude applies → matrix_reward                 │
│  Matrix accumulates: uses, successRate, patterns                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PATTERN DETECTION                             │
│  Matrix analyzes: repetitive? deterministic? no judgment?       │
│  If automationScore > 0.7 → Suggests script creation            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    DRAFT GENERATION                              │
│  matrix_generate_draft() → Base script with TODOs               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    HUMAN REFINEMENT                              │
│  Adds: errors, formatting, analyses, tests                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PROMOTION TO SKILL                            │
│  matrix_promote() → Skill created, Matrix references it         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    FUTURE USE (Matrix as orchestrator)           │
│  matrix_recall → { recommendation: "skill" } → Executes skill   │
│  matrix_reward → Matrix continues learning                      │
│  If skill fails → Fallback to solution                          │
└─────────────────────────────────────────────────────────────────┘

---

Benefits

1. Continuous learning - Matrix is always consulted, always learns
2. Natural evolution - Knowledge → Draft → Refined Skill
3. Robust fallback - If skill breaks, Matrix has knowledge
4. Intelligent detection - Only suggests automation when it makes sense
5. Human in the loop - Refinement and final decision are human

---

Suggested Next Steps

1. Add execution_log to schema
2. Implement automation_score calculation
3. Create matrix_generate_draft
4. Create matrix_promote
5. Modify matrix_recall to return recommendation
6. Create skill_executions table for tracking
7. Document CLAUDE.md instruction about execution hierarchy

---

This proposal was developed through iterative discussion about real use cases comparing Matrix vs Skills approaches.