skill-retro
Review selected past or current Claude Code or Codex sessions against readable target skill sources and related integration. Produce source-linked proposals without applying changes.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-retro
- version
- 0.6.0
- description
- Review selected past or current Claude Code or Codex sessions against readable target skill sources and related integration. Produce source-linked proposals without applying changes.
02 资源文件 22
- 参考文档agents/prompt-advisory-analyst.md16.1 KB
- 参考文档agents/prompt-failure-analysis.md9.0 KB
- 参考文档agents/prompt-success-analysis.md9.8 KB
- 参考文档README.ja.md5.6 KB
- 参考文档README.md5.0 KB
- 参考文档README.zh-TW.md4.4 KB
- 参考文档references/claude-code-tools.md2.5 KB
- 参考文档references/codex-tools.md2.2 KB
- 参考文档references/runtime-protocol.md8.6 KB
- 参考文档references/source-inspection.md2.9 KB
- 脚本scripts/aggregate.py19.9 KB
- 脚本scripts/cluster.py7.7 KB
- 脚本scripts/event.py3.6 KB
- 脚本scripts/facets.py6.7 KB
- 脚本scripts/fixture_subagent_results.json2.3 KB
- 脚本scripts/friction_signals.py13.1 KB
- 脚本scripts/ingest.py20.7 KB
- 脚本scripts/main.py24.5 KB
- 脚本scripts/propose.py31.9 KB
- 脚本scripts/report.py6.2 KB
- 参考文档test-prompts.json2.2 KB
- 参考文档trigger-eval.json1.8 KB
03 SKILL.md 正文
Skill retrospective
Review selected past or current Claude Code or Codex sessions for recurring behavior of a readable target skill. For a current session, analyze only its captured snapshot through the capture cutoff; later appended events stay outside this run. The target source may be an explicit readable path without installation in the reviewing host. Produce proposals for its instructions or directly related plugin registration, loading, hooks, bundled scripts, and dependent connectors. This is a review-only workflow. The previous callable name was distill-sessions; use skill-retro now.
<skill-dir> is this skill's folder: ${CLAUDE_SKILL_DIR} on Claude Code, otherwise the folder containing this file.
Privacy and consent
Local ingestion reads supported Claude Code and Codex session logs and available Claude /insights facets. Retain observable user and assistant text, tool calls, and tool outputs. Exclude hidden or encrypted reasoning. A policy stop needs both an observable stop or ask and its reason. Do not write to session records.
main.py, propose.py, and report.py run locally. Before dispatching session-derived text to analysis agents or an optional advisory agent, show the local preview and obtain explicit scope approval. An explicitly named target skips only the target-selection pause; it does not waive approval for outbound analysis. Never send a trajectory above the 1M-token estimate (len(json.dumps(payload.input)) // 4 > 1_000_000); report the exclusion.
Workflow
- For automatic discovery run
python <skill-dir>/scripts/main.py --target-skill-pattern 'loom-code:*' > top.json. For selected past/current sessions runpython <skill-dir>/scripts/main.py --target-skill plugin:skill --session SESSION_ID > top.json; repeat--sessionfor each selected ID. This explicit mode requires an exact operator target, even without a recorded skill invocation, and bypasses discovery ranking, minimum count and caps. Missing IDs fail instead of substituting other sessions. Show the stderr preview, including skill and session friction. For a bare invocation, confirm the target subset before analysis dispatch. Selection does not change the two-session proposal threshold or consent requirements. - Read
top.json. Dispatch one independent analysis agent per trajectory usingagents/prompt-failure-analysis.mdoragents/prompt-success-analysis.md. Pass that trajectory's retained observable events,session_snapshot,source_inspections, target identity and optional source path. The orchestrator fillsinput.target_skill_pathfrom an explicit operator path or selected event evidence; no target installation is required. Preview selected session evidence and relevant source categories before consent. Follow source inspection before diagnosis: inspect target sources and directly related resources read-only within permissions and approved scope; disclose unavailable sources and historical uncertainty without invented anchors. Read runtime protocol for host calls and collection details. - Convert returned strict-markdown Memory Items to
merged.json. Keep eachsession_id,target_skill,target_skill_path,session_snapshot, and per-itemsource_inspectionsJSON list; retain per-session version attribution. Every item hastitle,description,content,kind, andissue_surface.skill-instructionsrequires a nonblank realsection_anchor.plugin-integrationrequiresintegration_subtype(registration,loading,hook,bundled-script, ordependent-connector), normalizedfailure_mechanism, and a concretesource_pointer; it has no SKILL.md anchor. Reject missing classification or source instead of guessing. If the integration source is unavailable, retain a bounded investigation candidate in the review narrative; do not put an unsupported item intomerged.json. - Run
python <skill-dir>/scripts/propose.py --input merged.json --target-skill /path/to/target/SKILL.md --output proposals.md. The renderer accepts only records with the exact target path or, for name-routed records, the full matchingplugin:skillidentity derived from<plugin>/skills/<skill>/SKILL.md; an ambiguous path cannot use name fallback. It groups instruction items by target, title and anchor, and integration items by target, subtype and failure mechanism. Two distinct sessions promote a proposal, including one that needs a new reference file; one session remains pending. Promoted instruction requests for new reference files enter the deferred bucket; promoted integration requests stay in integration proposals with a reference-file caveat. Only instruction items undergo SKILL.md heading checks. The proposal shows integration target, observed behavior, supporting sessions, source, proposed outcome, uncertainty, and verification idea. - Review the proposals and hand chosen changes to an independent implementation workflow. Do not modify the target skill, plugin, connector, or reviewed project from this retrospective. Proposal approval is a decision about what to implement later, not permission for this workflow to write.
Optional advisory report
Run report.py --input merged.json --lang zh-TW|en|ja, then dispatch dispatch_payload.input only with explicit consent. Its skill_dir key gives the analyst the local bundled resource path. Apply the same source inspection and per-session provenance contract to advisory analysis. The report complements per-target proposals and has no write authority.
Evidence and completion
Keep top.json, merged.json, and each per-target proposal for audit. Report target, analyzed trajectories, facet availability, overflow or validation exclusions, and artifact paths. An empty valid result means no qualifying evidence; malformed or missing artifacts are failures. Preserve pending, anchor-mismatch, and deferred-reference buckets even when no item promotes. Signals rank review order, not proof of a defect. A session contributing both success and failure observations still counts as one distinct session for a given cluster.
Stop on missing target, denied analysis consent, hidden reasoning, overlong payload, missing prompt or artifact, unclassified or unsupported item, or a failed relevant test. State what remains unresolved. Run tests with bytecode disabled:
PYTHONDONTWRITEBYTECODE=1 python -m pytest loom-workflow/tests/skill-retro/ -q
04 同仓库更多 Skills
using-loom-workflow
Route broad Loom workflow-tool requests to the right skill. Use when the request spans tools or the right workflow skill is unclear.
recap-state
Give an in-session recap of current progress for 'where were we', '我們剛剛在幹嘛', '剛剛講到哪', '我跟丟了', 'ちょっと振り返って', '今どこだっけ', or '振り返り'. The built-in /recap is an away-summary.
project-retro
Review one current or specified coding session for source-backed project development improvements. Use for a requested retrospective, including 振り返り seeking improvements; not for current-progress recaps or recurring skill mining.
loom-visualization
Show comparisons, flows, decisions, states or reasoning chains as tables, ASCII or Mermaid in coding chat, including when a Loom station reports to the user (intent restatement, choices, acceptance test results); not Obsidian notes.
loom-memory
Record repo-wide lessons when saving to your own memory or asked to remember; recall, reconcile, or forget them when a task needs it.
loom-interactive-diagram
Create and check editable diagrams during standalone or Loom work. Use when the agent needs to create a diagram for the user to edit in an external editor or read back saved changes; draw.io is the default format.