SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssession-review

session-review

Agents & models

View repository

Updated 10-16 01:29

About this skill

Session Review

Go through all the AI conversations that people personally participated in under the project, organize them into an interactive HTML report, finally publish it as an artifact, and leave a copy on the desktop

Parameters

  • No path given: use the project of the current session, first run git rev-parse --show-toplevel to get the project root directory; if it is not a git repo, use the current working directory
  • One path given: analyze only that project
  • Multiple paths given (space-separated): merge into the same report, tag every session, skill, and quote with its project, and add a project filter to the report
  • --since YYYY-MM-DD: only look at sessions with activity after this day
  • --no-global: do not scan skill usage records from other projects; faster, but removal suggestions will lack one layer of judgment, and the report must note this
  • Paths can use ~; if a path does not exist, tell the user first, do not silently skip it

Process

1. Collect data

python3 <這個 skill 的目錄>/scripts/collect.py --out <scratchpad>/session-review [--since ...] [--no-global] <路徑 ...>

Output three files:

  • summary.json: counts by category, skill ranking (split into user-invoked user and AI-invoked model), subagents, tools, daily message counts, summary of each session
    • installed_skills: all currently installed skills (user scope, the project's .claude/skills, skills and commands of installed plugins), each with source, path, whether it is a symlink, whether the plugin is enabled, whether it is for internal use (user-invocable: false), description, count during this period uses_here, count across all projects uses_global, last used date, number of projects used
    • unused_here: list of skills with 0 uses during this period, enabled, and not for internal use; this is the starting point for removal suggestions
  • messages.txt: user messages grouped by session, truncated if over 400 characters; this is the main reading material
  • messages.json: full messages; look here when you need to quote long passages verbatim

Things the script already handles, do not redo: automated sessions (entrypoint starts with sdk, e.g. the security review run after every change) are counted only and not analyzed; duplicate messages caused by backtracking or resending are deduplicated by uuid; built-in commands (/clear, /model, etc.) do not count as skills; sessions under worktree are counted toward the main project

2. Read all conversations

  • Read messages.txt from beginning to end, do not just sample
  • When a file exceeds about 250KB, dispatch Explore subagents in batches by session; each returns: what this batch of sessions is doing, speaking patterns during development and debugging, verbatim quotes (with session id), recurring requests; the main conversation only collects conclusions
  • When needed, use Bash for keyword counts to support how many times a pattern appears and in how many sessions

3. Analyze content

The report must answer these six things; see details in references/report-spec.md

  1. Skill usage ranking: bar chart sorted by count, switchable between all, user manual, and AI-invoked; click a bar to see description, session count, and project; also compare against the workflow claimed in the user's CLAUDE.md and list whether it is actually being used
  2. Converged workflow: first load /diagram-design; if not installed, follow references/diagram-fallback.mdAt least draw two diagrams (a swimlane diagram for feature development and a debugging flowchart), with text cards explaining step by step, plus charts such as a timeline and daily message counts; do not use only one form of presentation
  3. How to communicate during 0-to-1 development: Summarize 5 to 8 patterns, each with 1 to 3 verbatim quotes
  4. How to communicate during debugging: Same as above, and also organize the moments that made the user impatient; these are usually the rules that CLAUDE.md should add
  5. Repetitive processes that can be turned into custom skills: Each suggestion must have occurrence counts and session counts as evidence, what it would do, a SKILL.md draft, and whether it is suggested to go in user or project scope with reasons
  6. Skills suggested for removal: Judge by the criteria in step 5, and for each one write out the reason for the judgment and how to remove it

4. Determine user or project scope

Every skill suggestion must be labeled with scope and include the installation path

Judgment question Yes No
Does the content mention things that only exist in this project (APIs, components, branch names, business rules)? project user
Should colleagues who take over also follow this approach? project, commit to git user
Does it touch the user's personal things (personal notes, personal preferences)? definitely user
When merging across multiple projects, does this pattern appear in two or more projects? user, leave project differences to each project's CLAUDE.md or lore see the first three questions

Path notation:

  • user scope：~/.claude/skills/<name>/SKILL.md, if the user's ~/.claude/skills is symlinked from a dotfiles repo, put it in that repo and remind them to commit
  • project scope：<專案>/.claude/skills/<name>/SKILL.md, commit to git

5. Determine skills that can be removed

From summary.json 's unused_here , judge one by one; only give suggestions, do not delete anything

Exclude first, do not include in suggestions

  • Internal-use skills (internal is true), and skills depended on by name by other skills, hooks, or CLAUDE.md; use grep to search for their names in ~/.claude/skills, project .claude/、~/.claude/CLAUDE.md, and hooks settings
  • List disabled plugins on a separate line, explaining that they are disabled and do not occupy triggers; whether to uninstall is up to the user

Then check whether there are similar needs in the conversations

  • Extract 3 to 6 keywords from the skill's name and description, in both Chinese and English; for example, for remotion video types extract 影片, 剪輯, 字幕, video, remotion
  • Use these keywords to search messages.json 's user messages and see whether related things are mentioned; if so, note the verbatim quote and session id
  • Keywords should capture the need itself, not just the skill name; users talk about what they want to do, not what the skill is called

Divide into four categories

Category Condition Suggestion
Suggest removal 0 times during this period, 0 times across all projects or unused for a long time, and no similar needs at all in the conversations Remove
Not used in this project 0 times during this period, no similar needs in the conversations, but used in another project Keep for user scope or plugin; remove if project scope
Keep but change the description 0 times during this period, but there are similar needs in the conversation Keep it. The AI should have invoked it but did not. It is recommended to rewrite the trigger words in the description, and include that exact quote
Observe first Installed within the last 30 days, or the count is too low to determine Do not change for now

When using --no-global there are no counts for all projects. Category 1 and Category 2 should be merged into one category, and this should be noted in the report

The removal method must be clearly stated

  • user scope: delete ~/.claude/skills/<name>; if it is a symlink (symlink_to has a value), delete only the shortcut, and remind where the original is in which repo, whether to delete it too, and whether to commit
  • project scope: delete <專案>/.claude/skills/<name> and commit, and remind colleagues that they will also lose this skill
  • plugin: it is not possible to delete only one skill in a plugin. Only when all skills in the same plugin match should you recommend /plugin uninstall <plugin>@<marketplace>. If only some match, clearly state which ones are unused and which others are still in use

6. Make it into HTML and publish

  • If the Artifact tool is available, first run its quickstart (use other for intent) to get the page specification. For images, use /diagram-design 's color palette and rules. If it is not installed, use references/diagram-fallback.md 's built-in same set
  • For layout and interactions, follow references/report-spec.md 's page structure. Reuse diagram-design for the color palette and fonts (or the token table in the fallback), and keep the same set of tokens across the whole page
  • If the environment has the Artifact tool, publish it as an artifact; otherwise, only generate a local file and open it in the browser. Save the local file to ~/Desktop/<專案名>-ai-review.html(for multiple projects use multi-project-ai-review.html). The local version must add doctype, head, and body yourself
  • At the end of the page, you must embed assets/layout-guard.js(after your own script). It will automatically shrink or truncate flowchart text that does not fit in nodes, and it also provides an inspection mode
  • Before starting to write the layout, first read the layout foolproofing rules in report-spec.md
  • Before publishing, use node to check once whether the embedded script can be parsed

7. Pre-publish layout check (cannot be skipped)

python3 <這個 skill 的目錄>/scripts/check_layout.py <報告.html> --shots <scratchpad>/session-review/shots
  • The script will use background Chrome to open the report at four widths: 1280, 900, 600, and 390, and find: text overlapping each other, charts pressing on titles, elements running out of cards, text exceeding containers, fields squeezed onto one line with only a few characters left, flowchart text exceeding nodes or being automatically shrunk/truncated, and horizontal scrolling of the whole page
  • If there are any issues, fix them, then rerun after fixing, until all four widths have 0 issues before publishing
  • After passing, look at at least one screenshot (600px recommended) to confirm there is no strange layout that the script cannot catch
  • When Chrome cannot be found (exit code 2), tell the user that the check was not run, and ask them to set the CHROME environment variable. Do not treat it as passed

Writing rules

  • Write the report in the language the user normally uses in conversation. If the user's CLAUDE.md has formatting rules for file content (punctuation, wording), follow them. The SKILL.md draft placed inside a code block is not restricted
  • Use plain language, describe the screen and behavior, and do not pile on jargon
  • Quote the original words verbatim, present them in a quote block, do not add quotation marks, and include the session id
  • Keyword classification is only a rough grouping. Note in the report that it is enough to look at the proportions
  • Business rules in the SKILL.md draft may only include those confirmed in the conversation. Leave the rest blank and clearly state that they are to be filled in later. Do not guess

Finally, reply to the user

  • Include the artifact link (if any) and the local file path
  • Summarize four to five key findings in a few lines
  • Describe the data scope: how many sessions were included, how many automated sessions were excluded, and whether Codex is included