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, plus each session's sub-agent transcripts at <project>/<sid>/subagents/** (workflow agents one level deeper)
  • 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)

~/.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.

Two things about the token totals, because they are measured over different scopes.

1. A session's tokens include its sub-agents. Sub-agent and workflow-agent transcripts are separate files but the same unit of work, so they roll into the session that spawned them. turns stays main-session-only, so a session can show few turns and a very large token total. That is fan-out, not a contradiction; say so rather than letting the reader trip over it. subagent_files and subagent_turns give the size of the fan-out, and tokens.main_by_model / tokens.subagent_by_model split the model mix so a model the user chose for the conversation is never confused with one a sub-agent ran.
2. One turn = one assistant message. Claude Code writes one JSONL line per content block (thinking, text, each tool_use) and repeats the same usage object on every line, so counting lines would inflate both turns and tokens by roughly 2-3x. The inventory dedupes by message.id.

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:

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

Then run:

~/.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:

{
  "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:

# 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 against reality. For every task cluster you might propose a skill for, ask:

• Is there already an installed skill whose description covers this territory? If yes, DO NOT propose a parallel skill. Either skip the proposal or reframe it as "enhance <existing-skill> with X", scoped narrowly to the gap.
• Is the gap just that the user doesn't know the skill exists, or that the trigger description is weak? If yes, the proposal is "update trigger for <existing-skill>", not a new skill.
• Does this overlap with a plugin skill (e.g. a memo template, a design system, a people-management namespace)? Plugins already ship the canonical implementation; re-inventing them is noise.

A proposal that duplicates an installed skill is a worse recommendation than no proposal at all. Five sharp proposals are better than five padded ones, and two sharp proposals beat five mediocre ones. Do not pad the list to reach 5.

Step 3, propose. Up to 5 atomic skills, each impacting ≥ 2 top tasks (breadth) and following the task-centric shape: prescriptive mandatory_steps, bundled sources-of-truth (guidelines, prior-art scripts, templates), fixed output_shape, invocation-as-slash-command. Avoid abstract workflow shapers ("opener-template", "staged-drafts", "checkpoint"), these sit outside a task and so don't get invoked in context.

For each proposal emit to out/skill-proposals.json:

• name, slug for the skill
• trigger_description, SKILL.md frontmatter description
• modelled_after, the existing installed skill it takes inspiration from, one line (REQUIRED, non-empty, references a real skill from Step 1)
• overlaps_considered, list of installed skills that cover adjacent territory + one-line why this proposal is still distinct (REQUIRED; empty list is only valid if the domain is genuinely uncovered)
• mandatory_steps, ordered list the skill runs every time (MANDATORY reads of guidelines/prior-art/references)
• output_shape, fixed filename convention + required sections
• tasks_impacted, ≥ 2 entries with task_id + why_relevant
• expected_savings, small/medium/large + why
• invocation_hint, /skill-creator <name>

Add a top-level _installed_skills_checked array to skill-proposals.json listing every skill enumerated in Step 1, so the user can verify the pre-check actually ran.