Self-Improving AI Agent

The Problem in Focus

AI agents executing coding tasks often encounter persistent challenges:
- Ephemeral Learning: Insights gained from errors, user corrections, or debugging sessions are not retained across sessions, leading to repeated mistakes and lost opportunities for improvement.
- Recurring Failures: Common issues such as API timeouts, command failures, or code defects reappear without systematic logging or prevention, increasing debugging overhead.
- Knowledge Silos: Project-specific conventions, architectural decisions, and best practices are scattered or undocumented, forcing each new agent or contributor to re-discover them from scratch.

This skill provides a structured self-improvement workflow to address these issues systematically.

Core Mechanisms

Structured Logging System

The skill creates a .learnings/ directory in the project root with dedicated templates for different event types:
- LEARNINGS.md: Logs learning entries with categories like correction, knowledge_gap, best_practice, and simplify-and-harden. Each entry includes metadata such as Priority, Area, and Pattern-Key for filtering.
- ERRORS.md: Records command or operation failures, including integration details, reproduction steps, and resolution status.
- FEATURE_REQUESTS.md: Captures user-requested features with metadata and status tracking.

Each entry uses a standardized ID format, for example LRN-20250115-001, where LRN indicates type, YYYYMMDD is date, and XXX is a sequential or random suffix. Entries can be linked via See Also references to track related issues.

Promotion to Project Memory

When a learning meets promotion criteria (recurrence count ≥3, seen across ≥2 tasks, within 30 days), it is promoted to project-level memory files for persistent guidance:
- CLAUDE.md: Stores project facts, conventions, and gotchas for all Claude interactions. Promoted rules are written as concise prevention rules.
- AGENTS.md: Stores agent-specific workflows, tool usage patterns, and automation rules.
- .github/copilot-instructions.md: Provides project context for GitHub Copilot.

Promotion involves distilling the learning into a short rule, adding it to the target file, and updating the original entry status to promoted. This ensures that valuable knowledge is not lost and is available to all agents and contributors.

Automation and Multi-Agent Integration

The skill supports automatic reminders via hooks to integrate with agent workflows:
- For Claude Code, configure .claude/settings.json to inject a learning evaluation reminder after each prompt (~50-100 tokens overhead) using scripts/activator.sh.
- An error detector hook (scripts/error-detector.sh) parses tool responses for error patterns and emits reminders, available for Claude Code, Codex CLI, and GitHub Copilot (though Copilot hooks only log, not inject context).

Additionally, the skill can extract reusable sub-skills from learning entries. When a learning qualifies (e.g., recurring, verified fix, broadly applicable), it can be extracted using a helper script or manual creation, updating the entry status to promoted_to_skill.

Applicability and Considerations

• Configuration Required: Full automation requires setting up hooks as per agent type (Claude Code, Codex CLI). For GitHub Copilot, integrate via .github/copilot-instructions.md. The skill works in multi-agent environments with agent-specific activation.
• Team Collaboration: Logs can be kept local (per-developer) by adding .learnings/ to .gitignore, or tracked in the repository for team-wide knowledge sharing. A hybrid approach can track templates while ignoring entries.
• Promotion Threshold: Strictly adhere to the three-condition rule (recurrence ≥3, across ≥2 tasks, within 30 days) to avoid promoting trivial or one-off learnings prematurely.
• Skill Extraction: Only extract learnings as new skills when they meet criteria such as recurring patterns, verified fixes, and broad applicability. This prevents skill bloat and ensures quality.
• Periodic Review: Regularly review .learnings/ at natural breakpoints (e.g., before major tasks, after features, weekly during active development) to resolve fixed items, promote applicable learnings, and link related entries.

By following this workflow, AI agents can achieve continuous learning, reduce repeated errors, and effectively transfer knowledge across sessions and projects.