# Learn

> Extract non-obvious session learnings into scoped AGENTS.md files

- Skill: `d-o-hub/learn` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add d-o-hub/learn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/d-o-hub/learn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: d-o-hub (https://skillmd.com/u/d-o-hub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/d-o-hub/learn

---


# Learn

Extract non-obvious session learnings into scoped `AGENTS.md` files to preserve knowledge across sessions.

## When to Use

Activate after completing a non-trivial task to capture insights that would otherwise be lost.

## Instructions

### What to Capture (Non-Obvious Only)

- Hidden relationships between files or scripts not obvious from code.
- Execution paths that differ from what the code appears to do.
- Non-obvious config, env vars, or flags (see root `AGENTS.md` and `agent_docs/building_the_project.md`).
- Debugging breakthroughs where error messages were misleading.
- Files that must change together (e.g., `AGENTS.md` + `agent_docs/AVAILABLE_SKILLS.md` when adding skills).
- Build/test commands not documented in README.
- Architectural constraints discovered at runtime.

### What NOT to Capture

- Obvious documentation or standard behavior.
- Duplicates of existing entries.
- Verbose explanations or session-specific notes.

### Scoping Rules

Place learnings in the most specific `AGENTS.md` file:
- **Project-wide**: Root `AGENTS.md`.
- **Script-specific**: `scripts/AGENTS.md`.
- **Skill-specific**: `.agents/skills/<name>/AGENTS.md`.

### Dual-Write Requirement

Every new non-obvious insight must be recorded in two places:
1. **Verbose Log**: Add a full `LESSON-NNN` entry to `agent_docs/LESSONS.md` with Issue/Root Cause/Solution.
2. **Distilled Note**: Add a 1–3 line note to the nearest `AGENTS.md` (this is what `learn` automates).

If `agent_docs/LESSONS.md` does not exist yet, create it before relying on the dual-write workflow.

### Format

- 1–3 lines per insight in `AGENTS.md`.
- Fits within `MAX_LINES_AGENTS_MD=150` constraint.
- Bulleted list under a "Learnings" or "Context" section.

## Reference Files

- `agent_docs/LESSONS.md` - Project-wide lessons log.
- `AGENTS.md` - Root agent guidance and constraints.
- `agent_docs/README.md` - Index of workflow-impacting reference files.