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)

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

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

Phase G, Persona card (main agent, MANDATORY)

Do not skip. build_explorer.py refuses to run without out/persona.json.

1. Run the deterministic feature helper: ```bash ~/.claude/skills/task-profile/scripts/persona_features.py ``` Produces out/persona-features.json with the numbers only.
2. Read ~/.claude/skills/task-profile/references/personas.md (the 20-persona catalogue + fallback Explorer).
3. Read out/persona-features.json, out/profile.json, out/coaching-panel.json, out/skill-proposals.json.
4. Pick one primary persona whose triggers fire most clearly in the feature sheet. Break ties by coherence with the coaching cards. If fewer than ~10 interactive sessions, pick The Explorer.
5. Optionally pick one secondary modifier. Leave modifier: null when none fits cleanly.
6. Write a 40–60-word tailored blurb, in second person, opening with a concrete behaviour and including one surprising number from the feature sheet. No em-dashes, hype words, brand names. Voice: observant friend, not marketing coach.
7. Write out/persona.json:

{
  "id": "<persona-slug>",
  "name": "<The Xxxx>",
  "tagline": "<catalogue tagline>",
  "modifier": "<slug or null>",
  "confidence_note": "<why this persona beats the others, one sentence>",
  "blurb": "<your rewritten 40–60-word blurb>",
  "highlight_stat": {"label": "<short>", "value": <number>},
  "top3_task_names": ["<short>", "<short>", "<short>"],
  "features_used": { ... relevant numbers cited in the blurb ... }
}

Phase F, Explorer HTML

~/.claude/skills/task-profile/scripts/build_explorer.py

Fixed light theme baked into the generator: off-white background, aquamarine accents, subtle dot-grid atmosphere, Geist sans-serif via Google Fonts, glassmorphism adapted for light. Single-file, no network at runtime (fonts via CDN). Data embedded as a JSON blob. Uses progressive disclosure, categories open to reveal tasks; tasks open to reveal friction and tokens; coaching and proposals open to reveal detail. Includes:

• Token-spend chart (horizontal stacked bars per task, clickable to jump to task detail)
• Sortable/filterable task table with search, category, min-frequency, since-date
• Row-click expands per-task detail: friction points with what-would-prevent guidance, per-model token table, session list
• Personal coaching panel (AI-first principle comparison)
• Skill proposals cards
• Automation-filter transparency footer

Open with open out/explorer.html.

Final manual review

Before considering the run done, scan out/profile.csv and the explorer for the top-100 highest-entropy tokens (any random-looking string of mixed case + digits ≥ 16 chars). These are the most likely way a secret slipped past automated redaction. Ask the user to confirm the scan is clean.

Outputs at a glance

| File | Audience | Shape | |---|---|---| | out/inventory.json | Internal | Full per-session rows with condensates | | out/clusters.json | Internal | [{cluster_id, label, session_paths}] | | out/payloads/*.json | Haiku subagents | Sampled condensates per cluster | | out/analyses/*.json | Internal | Haiku output, 1–3 tasks per cluster | | out/canonical-merges.json | Internal | Main-agent cross-cluster merge decisions | | out/profile.csv | Shareable with company | One row per canonical task | | out/profile.json | Feeds the explorer | Rich task rows + session detail | | out/coaching-panel.json | Feeds the explorer | Personal AI-first coaching cards | | out/skill-proposals.json | Feeds the explorer + user action | Up to 5 cross-cutting skill proposals | | out/explorer.html | Personal | Single-file UI with progressive disclosure |

References

• references/task-style.md, CSV-style task sentence rules, good/bad examples
• references/success-rubric.md, 4-level success taxonomy with signals
• references/friction-signals.md, correction phrases + behavioural markers
• references/automation-filters.md, rules for flagging non-interactive sessions
• references/redaction-rules.md, regex + heuristic rules for stripping secrets
• references/ai-first-principles.md, bootcamp + prompting principles used for coaching