SKILL.md
Reflect Codex Sessions
When to use this skill
- Summarize or reflect on past Codex session histories.
- List projects, session counts, or filter by date/session id.
- Retrieve/Refresh cached reflections or pull extra metadata for auditing.
Interpretation guidance (important)
- Treat reflection content as heuristics, not facts or ideas from a user. Use it as a starting point.
- Surface only non-niche, broadly useful themes and repeated patterns and confirm with the
user before acting on a pattern.
- Avoid over-indexing on one-offs; ask for confirmation when a pattern is uncertain.
Quick start
- Run commands from
scripts/inside this skill directory. - Default:
python3 reflect_sessions.py --output -. - Use
--output-style humanwhen replying in chat; use JSON for downstream parsing. - Ensure the shell command timeout is at least 120000 ms (2 minutes) so runs are not cut off.
- Use Python 3.11+ (the CLI relies on features not present in Python 3.9).
Workflow
- Choose scope:
--project,--since,--until,--session-id(s),--limit.
Note: the most recent session is skipped unless --include-most-recent.
- Generate reflections:
python3 reflect_sessions.py ...and adjust
--refresh-mode, --prompt-preset, --prompt-text, --prompt-file, or Codex flags only when asked.
- Respond carefully: highlight repeated, non-niche patterns and keep claims
tentative unless the user confirms them.
Prompt presets
Default preset: reflection.
Available presets:
reflection: Full reflection on repetition, friction, and skill ideas (default).summary: Concise summary of goals, actions, outputs, and decisions.bloat: Bloat/dead ends/cleanup opportunities introduced during the session.incomplete: Open loops and tasks left unfinished.decisions: Key decisions, alternatives, and rationale.next_steps: Concrete follow-up actions, tests, and validations.
Use --prompt-preset <name> to select one, --prompt-text "<prompt>" for inline prompts, or --prompt-file /path/to/prompt.md for a custom prompt file.
References
references/cli.mdfor the command catalog and full flag list.references/README.mdfor system behavior, cache semantics, and output schema.references/examples.mdfor an end-to-end example from ExampleProject.