Self-Improving Assistant

What problem it solves

Agents often hit the same class of failures across sessions: command failures, unexpected API behavior, user corrections, stale knowledge, and one-off edge cases. These details usually disappear with the conversation context, so a future session may repeat the same mistake or treat a temporary issue as a permanent constraint. The cost grows when a project spans days of development, multiple contributors, or frequent external tool calls. This skill turns ephemeral context into inspectable, repeatable, promotable local logs: errors, corrections, and feature requests are written to Markdown files, and a stable Pattern-Key provides semantic-level deduplication.

How it works

The core loop is record, deduplicate, promote, and extract:
- Record immediately: capture failures, corrections, knowledge_gap items, and best_practice items in .learnings/LEARNINGS.md, .learnings/ERRORS.md, or .learnings/FEATURE_REQUESTS.md.
- Classify stably: use two-level area.symptom keys such as deps.module-not-found and auth.token-expired, so similar issues are not missed by keyword search.
- Merge recurrence: when an existing entry matches, update Recurrence-Count, Last-Seen, and See Also instead of creating a duplicate.
- Promote to workspace memory: when a lesson applies across files or workflows, distill it into SOUL.md, TOOLS.md, or AGENTS.md so later sessions inherit it.
- Extract as a skill: when the pattern is repeated, validated, and not project-specific, package it as a reusable skill.

Boundaries and cautions

It is not an automatic bug-fixing oracle; it gives the agent a memory and review mechanism. It is better suited to long-lived codebases, multi-turn agent workflows, and small teams that need to accumulate tool-specific pitfalls. Sensitive data should not be written directly into logs, automatic hooks should only be used in trusted environments, and entries should move from pending to resolved or promoted; otherwise the learning log becomes stale noise.