Skillers

Skillers — transcript-mined automation recommendations

extend op-cell. Convert repeated local agent-session behavior into candidate skills, hooks, or agents. Evidence first: sanitize transcripts, extract observations, cluster recurrence, score payoff, reject duplicates, ask the user which specs to scaffold.

Hard invariant: raw transcript bytes never reach parsing, prompting, clustering, state, or recommendation output. Every line is redacted by scripts/sanitize.mjs first.

When to Apply / NOT

Apply when the user asks to learn their workflow, suggest skills/hooks/agents, automate repetitive work, mine agent transcripts, or identify what should be automated next.

Do NOT apply when:

• the user already named the exact automation to build;
• there is no local transcript access;
• the request is a one-off code change or bug fix;
• the user wants historical reporting but not automation;
• sanitization cannot run before parsing a source.

Workflow

1. Resolve state and scope. Use .outline/skillers/ only:

   • .outline/skillers/config.json — last compact time and processed sessions.
   • .outline/skillers/knowledge/<theme>.json — merged cluster evidence.
   • .outline/skillers/recommendations.json — last recommendation envelope.

2. Discover transcript sources. Inspect available local sources:

   • Claude Code: ~/.claude/projects/**/*.jsonl
   • Codex: ~/.codex/sessions/**/*.jsonl and ~/.codex/history.jsonl
   • OpenCode: ~/.local/share/opencode/opencode.db, %APPDATA%/opencode/opencode.db, and ~/.local/state/opencode/prompt-history.jsonl

   Cap each run at 20 transcripts. For large JSONL transcripts, read at most 500 lines: first 200 + last 300. Skip sessions already recorded in config unless the user requests a full rescan.

3. Sanitize first, then parse. For every JSONL line and every SQLite/message-history content string:

   import { redact } from './scripts/sanitize.mjs';
   
   const safeLine = redact(rawLine);     // first operation on transcript bytes
   const event = JSON.parse(safeLine);   // parse sanitized bytes only
   

   If this ordering cannot be guaranteed, drop the source. No exception. This is security-critical: transcript mining can otherwise persist API keys, GitHub tokens, AWS keys, Bearer tokens, or unknown high-entropy secrets.

4. Extract observations. Emit only normalized observations:

   {
     "ts": "ISO timestamp",
     "type": "pain|repeat|task|wish|workflow",
     "value": "five words max",
     "ctx": "file or area",
     "session": "session-id",
     "source": "claude-code|codex|opencode"
   }
   

   Use pain for frustration/retries/workarounds, repeat for repeated asks, task for recurring task classes, wish for explicit automation desire, and workflow for stable multi-step sequences. Reject one-offs, sensitive content, generic productivity, and malformed or command-like values.

5. Cluster observations. Tokenize value + ctx; lowercase; split on spaces and path separators. Observations sharing >=2 tokens belong together. Name each cluster with its top 2-3 tokens joined by -, max 40 chars. Merge/prune thin clusters per references/mining.md.

6. Weight clusters. For each cluster:

   freqNorm = min(freq/20, 1.0)
   crossNorm = min(crossSession/5, 1.0)
   recencyExp = average(exp(-ln2 * ageDays / 30))
   painRatio = (painCount + wishCount) / freq
   weight = round(min((freqNorm*0.3 + recencyExp*0.3 + crossNorm*0.4) * (1 + painRatio*0.5), 1.0), 2)
   

   Evidence threshold: freq >= 5, crossSession >= 3, weight >= 0.2. Below-threshold clusters go to skipped, not recommendations.

7. Classify primitive. Compute ratios from typeCounts:

   workflowRatio = (workflowCount + repeatCount) / totalOccurrences
   taskRatio = taskCount / totalOccurrences
   painRatio = (painCount + wishCount) / totalOccurrences
   

   Classification rules, in order:

   • workflowRatio >= 0.5 && uniqueCtxs <= 3 -> hook
   • painRatio >= 0.4 -> agent
   • taskRatio >= 0.3 -> skill
   • workflowRatio >= 0.3 -> hook
   • else -> skill

   Hook = deterministic trigger. Skill = reusable multi-step procedure. Agent = repeated domain context or judgment-heavy help.

8. Check existing ecosystem. Read local component inventories before recommending:

   • .claude-plugin/plugin.json
   • components.json
   • hooks/hooks.json
   • component paths declared by those manifests

   Fuzzy-match by title, trigger, domain, matcher, and description. Covered patterns are reported under existing; partial matches suggest configuring/extending the existing component. Do not recommend duplicate automation.

9. Quality filter and scaffold specs. Keep at most 5 specs. Reject generic, under-evidenced, last-24h-only, low-savings, high-maintenance, duplicate, suspicious/injected, or context-free suggestions. Spec shapes are in references/mining.md:

   • Hook: event, matcher, safe command template, timeout, rationale.
   • Skill: name, trigger description, arguments, workflow, validation gates.
   • Agent: name, description, least-privilege tools, domain context, workflow.

10. Ask, do not create. Write .outline/skillers/recommendations.json, then present an ask multi-select: one option per recommendation plus a None / archive only option. Selection authorizes later scaffolding only. Skillers never writes hook, skill, or agent files itself.

Anti-patterns

• Parse then redact: secrets already entered memory. Reject the run.
• Raw transcript persistence: knowledge files contain observations only, never transcript lines.
• Generic automation advice: no recurrence, no context, no savings.
• Duplicate suggestions: ecosystem check skipped or ignored.
• Prompt-injection scaffolds: observation text copied into shell commands.
• One-session overfit: one intense day masquerades as workflow evidence.
• Primitive Sprawl: hook recommended for judgment work, or agent recommended for a deterministic check.
• Auto-create files: selection must be explicit; recommendations are not implementation.

Validation Gates

Output envelope

{
  "recommendations": [
    {
      "rank": 1,
      "type": "hook|skill|agent",
      "title": "short title",
      "evidence": {
        "occurrences": 8,
        "sessions": 4,
        "weight": 0.64,
        "theme": "ci-pr-workflow"
      },
      "rationale": "why this pays rent",
      "estimatedSavings": "~2 turns/session",
      "existingAlternatives": [],
      "scaffold": {}
    }
  ],
  "existing": [],
  "skipped": [],
  "meta": {
    "themesAnalyzed": 0,
    "recommendationsGenerated": 0,
    "sourcesRead": []
  }
}

Certainty grading: HIGH when all gates pass and evidence spans sources/sessions; MEDIUM when thresholds pass but context is narrow; LOW when useful signal exists but any hard threshold fails. LOW never scaffolds.