| name | agent-learning |
| description | 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. |
| user-invocable | false |
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:
- Minimum length: 20 words in the content field
- Structure: Must include context (what happened), insight (why), and
action (what to do)
- Specificity: Reference concrete files, functions, or error messages — not
vague generalizations
- 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
- Semantic similarity — Vector cosine distance to query
- 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:
- Identify the recurring pattern from prior context entries
- Formulate as a positive "do this" rule (not "don't do that")
- Store as a
decision entry with broader context
- Optionally add to project CLAUDE.md if it's a project-wide convention
