# Add Lesson

> Add a new lesson learned to shared rules and sync to context files.

- Skill: `diegosouzapw/add-lesson` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/add-lesson`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/add-lesson/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/add-lesson

---


# Add Lesson Skill

Add a new lesson learned to the shared rules.

## Overview

When you discover a bug, mistake, or useful pattern, use this skill to document it so all agents learn from it.

## Usage

```
/add-lesson
```

## Prerequisites

- Access to `shared-rules/` and permission to run `scripts/sync-rules.py`.

## Lesson Template

```markdown
### YYYY-MM-DD - Brief Title

- **Issue**: What went wrong or was discovered
- **Root Cause**: Why it happened
- **Fix**: How it was fixed
- **Prevention**: Rule or check to prevent recurrence
- **Applies To**: all | claude | cursor | gemini
- **Files Changed**: List of affected files
```

## Process

1. **Gather information**:
   - What was the issue?
   - What caused it?
   - How was it fixed?
   - How can we prevent it?

2. **Add to lessons file**:
   - Open `shared-rules/lessons-learned.md`
   - Add new entry at TOP of "Recent Lessons" section
   - Use the template format

3. **Run sync**:
   ```bash
   python scripts/sync-rules.py
   ```

4. **Verify propagation**:
   - Check CLAUDE.md updated
   - Check timestamp

## Example

```markdown
### 2026-01-22 - Task Tool Token Efficiency

- **Issue**: Spawning Claude workers via subprocess was expensive (~13k tokens overhead)
- **Root Cause**: Full context duplication to each subprocess
- **Fix**: Use native Task tool with context filtering
- **Prevention**: Always prefer Task tool over subprocess for Claude workers
- **Applies To**: claude
- **Files Changed**:
  - `.claude/skills/implement-task/SKILL.md`
  - `CLAUDE.md`
```

## Categories

Lessons should be categorized by:
- `all` - Applies to all agents
- `claude` - Claude-specific
- `cursor` - Cursor-specific
- `gemini` - Gemini-specific

## Archiving

After 30 days or when list gets long:
- Move old lessons to "Archived Lessons" section
- Keep for historical reference

## Outputs

- Updated `shared-rules/` content and synced context files (e.g. `CLAUDE.md`).

## Error Handling

- If sync fails, do not proceed; resolve and rerun `scripts/sync-rules.py`.
- If lesson template is incomplete, request the missing fields before adding.

## Related Skills

- `/sync-rules` - Sync shared rules into context files