task-profile

# task-profile

> **Platforms: Claude Code / Cowork and Codex.** `scripts/inventory.py` detects the host (via the `platform` stamp `install.sh` writes, or `AI_FIRST_PLATFORM`) and routes: Claude Code (`~/.claude/projects`) + Cowork transcripts, or Codex rollouts (`~/.codex/sessions`), building the same session condensate + token aggregates either way. **Antigravity** is unsupported: its IDE store is AEAD-encrypted at rest and its CLI store has no parseable turn content, so the skill prints a clear "not available" message and exits.

End-to-end skill: session inventory → LLM clustering → parallel Haiku analysis → aggregation → branded explorer HTML + shareable CSV + atomic skill proposals.

## When to run

When the user asks to understand their own Claude usage patterns: what tasks they repeat, how much friction those tasks generate where tokens go which principles they already follow vs. where they slip, and which new skills would compound across many tasks.

## Prerequisites

- Session history on this machine:
  - Claude Code: `~/.claude/projects/*/\*.jsonl`
  - Claude Cowork: `~/Library/Application Support/Claude/local-agent-mode-sessions/*/*/local_*/audit.jsonl`
- The `session-search` skill is already installed at `~/.claude/skills/session-search/` (optional but recommended; this skill does its own inventory pass).
- None beyond Python 3, the HTML generator ships with its own light theme baked in. No external design or logo skill required.

## Workflow

Run from any working directory, outputs land under `./out/` in that directory.

### Phase A, Inventory (deterministic script)

```bash
~/.claude/skills/task-profile/scripts/inventory.py --out out/inventory.json
```

Flags: `--since YYYY-MM-DD`, `--until YYYY-MM-DD`, `--all` (default window: last 6 months).

Writes per-session rows with: summary, token totals (per model, from `message.usage`), automation flag + reason, and a structured condensate (intent turns + correction turns + tool-flail episodes + outcome turns). Automated sessions (paperclip, scheduled-task, sdk-cli, ditto-routine) are flagged and excluded from downstream analysis but kept for transparency.

### Phase B, Cluster (main agent reads + judges)

You (the main agent) read the non-automation rows and group them into ~40–80 clusters by judgment, no scripted heuristics past cwd. Write `out/clusters.json`. Merge sessions with the same cwd, similar Cowork titles, or clearly similar topics. Show the cluster list to the user before the Haiku fan-out so they can adjust.

### Phase C, Per-cluster payloads + Haiku fan-out (parallel)

Run `out/build_payloads.py` (generated per-run, sample below) to produce one payload per cluster. Sampling: ≤ 10 sessions → all included; > 10 → include 10 biased to outliers (3 longest by turns, 3 most corrections, oldest, newest, even-spaced fill).

Dispatch one `Agent(subagent_type="general-purpose", model="haiku", run_in_background=true)` per cluster **in parallel**. Each subagent reads:

1. `~/.claude/skills/task-profile/references/task-style.md`
2. `~/.claude/skills/task-profile/references/success-rubric.md`
3. `~/.claude/skills/task-profile/references/friction-signals.md`
4. Its cluster payload at `out/payloads/<cluster_id>.json`

And emits strict JSON to `out/analyses/<cluster_id>.json` with a 1–3 task list per cluster.

### Phase D, Aggregate (main agent + script)

You (the main agent) read `out/analyses/*.json`, decide cross-cluster merges, and write `out/canonical-merges.json` with entries of the form:

```json
{"canonical": "<sentence>", "category": "<cat>", "source_tasks": [{"cluster": "...", "match": "<substring>"}]}
```

Then run:

```bash
~/.claude/skills/task-profile/scripts/write_profile.py
```

The script normalises success/category enums, applies redaction one more time, sums tokens per task from the inventory (no estimation, real `message.usage` values), and writes:

- `out/profile.csv`, shareable, one row per canonical task, with `tokens_by_model` as a compact string.
- `out/profile.json`, richer, includes per-task friction points and session list (for the explorer).

### Phase E, Coaching panel + skill proposals (main agent, MANDATORY)

**Do not skip this phase.** The explorer is half-empty without it. `build_explorer.py` will refuse to run unless both `out/coaching-panel.json` and `out/skill-proposals.json` exist; override with `--allow-empty` is only for debugging.

#### E.1, Coaching panel

Read `out/profile.json` and `~/.claude/skills/task-profile/references/ai-first-principles.md`. Pick 3–5 principles where the user has a clear, evidenced gap. For each, cite ≥ 1 good-example session path and ≥ 1 friction-example session path. Write `out/coaching-panel.json`.

Schema:

```json
{
  "cards": [
    {
      "principle": "<short name of the habit>",
      "pattern": "<one-line description of the observed pattern>",
      "good_example": {"description": "<what worked here>", "session_path": "<path>"},
      "friction_example": {"description": "<what slipped>", "session_path": "<path>"},
      "suggested_adjustment": "<concrete habit to try next time>"
    }
  ]
}
```

#### E.2, Skill proposals

**Step 1, MANDATORY: enumerate what's already installed.** Before you write a single proposal, list every skill the user already has access to:

```bash
# User-level skills
ls ~/.claude/skills/ 2>/dev/null
# Project-level skills (if present)
ls .claude/skills/ 2>/dev/null
# Plugin-namespaced skills (read SKILL.md frontmatter to capture `description`)
for f in ~/.claude/plugins/cache/*/*/skills/*/SKILL.md ~/.claude/plugins/*/skills/*/SKILL.md; do
  [ -f "$f" ] && echo "=== $f ===" && head -5 "$f"
done 2>/dev/null
```

Also scan the transcripts: any `mcp__...` tool call, any `/<namespace>:<name>` slash command the user has typed, and anything the `coaching-panel.json` cites as "you do this well already", all of those are skills already in play. Collect the full list into a working set before proposing anything.

**Step 2, de-duplicate again