peterskoett/self-improving-agent
Overview
This skill captures learnings, errors, and feature requests so the agent and team can improve continuously. It prescribes where to log corrections, failures, and missing capabilities and how to promote broadly useful lessons into project memory. Use it to create reproducible entries that drive fixes, prevent recurrence, and inform future sessions.
How this skill works
When failures, user corrections, or missing capabilities occur, append structured entries to .learnings/ files: LEARNINGS.md for corrections and best practices, ERRORS.md for command or integration failures, and FEATURE_REQUESTS.md for requested capabilities. Entries follow a consistent template (ID, timestamp, priority, summary, details, suggested action, metadata) so other agents or developers can search, triage, and promote items into CLAUDE.md, AGENTS.md, TOOLS.md, or project memory. Periodic review and recurrence tracking guide promotion and systemic fixes.
When to use it
- A command or operation returns a non-zero exit code or an exception occurs
- A user corrects the agent ("No, that's wrong", "Actually...")
- A user requests a capability the agent does not have
- An external API or tool integration fails or times out
- The agent discovers its knowledge is outdated or a better recurring approach is found
Best practices
- Log immediately with full context and reproduction steps
- Use the provided templates (learning, error, feature) and consistent categories/tags
- Include suggested fixes or concrete next steps, not just observations
- Search existing .learnings/ first to avoid duplicates and link related entries
- Promote broadly applicable rules to CLAUDE.md, AGENTS.md, TOOLS.md, or SOUL.md
- Review pending and high-priority items before major tasks and weekly during active development
Example use cases
- A build step fails with a stack trace — append an ERR entry with command, output, environment, and suggested fix
- User corrects an API detail — add a LEARNING with category knowledge_gap and suggested doc update
- Multiple sessions report the same flaky test — create a recurring-learning, bump priority, and promote remediation steps to AGENTS.md
- User asks for a new export feature — file a FEATURE_REQUEST with context, complexity estimate, and suggested implementation
- Agent discovers a faster, safer pattern for deployment — add a best_practice learning and promote it to TOOLS.md or AGENTS.md
FAQ
Place it in the workspace root (e.g., ~/.openclaw/workspace/.learnings or ./ .learnings) so agents and developers can find and promote entries.
When should I promote a learning to project memory?
Promote when the lesson applies across tasks or contributors, prevents recurring mistakes, or meets recurrence criteria (seen multiple times or across sessions); convert it into a concise prevention rule in an appropriate target file.
