agent-skills/skills/week-review/SKILL.md

name, description, user-invocable, argument-hint, allowed-tools

name	description	user-invocable	argument-hint	allowed-tools
week-review	Review the past week of Claude Code and Codex sessions, find recurring friction, and turn it into concrete config or tooling changes. Use when the user asks to review the week, review recent sessions, or asks what to improve about their setup. Also picks up carry-over items filed as issues on the agent-skills repo.	true	[--days N | --since YYYY-MM-DD]	Read Grep Glob Bash Edit Write WebFetch WebSearch

Week review

Find what went wrong repeatedly, fix the cause, file the rest.

The output is changes and issues, not a report. A finding nobody acts on was not worth the tokens to produce.

1. Carry-over first

Read the open issues before scanning anything. Last week's unfinished work is the highest-value input, and re-deriving it from transcripts wastes a lot of context.

source ~/.env.claude
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "https://git.naps.pt/api/v1/repos/yolo/agent-skills/issues?state=open&labels=weekly-review&limit=50" \
  | python3 -c "import json,sys; [print(f\"#{i['number']} {i['title']}\") for i in json.load(sys.stdin)]"

Read the bodies, not just the titles — several carry a design already argued through, so the run starts from the open question rather than from scratch.

Ask which to take this week. Do not silently re-litigate one the user already deferred; a deferred item stays open and gets one line in the summary.

2. Scan

python3 <skill-dir>/scripts/scan-sessions.py --days 7 --out <scratch>

Writes sessions.json (one record per session) and userturns.txt (every human turn, grouped). It drops subagent transcripts and flags swarm runs — collapse those to a single line, since one /code-review ultra can be 500+ sessions and 40% of the week's bytes without being 40% of the week's work.

Read userturns.txt in full. It is the primary evidence and it is usually 40-100k tokens. Do not sample it.

3. Find the friction

Rank by how often the same thing went wrong, not by how annoying any one instance felt. In order of signal strength:

• The same correction given more than once, especially across different repos. Four separate "stop putting decisions in the spec, use an ADR" corrections means the rule belongs in global config, not in each repo.
• A fix that did not hold. Something declared fixed in one session and recurring days later. Name both sessions.
• Crashes, /compact confusion, "are you there?", sessions restarted to rebuild lost state.
• Security slips — a secret echoed, an env value written somewhere it persists. These outrank everything above on consequence.
• Anything the user said twice in different words.

Quote the user verbatim with the date and repo. A finding without a quote is a guess, and the user can tell.

4. Check the docs before recommending

Model behaviour changes and last year's advice rots. Before proposing a prompt, skill, or config change, read the relevant page — do not answer from memory:

• platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5
• .../prompting-claude-fable-5
• .../claude-prompting-best-practices
• code.claude.com/docs/en/memory

Two findings from these that keep mattering: instructions to verify or re-check compound badly and should be removed, and prompt style leaks into output style, so a rule written in dense prose teaches dense prose.

Search for community practice too, and say which source a recommendation came from.

5. Measure before trimming

Always-loaded and on-demand are different budgets, and conflating them produces wrong advice.

Always loaded	On demand
entry files and every @import they pull	skill bodies
~/.claude/rules/*.md without paths: frontmatter	~/.claude/rules/*.md with paths:
the first 200 lines of each project's MEMORY.md	memory topic files
every skill's name + description

Count lines, not words — Anthropic's target is under 200 lines per file. Splitting one file into @imports saves nothing; only deleting content or adding paths: scoping does.

6. Apply, then file the rest

Propose a ranked shortlist with an appetite for each. Apply what the user agrees to, in this repo, and push. For anything deferred or too large, file a Gitea issue so next week starts from step 1 instead of a re-derivation.

This repo is public. Issues must carry no client names, no hostnames, no secrets, no internal ticket IDs. Describe the shape of the problem, not the customer it happened at. When quoting the user as evidence, strip identifying detail first.

Label every issue weekly-review (id 37) so step 1 picks it up next run. An issue filed without it is invisible to the next review.

source ~/.env.claude
curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  "https://git.naps.pt/api/v1/repos/yolo/agent-skills/issues" \
  -d '{"title":"...","body":"...","labels":[37]}'

Close issues that got done this week, with a one-line comment saying what landed.

Scope

Config, skills, hooks, and prompts. Not a project status report — the user has trackers for that. If a week's biggest problem is a product bug, say so in one line and move on.