agent-self-reflection_skill

Overview

This skill performs periodic self-reflection on recent sessions to extract specific, actionable insights and append them to the appropriate workspace files. It runs as a cron job and focuses only on meaningful user interactions, skipping subagent and heartbeat sessions. The goal is concise lessons that improve future behavior and tool usage.

How this skill works

Every run lists sessions active in a recent window, filters for real user-facing sessions, and reads only the tail of each session transcript to stay within token limits. It analyzes message types, tool calls, errors, and patterns to produce targeted insights. Each insight is routed to the correct workspace file (process docs, tool notes, daily memory, or user memory) and written in a concise, structured format.

When to use it

• Hourly or regular cron-driven reviews of recent activity
• After deployments or when new tools are added
• When error rates or retries spike
• To capture evolving user preferences and temporary context
• When a session contains unusual tool behavior or repeated misunderstandings

Best practices

• Only tail the last ~50 lines of session files; never load full logs
• Skip subagent and cron:self-reflection sessions to avoid noise
• Make insights specific, actionable, and non-obvious (e.g., check file exists before editing)
• Check existing files first to avoid duplicating knowledge
• Append to daily memory files and surgically edit process or tool docs when needed

Example use cases

• Noting that a CLI tool needs a --json flag and adding that to the tool notes
• Recording that a user prefers terse progress updates in the user memory file
• Capturing a recurring confusion pattern and updating an agent workflow to disambiguate
• Logging a failed automated job and adding a remediation step to AGENTS.md
• Adding a short, dated entry to today's memory file about a time-sensitive decision