How to Read an Agent Transcript to Find Dead Skills

Agent skill catalogs grow because nothing in the system forces them to shrink. Skills arrive from past projects, from shared team installations, from upstream library updates, and each one stays installed long after the task that justified it has ended. The cost of that accumulation is not abstract: in the progressive-disclosure model, an agent reads skill metadata at session start to decide whether to load the full instructions, and that metadata cost gets paid on every single session regardless of whether the skill ever fires. A skill nobody has touched in months still taxes every conversation the agent runs. Most teams believe they know what's installed because they can list it, but a list only shows what's present. Only a session transcript shows what a skill actually did, and the space between those two things is where this piece spends its attention.

What an agent transcript contains

A transcript is the one record that captures both halves of the story: what the agent loaded and what it actually used. No skill directory and no dependency manifest can stand in for it, because both only describe what could run, not what did. Tools like Claude Code and Codex CLI write these as JSONL session logs, line-delimited JSON where each entry marks an event in the conversation, including the moments when a skill gets invoked. Hermes used to work the same way, but it has since moved its canonical session storage to SQLite, with any leftover JSONL files in its sessions folder now inert and no longer read by the agent. skillreaper, a tool built for exactly this kind of transcript analysis, reads JSONL files directly, counting tool_use blocks and command invocations. For OpenCode, which stores history in SQLite, skillreaper pulls that data through the sqlite3 command-line tool when it's available on the system path. Without sqlite3 installed, OpenCode support drops to inventory-only: the tool can tell you what's installed but not what fired.

Not every platform offers this level of visibility. Cursor keeps no local transcripts, so it supports only inventory-only analysis. OpenClaw lands in the same inventory-only category, but for a different reason: it has no session history to read. Cloud-hosted agents run into comparable limits, because the end user may simply not be able to reach the record of what happened during a session. Where exactly a given tool stores its logs varies, and each platform documents its own session log path, but the underlying fact holds across all of them: the file exists locally, it's plain text, and it's readable without specialized software. Every verdict in this piece gets built from that raw material.

The four verdicts that turn raw transcript data into decisions

Reading a transcript only matters if it ends in a decision about what to do with a skill. The skillreaper framework defines five possible outcomes, and each one maps to a specific action a team can take with confidence.

REAP means the skill shows zero invocations across the session window under review. It's safe to quarantine, not delete, because quarantine can always be reversed if the skill turns out to matter later.

REAP(broken) means the skill was invoked but the invocation errored. This is a fundamentally different failure than cold disuse, and it calls for repair or removal, not a simple quarantine.

MUTE applies when a skill gets invoked rarely but carries a heavy description in the catalog layer. The fix is to strip that description out so it stops costing tokens on sessions where the skill won't fire, while leaving the skill itself available for explicit invocation when needed.

KEEP covers skills invoked regularly, skills small enough that their catalog cost barely registers, or skills a team has flagged by hand as protected regardless of usage.

REVIEW covers everything else: insufficient session history, or evidence that's been flagged incomplete. These don't get acted on yet.

Of the five, the split between REAP and REAP(broken) carries the most operational weight. A skill that fires and then errors is signaling a broken integration or an upstream rename, the kind of thing that happened in Traigent's pull request #2315, and that signal has nothing to do with disuse. Pruning that skill instead of fixing it means losing a capability the team still actively wants, not clearing out dead weight.

Reading the catalog layer: finding skills that were loaded but never fired

Every session begins with the agent printing a catalog of the skills it has loaded, each one listed by name and description. As the session proceeds, tool_use entries appear whenever the agent actually invokes one of those skills by its ID. The comparison between those two record types, the catalog at the top and the invocation entries scattered through the rest of the transcript, is the single most useful signal for spotting dead skills, and reading it requires no special tooling.

A skill ID that shows up in the catalog but never once appears in a tool_use entry, across several sessions rather than just one, is a REAP candidate. The qualifier about multiple sessions matters: a skill can legitimately go unused in any single session without being dead. A skill built for an iOS simulator workflow will show zero fires on every web-only project session, and that's expected; it doesn't mean the skill's been neglected. So build up evidence across enough sessions that a genuine pattern becomes visible before you conclude a skill is cold.

Doing this by hand works fine for a small team or a one-off audit: pull every skill ID out of the session header, then search the rest of the transcript for each ID appearing in tool_use position. skillreaper automates the same comparison at scale, counting tool_use blocks per skill ID across an entire transcript corpus, surfacing the zero-count IDs as REAP candidates, and routing anything with incomplete evidence to REVIEW.

Reading invocation patterns: separating cold skills from broken ones

A skill that shows up in tool_use blocks but keeps producing errors is broken. It's broken, and treating the two as the same thing is the single most common mistake a naive transcript audit makes, since it leads straight to pruning a capability the team still needs. The signal to watch for is a tool_use entry immediately followed by an error response: a tool-not-found message, a failed invocation, an empty return where a substantive result should be. That pattern, repeated across sessions, marks a skill as broken.

The difficulty is that a transcript alone often can't tell you why a skill is broken. A skill that's been renamed upstream produces invocation evidence that looks the same as a skill that's simply misconfigured or whose MCP server has gone down. Traigent's pull request #2315 is a concrete case of exactly this: a skill that had been working fine suddenly started failing because its upstream identity shifted, not because anyone stopped wanting to use it. Telling that apart from a genuine misconfiguration means going back to the skill file itself and checking it against its current upstream ID, something no amount of transcript counting can substitute for.

The practical rule follows directly: if a skill's invocation count is nonzero but its error rate on those invocations runs high, the right verdict is REAP(broken), and the right next step is investigating the skill definition before anything gets quarantined. skillreaper tracks this as a separate category from zero-fire items specifically so that repair work and pruning work don't get confused with each other.

Reading token weight: identifying heavy skills worth muting rather than removing

Muting a skill strips its description out of the catalog layer so it no longer costs tokens on every session, while leaving the underlying skill fully available for explicit invocation whenever it's called for. That distinction matters because a skill with a long, detailed description pays its full token cost at session initialization on every session, whether or not it ends up being used. A skill that fires in a small fraction of sessions but carries an outsized description has its cost structure backwards: the token spend is heaviest exactly where the value delivered is lowest.

Spotting this pattern in a transcript means looking for the combination of low invocation counts and long descriptions together, not either one alone. A rarely used skill with a short description isn't much of a problem. A heavily used skill with a long description is earning its keep. It's the pairing of rare use and heavy weight that marks a MUTE candidate. Deadskills, a separate tool built around this kind of analysis, reports per-skill invocation counts and token cost estimates alongside a three-way classification of active, zombie, and dead, where zombie means invoked before but silent for 90 or more days. So teams get the weight dimension without counting characters in every skill description by hand, though Deadskills' own documentation doesn't describe an automated remediation step, so someone still has to strip a description down by hand.

Reading the REVIEW queue: skills with too little evidence to act on

Acting on thin evidence is what makes a transcript audit lose credibility, and the REVIEW verdict exists to keep that from happening. Three situations push a skill into REVIEW. A newly installed skill hasn't had enough sessions yet to establish any kind of baseline. A platform's transcript record might be oversized or unreadable, which leaves the evidence for that skill marked incomplete. Or the session corpus overall is too small to tell a genuinely rare but legitimate skill apart from one that's simply dead.

The conservatism built into this step is correct. Incomplete evidence should never produce a REAP or a MUTE verdict. The item stays in REVIEW, flagged with a warning naming whatever platform the gap applies to, until more evidence accumulates. If a skill has fewer sessions behind it than a team's own minimum confidence window calls for, it carries forward to the next audit cycle. This also covers skills tied to specific project phases, a migration skill or a deploy-review skill, which will look cold during an ordinary sprint simply because the work that calls for them hasn't come up yet. A transcript can't supply that context on its own; it takes someone who knows what phase the team is actually in.

None of this represents a gap in the method. It's the method being honest about the limits of what a given set of sessions can prove, and teams should read the REVIEW queue as a watchlist rather than a set of skills granted indefinite protection. The queue shrinks on its own as more sessions accumulate and more evidence becomes available, which is what turns a single audit into something closer to an ongoing process.

Turning a one-time audit into a repeatable operational practice

One audit clears out whatever dead weight has built up to that point. It does nothing to stop the same weight from building back up, because the mechanism that created it in the first place, skills as version-controlled files that accumulate with no automatic retirement, is still running after the audit ends. Only a scheduled, repeated audit closes that loop.

A workable cadence runs a transcript analysis pass at the end of each major project phase or sprint cycle, while the skill set relevant to that phase is still fresh in both the transcript history and the team's memory of what they were actually working on. Quarantine stays the right default at every pass: a skill that looks dead in the context of one project can turn out to be what the next project needs, and skillreaper's design treats reversibility as a core principle.

The review cycle needs one more layer beyond invocation counting: checking skill IDs against their upstream sources. The Traigent case already showed that a skill can go from working to broken between one audit and the next without anything changing locally at all, purely because something shifted upstream. Teams running shared environments need to diff their skill IDs against upstream sources as a standing part of the review, not treat invocation counts as the whole picture.

One more layer belongs ahead of all of this. A 2026 survey of agent skill lifecycle practices describes a class of cold skills that have nothing to do with disuse at all: skills blocked by a security scanner or by operator policy, which will look exactly like REAP candidates to a transcript analysis that doesn't know a block happened. Mature pipelines now run security scanning before transcript analysis for this reason, cross-referencing scanner verdicts first so that a policy-blocked skill doesn't get misread as an abandoned one. Reading a transcript tells a team what fired and what didn't. Cross-referencing it against scanner history and upstream source changes tells them why, which is what keeps a catalog clear on an ongoing basis.