lessons

Engineering Community

Repo stars 3,507
License Apache-2.0
Author repo okteto

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Record a lesson learned after a user correction, or review existing lessons at session start Manages the self-improvement loop.…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Lesson file”, “Workflow: Recording a Lesson”, “Step 1: Read the current lessons file”, “Step 2: Identify the lesson”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name lessons directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Lesson file / Workflow: Recording a Lesson / Step 1: Read the current lessons file” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Lessons Skill

Manages the self-improvement loop. Use this skill when:

The user corrects a mistake or gives feedback that should change future behavior
You want to review past lessons at the start of a session
After completing a task, to capture any patterns worth preserving

Lesson file

All lessons live in .claude/lessons.local.md.

Workflow: Recording a Lesson

Step 1: Read the current lessons file

cat .claude/lessons.local.md

Step 2: Identify the lesson

From the user correction, extract:

Mistake: What went wrong (be specific, not generic)
Pattern: The concrete rule to apply going forward
Trigger: The condition that should activate this rule

Step 3: Append the entry

Add a new entry at the bottom of .claude/lessons.local.md, above the closing comment:

## 2026-03-17 — [short title]

**Mistake**: [What went wrong]
**Pattern**: [Rule to apply going forward]
**Trigger**: [When to apply this rule]

Use absolute dates (YYYY-MM-DD), never relative ("today", "last week").

Step 4: Confirm

Report the new entry to the user briefly:

Lesson recorded: [short title]

Workflow: Reviewing Lessons

At the start of a session, or when asked:

Read .claude/lessons.local.md
Identify lessons relevant to the current task
Internalize them — do not re-state them all back to the user unless asked
Apply them silently

Workflow: Pruning Lessons

Lessons become stale when:

They reference a pattern that's been fixed in the code
They duplicate another lesson
They're too generic to be actionable

When pruning, remove the entry entirely. Don't leave tombstones.

Rules

Never invent a lesson that wasn't triggered by an actual correction
Be specific: "always read the file before editing" is better than "be careful"
One lesson per entry — don't bundle unrelated corrections together
Update an existing lesson if a correction refines a known pattern rather than creating a duplicate

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Engineering
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 94 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @okteto · Apache-2.0
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview lessons.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# Lessons Skill

Manages the self-improvement loop. Use this skill when:

- The user corrects a mistake or gives feedback that should change future behavior
- You want to review past lessons at the start of a session
- After completing a task, to capture any patterns worth preserving

## Lesson file

All lessons live in `.claude/lessons.local.md`.

## Workflow: Recording a Lesson

### Step 1: Read the current lessons file

```bash
cat .claude/lessons.local.md
```

### Step 2: Identify the lesson

From the user correction, extract:

- **Mistake**: What went wrong (be specific, not generic)
- **Pattern**: The concrete rule to apply going forward
- **Trigger**: The condition that should activate this rule

### Step 3: Append the entry

Add a new entry at the bottom of `.claude/lessons.local.md`, above the closing comment:

```markdown
## 2026-03-17 — [short title]

**Mistake**: [What went wrong]
**Pattern**: [Rule to apply going forward]
**Trigger**: [When to apply this rule]
```

Use absolute dates (YYYY-MM-DD), never relative ("today", "last week").

### Step 4: Confirm

Report the new entry to the user briefly:

```
Lesson recorded: [short title]
```

## Workflow: Reviewing Lessons

At the start of a session, or when asked:

1. Read `.claude/lessons.local.md`
2. Identify lessons relevant to the current task
3. Internalize them — do not re-state them all back to the user unless asked
4. Apply them silently

## Workflow: Pruning Lessons

Lessons become stale when:

- They reference a pattern that's been fixed in the code
- They duplicate another lesson
- They're too generic to be actionable

When pruning, remove the entry entirely. Don't leave tombstones.

## Rules

- Never invent a lesson that wasn't triggered by an actual correction

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Lesson file → Workflow: Recording a Lesson → Step 1: Read the current lessons file → Step 2: Identify the lesson → Step 3: Append the entry → 2026-03-17 — [short title]
terms    -> Mistake · Pattern · Trigger · Manages the self-improvement loop. · All lessons live in .claude/lessons.local.md. · Use absolute dates (YYYY-MM-DD), never relative ("today", "last week"). · 1. Read .claude/lessons.local.md 2. · When pruning, remove the entry entirely.
files/cmd -> .claude/lessons.local.md
body sha256 -> d2414a6b9d2d