agent-memory

Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead — or when asking why the agent keeps re-learning the same correction, why a remembered rule is wrong, or where a memory line came from. Implements a four-tier store (L0 transcripts / L1 candidates / L2 project context / L3 stable persona) where promotion is earned by recurrence across sessions and days, never by one confident statement, and nothing reaches a committed file without a human adopting it.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A tight, executable body with strong safety discipline and concrete commands, weakened mainly by incomplete reference wiring — a broken DESIGN.md link and orphaned reference files that are not navigable from the overview.

Suggestions

Fix or correct the `../../DESIGN.md` link so it resolves to an existing file, or move the rationale into the `references/` docs and link those instead.

Surface the three `references/*.md` docs (tiered_memory_canon, promotion_gate_design, hook_capture_discipline) from the body with labeled pointers so the bundle is navigable one level deep.

Add a short numbered sequence for the human review-and-adopt step (inspect staged → review → `/cs:memory adopt`) to make the write-side workflow as explicit as the read-side commands.

Dimension	Reasoning	Score
Conciseness	Dense and assumes Claude's competence (no explanation of hooks, gitignore, or CLAUDE.md), but the narrative "The problem" framing and the reflective "Forcing questions" add tokens that aren't strictly instructional, keeping it just below fully lean.	4 / 5
Actionability	Copy-paste-ready commands referencing real scripts — `python3 scripts/memory_inspect.py --tier L1`, `--why "..."`, `--contested`, and `python3 scripts/memory_promote.py` — plus concrete env-var toggles, covering the common diagnostic and promotion cases.	5 / 5
Workflow Clarity	The promotion ladder (L0→L1→L2→L3) is clearly sequenced with explicit thresholds and real validation discipline (fail-open hooks, redact-before-write, propose-never-apply with backup, ambiguous=print nothing), but the human review-and-adopt step is not laid out as an explicit numbered sequence.	4 / 5
Progressive Disclosure	The body is a well-sectioned overview with one-level-deep, clearly labeled pointers to scripts, but `../../DESIGN.md` does not resolve at the cited path and the three provided `references/*.md` design docs are not surfaced from the overview, leaving a real navigation gap.	3 / 5
	Total	16 / 20 Passed

Description

95%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly states both capability and trigger conditions with natural language and good synonym coverage. The only soft spot is that it characterizes the system's mechanism rather than listing discrete user actions.

Dimension	Reasoning	Score
Specificity	Names concrete mechanisms — a "four-tier store (L0 transcripts / L1 candidates / L2 project context / L3 stable persona)" with "promotion earned by recurrence across sessions and days" and "human adopting" — but frames system behavior rather than enumerating discrete user-facing actions, so it sits just below comprehensive.	4 / 5
Completeness	Explicitly answers both — "Implements a four-tier store ... promotion is earned by recurrence ... nothing reaches a committed file without a human adopting it" (what) and "Use when ..." with concrete trigger phrases (when).	5 / 5
Trigger Term Quality	Natural user phrasings with synonym coverage: "CLAUDE.md has grown past what anyone reads", "keeps re-learning the same correction", "why a remembered rule is wrong", and "where a memory line came from" are exactly what someone would say when they need this skill.	5 / 5
Distinctiveness Conflict Risk	Clear niche (recurrence-gated tiered agent memory) with highly specific triggers and explicit distinct_from comparisons in metadata, giving minimal overlap risk with adjacent skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: alirezarezvani/claude-skills
Path: engineering/agent-memory/skills/agent-memory/SKILL.md
Commit: 19392f7

Reviewed: ~3 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.