# Soulcatcher

> Orchestrates behavioral workflow discovery — observes actions across sessions, detects recurring procedures, challenges inferences, and compiles portable Agent Skills with evidence. Use when the user mentions Soulcatcher, wants to learn their workflow, compile a skill from behavior, run the Soulcatcher demo, or analyze how they repeatedly solve a class of problems.

- Skill: `justtyashh/soulcatcher` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add justtyashh/soulcatcher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justtyashh/soulcatcher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: JusttYashh (https://skillmd.com/u/justtyashh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/justtyashh/soulcatcher

---


# Soulcatcher

Turn behavioral traces into portable, evidence-backed Agent Skills.

**Core primitive:** Behavioral traces → latent procedure → portable Skill

Read [reference.md](reference.md) for artifact schemas and pipeline rules.

## Modes

### Demo mode

Activate when the user says **"demo"**, **"Run the Soulcatcher demo"**, or points to `learned-skills/examples/sample-traces/`.

1. Load all traces from `learned-skills/examples/sample-traces/`
2. Run pipeline steps 2–5 below (skip gather — traces are bundled)
3. Present infer-procedure output using the standard template
4. Show challenge-inference verdict (reference pre-computed output in `learned-skills/examples/pipeline-output/` if helpful)
5. Point to `learned-skills/examples/adversarial-decision-analysis/` as the compiled result
6. Offer A/B test prompt from `learned-skills/examples/WALKTHROUGH.md`

Do not ask the user to supply transcripts in demo mode.

### Production mode

Activate for real workflow discovery on the user's own sessions.

## Pipeline Checklist

Copy and track progress:

```
Soulcatcher Progress:
- [ ] 1. Gather source material
- [ ] 2. Observe → BehavioralTrace(s)
- [ ] 3. Detect patterns → PatternReport(s)
- [ ] 4. Infer procedure → ProcedureDraft
- [ ] 5. Challenge inference → accept / refine / reject
- [ ] 6. User approval
- [ ] 7. Compile skill → learned-skills/{skill-name}/
- [ ] 8. (Optional) Skill audit
```

### Step 1: Gather source material

Collect behavioral evidence from:
- Current chat and tool history
- User-pasted session summaries
- Agent transcripts (e.g. `.cursor/projects/.../agent-transcripts/*.jsonl`)
- Git history / diffs if relevant

Need **3+ relevant sessions** for pattern detection unless user specifies otherwise.

### Step 2: Observe

Follow [../observe/SKILL.md](../observe/SKILL.md). Output: BehavioralTrace per session.

**Hard rule:** Do not change how you respond during observation. Read-only analysis.

### Step 3: Detect patterns

Follow [../detect-patterns/SKILL.md](../detect-patterns/SKILL.md). Output: ranked PatternReport list.

### Step 4: Infer procedure

Follow [../infer-procedure/SKILL.md](../infer-procedure/SKILL.md). Output: ProcedureDraft.

Present to user using the infer-procedure template. **Stop and wait for interest before challenging.**

### Step 5: Challenge inference

Follow [../challenge-inference/SKILL.md](../challenge-inference/SKILL.md). Output: verdict.

- **accept** → proceed to step 6
- **refine** → return to step 4 with constraints
- **reject** → try next pattern or stop

### Step 6: User approval

Ask explicitly:

> Would you like to compile this into a Skill?

Do not compile without a clear yes.

### Step 7: Compile skill

Follow [../compile-skill/SKILL.md](../compile-skill/SKILL.md). Write to `learned-skills/{skill-name}/`.

### Step 8: Skill audit (optional)

Follow [../skill-audit/SKILL.md](../skill-audit/SKILL.md) on existing skills when user requests or after major behavior change.

## Hard Rules

- Never write personality profiles or preference lists
- Never dump full transcripts into compiled Skills
- Always show evidence before asking to compile
- Explicit invocation only — no background watching
- Separate observation, inference, and compilation at every step

## Quick Reference

| Step | Skill | Output |
|------|-------|--------|
| Observe | observe | BehavioralTrace |
| Detect | detect-patterns | PatternReport |
| Infer | infer-procedure | ProcedureDraft |
| Challenge | challenge-inference | verdict |
| Compile | compile-skill | SKILL.md + evidence.md |
| Audit | skill-audit | drift report |