# Agent Learning

> Agent learning patterns and quality guidelines. Use when commands or agents need to determine when and how to record learnings, apply quality gates, or retrieve past knowledge using ranked retrieval.

- Skill: `kinginyellows/agent-learning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/agent-learning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/agent-learning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/agent-learning

---


# Agent Learning Patterns

## What It Does

Defines when to record learnings, quality standards for entries, and retrieval
strategies. Loaded by memory-related commands and agents for consistent learning
behavior.

## When to Use

Use when yellow-ruvector plugin commands or agents need guidance on learning
triggers, quality gates, or retrieval ranking.

## Usage

This skill is not user-invocable. It provides shared context for the
yellow-ruvector plugin's learning workflows.

## Learning Triggers

### Record a Context Entry When (type: `context`)

- Test failure that required a code fix
- Lint or type error that needed resolution
- User corrected the agent's approach
- Agent retried after an error and succeeded
- Build or deploy failure

### Record a Decision Entry When (type: `decision`)

- Complex operation succeeded on first attempt
- User explicitly praised a technique
- Clean solution to a recurring problem
- Novel approach that worked well

### Record a Code Entry When (type: `code`)

- Debugging revealed "X caused Y"
- Configuration change resolved an issue
- Performance investigation found a bottleneck
- Dependency update triggered a regression

### Skip Recording When

- Trivial file reads or searches
- Simple, routine operations
- Information already captured in a previous entry
- The operation has no notable outcome

## Quality Gates

Every learning entry must meet these criteria:

1. **Minimum length:** 20 words in the content field
2. **Structure:** Must include context (what happened), insight (why), and
   action (what to do)
3. **Specificity:** Reference concrete files, functions, or error messages — not
   vague generalizations
4. **Actionability:** The "action" must be something a future agent can follow

### Good Examples

**Context:**

> "Test `auth.test.ts:testTokenRefresh` failed because the mock JWT was expired.
> Fix: always set mock token expiry to `Date.now() + 3600000` instead of a
> hardcoded timestamp. Applied in commit abc123."

**Decision:**

> "Batch database inserts wrapped in a transaction are 10x faster than
> individual inserts for the users table. Use
> `db.transaction(async (tx) => { ... })` pattern when inserting more than 5
> rows."

### Bad Examples

> "Fixed a bug" — No context, no insight, no action. "Tests should pass" — Not
> specific, not actionable.

## Retrieval Strategy

Use Reciprocal Rank Fusion (RRF) to combine multiple ranking signals:

```
final_score = sum(1 / (rank_i + 60)) for each signal i
```

### Ranking Signals

1. **Semantic similarity** — Vector cosine distance to query
2. **Recency** — Time-decay: newer entries rank higher

(Retrieval frequency is not a usable signal: the recall result shape exposes
only `content`, `type`, `score`, and `created` — there is no retrieval-count
field to read.)

### Context Budget

- Load max 5 learnings per session start (via SessionStart hook)
- Prioritize by RRF score
- Each loaded learning should be a concise, actionable reminder

### Dedup Threshold

- Cosine similarity > 0.82 = likely duplicate (canonical constant from the
  `memory-query` skill's protocol constants)
- Warn user before storing near-duplicates
- Don't apply hard threshold on search results — always return top-k, filter
  below 0.5

## Skill Promotion

When a recurring `context` pattern appears 3+ times across sessions, consider
promoting it to a reusable `decision` entry:

1. Identify the recurring pattern from prior context entries
2. Formulate as a positive "do this" rule (not "don't do that")
3. Store as a `decision` entry with broader context
4. Optionally add to project CLAUDE.md if it's a project-wide convention