Detailed, self-updating skills covering the whole system - #854
Merged
Conversation
Restructure the 8 action skills into the tiered format (SKILL.md under 100 lines, EXAMPLES.md, shared troubleshooting, anti-patterns, cross-refs) and add 7 reference skills covering MCP tools, REST API, config, connect adapters, hooks, architecture, and skill authoring. Reference data tables are generated from source by scripts/skills/generate.ts and guarded against drift by npm run skills:check in CI, so the docs stay current as the repo changes.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (13)
✅ Files skipped from review due to trivial changes (7)
🚧 Files skipped from review as they are similar to previous changes (6)
📝 WalkthroughWalkthroughThis PR expands the agentmemory skills documentation system from 8 to 15 skills by introducing automated documentation generation/validation scripts, establishing shared skill documentation patterns, and documenting system components (architecture, configuration, hooks, MCP tools, REST API) and user-invocable skills (remember, recall, recap, handoff, session-history, commit-context, commit-history, forget). ChangesSkills Documentation System Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (3)
plugin/skills/write-agentmemory-skill/SKILL.md (1)
11-16: 💤 Low valueAdd language specifier to the fenced code block.
The directory layout code block should specify a language (e.g.,
textor leave blank but markdownlint prefers an explicit specifier).📝 Suggested fix
-``` +```text plugin/skills/<name>/ SKILL.md (required, under 100 lines) REFERENCE.md (optional, dense facts; auto-generate data tables) EXAMPLES.md (optional, worked transcripts)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@plugin/skills/write-agentmemory-skill/SKILL.mdaround lines 11 - 16, The
fenced code block in SKILL.md lacks a language specifier; update the block
delimiter for the directory layout example in SKILL.md to include an explicit
language (e.g., changetotext) so markdownlint is satisfied and the
snippet is rendered as plain text.</details> <!-- cr-comment:v1:d534062446bc101538b133ed --> </blockquote></details> <details> <summary>scripts/skills/generate.ts (1)</summary><blockquote> `114-132`: _💤 Low value_ **Clarify the intent of filtering environment variables ending with `__`.** Line 122 excludes variables ending with `__` from the generated list. If this filters internal/transient vars by convention, add a comment. If it's unintentional, it may hide valid config vars. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/skills/generate.ts` around lines 114 - 132, The env() function filters out matched names that end with "__" via the condition m[0].endsWith("__") which is unclear; either document the convention or stop filtering: update the env() function to either (a) add a concise comment above the regex/while block explaining that variables suffixed with "__" are intentionally treated as internal/transient and should be excluded, referencing the regex /AGENTMEMORY_[A-Z0-9_]+/ and the m[0].endsWith("__") check, or (b) if that exclusion was accidental, remove the endsWith("__") guard so all AGENTMEMORY_* matches are included; ensure the chosen approach is reflected clearly in the code comment near env(), the regex, and the m[0].endsWith("__") usage. ``` </details> <!-- cr-comment:v1:7982906e1fdb57caa9aba3d7 --> </blockquote></details> <details> <summary>scripts/skills/check.ts (1)</summary><blockquote> `65-73`: _💤 Low value_ **Guard against undefined `description` in plugin.json validation.** Line 67 reads `description` and uses nullish coalescing `?? ""`, but if `description` is undefined (not just null), the regex on line 68 will still work on an empty string. However, the type assertion `as string` is misleading because the JSON parse result might not have a `description` field. <details> <summary>🛡️ Suggested clarification</summary> ```diff - const desc = (JSON.parse(readFileSync(pluginJson, "utf8")).description as string) ?? ""; + const pkg = JSON.parse(readFileSync(pluginJson, "utf8")) as { description?: string }; + const desc = pkg.description ?? ""; ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/skills/check.ts` around lines 65 - 73, The code reads and asserts description from plugin/plugin.json then runs a regex on it without verifying the field exists or is a string; change the JSON parsing logic to safely extract description (e.g., const parsed = JSON.parse(...); const desc = typeof parsed.description === "string" ? parsed.description : "";), remove the misleading "as string" assertion, and then run the /(\\d+)\\s+skills/ regex against desc (variables: pluginJson, desc, m, dirs, errors) so missing or non-string description fields are handled gracefully. ``` </details> <!-- cr-comment:v1:4230cd99e9d30eaeced81777 --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@plugin/skills/_shared/TROUBLESHOOTING.md:
- Around line 27-36: The table rows for the "recap" and "handoff" skills
currently list POST /agentmemory/recall but that route is not registered; open
src/triggers/api.ts, find the actual POST endpoint that handles recap/handoff
(look for the router.post or app.post registration for agent memory
recall/recap/hand off), and update the "recap" and "handoff" rows in
plugin/skills/_shared/TROUBLESHOOTING.md to exactly match the registered POST
path (replace the current /agentmemory/recall entries with the correct
registered endpoint).In
@plugin/skills/agentmemory-config/SKILL.md:
- Around line 13-17: The fenced code block that lists environment variables (the
block containing ANTHROPIC_API_KEY, AGENTMEMORY_AUTO_COMPRESS,
AGENTMEMORY_INJECT_CONTEXT) is missing a language tag; update the opening
triple-backtick to include a language such as env or bash (e.g., ```env) so
markdownlint MD040 is satisfied and the block is properly highlighted.In
@plugin/skills/agentmemory-hooks/SKILL.md:
- Around line 13-16: Add a language identifier to the fenced code block that
contains the two plugin commands in SKILL.md (the block starting with "/plugin
marketplace add rohitg00/agentmemory" and "/plugin install agentmemory") by
changing the opening fence fromto something likebash so the block is
recognized as shell script and satisfies markdownlint MD040.In
@plugin/skills/commit-context/SKILL.md:
- Around line 22-25: The fenced expected-output block containing the
commit/session sample (the block that currently begins withand includes the lines '9a1b2c3 on main by dev: "rotate refresh tokens"' and 'Linked session 7f3a9c2 "Auth refresh rework", 14 obs.') needs a language label to satisfy markdownlint MD040; update that fenced block delimiter fromto ```text so
the block is explicitly labeled (i.e., change the opening backticks for the
example in SKILL.md to include "text").In
@plugin/skills/commit-history/EXAMPLES.md:
- Around line 66-68: The fenced code block containing the GET request "GET
/agentmemory/commits?branch=release-2.0&limit=100" is missing a language tag;
update the opening fence fromto a language-specific tag such ashttp (or
text) so the block becomeshttp to satisfy markdownlint MD040 and keep
EXAMPLES.md lint-clean.In
@plugin/skills/commit-history/SKILL.md:
- Around line 19-20: The sample session IDs in SKILL.md's commit examples (e.g.,
the "session 7f3a9c2" and "session b21d004" tokens) are only 7 characters but
must follow the "first 8" chars rule mentioned later; update those session IDs
to 8-character prefixes (e.g., change 7f3a9c2 → 7f3a9c2X and b21d004 → b21d004X
or replace with the correct first-8 hex chars) so all examples in the commit
lines match the documented "first 8" requirement (also apply the same fix to the
other example referenced around lines 35-36).- Around line 18-21: The fenced code block that contains the commit lines (the
triple backticks before the lines starting with "9a1b2c3" and "b21d004") is
unlabeled; update the opening fence fromtotext so the block becomes a
labeled code fence (keep the closing ``` unchanged) to satisfy markdownlint
MD040.In
@plugin/skills/forget/EXAMPLES.md:
- Line 27: Update the example lines so session IDs are consistent across the
document: replace the truncated session IDs shown in the example string
"abc12345(session7f3a9c2) "Pasted staging API key"" with the full ID used earlier (e.g.,7f3a9c21), and likewise makec98f110/c98f1100consistent everywhere; ensure the example output strings and any other examples use the exact same full session ID values throughout (search for7f3a9c2,7f3a9c21,c98f110,c98f1100` to locate and update).In
@plugin/skills/forget/SKILL.md:
- Around line 24-26: The fenced code block in SKILL.md containing "Found 2
matching memories. Confirmed. Deleted 2 memories." lacks a language identifier;
update that fenced block to include a language tag (e.g., "text") after the
openingso the block becomestext ... ``` to satisfy markdownlint MD040
and ensure proper rendering.In
@plugin/skills/remember/SKILL.md:
- Around line 22-24: The fenced output block containing the line "Saved memory
abc12345 with 3 concepts: jwt-refresh-rotation, token-revocation, auth-flow." is
missing a language tag; update the opening fence fromtotext so the
block is explicitly marked as plain text (e.g., change the fenced block that
wraps that sentence to start with ```text).In
@plugin/skills/session-history/SKILL.md:
- Around line 18-21: The example commit IDs in SKILL.md (e.g., the shown short
hashes "7f3a9c2" and "b21d004" and the other examples referenced alongside the
“first 8” rule) are only 7 characters long; update those example IDs to be 8
characters each to match the documented “first 8” convention (ensure every
sample ID in the file uses the first 8 chars of a commit hash so the examples
and the rule are consistent).- Around line 17-22: The fenced code block in SKILL.md is unlabeled and triggers
markdownlint MD040; update the block opening fence to include a language
specifier (e.g., changetotext) so the snippet is explicitly marked as
plain text; ensure the closing fence remains ``` and do not alter the block
contents.
Nitpick comments:
In@plugin/skills/write-agentmemory-skill/SKILL.md:
- Around line 11-16: The fenced code block in SKILL.md lacks a language
specifier; update the block delimiter for the directory layout example in
SKILL.md to include an explicit language (e.g., changetotext) so
markdownlint is satisfied and the snippet is rendered as plain text.In
@scripts/skills/check.ts:
- Around line 65-73: The code reads and asserts description from
plugin/plugin.json then runs a regex on it without verifying the field exists or
is a string; change the JSON parsing logic to safely extract description (e.g.,
const parsed = JSON.parse(...); const desc = typeof parsed.description ===
"string" ? parsed.description : "";), remove the misleading "as string"
assertion, and then run the /(\d+)\s+skills/ regex against desc (variables:
pluginJson, desc, m, dirs, errors) so missing or non-string description fields
are handled gracefully.In
@scripts/skills/generate.ts:
- Around line 114-132: The env() function filters out matched names that end
with "" via the condition m[0].endsWith("") which is unclear; either
document the convention or stop filtering: update the env() function to either
(a) add a concise comment above the regex/while block explaining that variables
suffixed with "" are intentionally treated as internal/transient and should be
excluded, referencing the regex /AGENTMEMORY_[A-Z0-9_]+/ and the
m[0].endsWith("") check, or (b) if that exclusion was accidental, remove the
endsWith("") guard so all AGENTMEMORY_* matches are included; ensure the
chosen approach is reflected clearly in the code comment near env(), the regex,
and the m[0].endsWith("") usage.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `b8099475-cf40-44ea-b375-7809a9dd486a` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 25158519d5d68b9060a97ba5bdcccc3e1aba6d79 and 616f341f1f8e0ca6417d69cb830c4b04eee86434. </details> <details> <summary>📒 Files selected for processing (36)</summary> * `.github/workflows/ci.yml` * `README.md` * `package.json` * `plugin/plugin.json` * `plugin/skills/_shared/TROUBLESHOOTING.md` * `plugin/skills/agentmemory-agents/REFERENCE.md` * `plugin/skills/agentmemory-agents/SKILL.md` * `plugin/skills/agentmemory-architecture/SKILL.md` * `plugin/skills/agentmemory-config/REFERENCE.md` * `plugin/skills/agentmemory-config/SKILL.md` * `plugin/skills/agentmemory-hooks/REFERENCE.md` * `plugin/skills/agentmemory-hooks/SKILL.md` * `plugin/skills/agentmemory-mcp-tools/REFERENCE.md` * `plugin/skills/agentmemory-mcp-tools/SKILL.md` * `plugin/skills/agentmemory-rest-api/REFERENCE.md` * `plugin/skills/agentmemory-rest-api/SKILL.md` * `plugin/skills/commit-context/EXAMPLES.md` * `plugin/skills/commit-context/SKILL.md` * `plugin/skills/commit-history/EXAMPLES.md` * `plugin/skills/commit-history/SKILL.md` * `plugin/skills/forget/EXAMPLES.md` * `plugin/skills/forget/SKILL.md` * `plugin/skills/handoff/EXAMPLES.md` * `plugin/skills/handoff/SKILL.md` * `plugin/skills/recall/EXAMPLES.md` * `plugin/skills/recall/SKILL.md` * `plugin/skills/recap/EXAMPLES.md` * `plugin/skills/recap/SKILL.md` * `plugin/skills/remember/EXAMPLES.md` * `plugin/skills/remember/SKILL.md` * `plugin/skills/session-history/EXAMPLES.md` * `plugin/skills/session-history/SKILL.md` * `plugin/skills/write-agentmemory-skill/SKILL.md` * `scripts/skills/check.ts` * `scripts/skills/generate.ts` * `src/mcp/tools-registry.ts` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| Present and gate: | ||
|
|
||
| > Found 1 match: | ||
| > - `abc12345` (session `7f3a9c2`) "Pasted staging API key" |
Contributor
There was a problem hiding this comment.
Fix inconsistent session IDs in example output text.
The displayed session IDs are truncated compared to earlier values (7f3a9c21 vs 7f3a9c2, and c98f1100 vs c98f110). Keep these consistent so users can reliably follow and verify the workflow examples.
Also applies to: 75-75
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugin/skills/forget/EXAMPLES.md` at line 27, Update the example lines so
session IDs are consistent across the document: replace the truncated session
IDs shown in the example string "`abc12345` (session `7f3a9c2`) \"Pasted staging
API key\"`" with the full ID used earlier (e.g., `7f3a9c21`), and likewise make
`c98f110`/`c98f1100` consistent everywhere; ensure the example output strings
and any other examples use the exact same full session ID values throughout
(search for `7f3a9c2`, `7f3a9c21`, `c98f110`, `c98f1100` to locate and update).
Comment on lines
+18
to
+21
| 7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs | ||
| - decision: Rotate refresh tokens on every use | ||
| b21d004 · app · 2026-06-05 14:00 · completed · 9 obs | ||
| - code: limit.ts counts per-IP |
Contributor
There was a problem hiding this comment.
Align example ID length with the documented “first 8” rule.
Lines 32-33 require first 8 chars, but Lines 18 and 20 show 7-char IDs. Keep one convention to avoid operator confusion.
Suggested fix
-7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs
+7f3a9c21 · app · 2026-06-07 09:00 · completed · 14 obs
...
-b21d004 · app · 2026-06-05 14:00 · completed · 9 obs
+b21d004e · app · 2026-06-05 14:00 · completed · 9 obsAlso applies to: 32-33
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugin/skills/session-history/SKILL.md` around lines 18 - 21, The example
commit IDs in SKILL.md (e.g., the shown short hashes "7f3a9c2" and "b21d004" and
the other examples referenced alongside the “first 8” rule) are only 7
characters long; update those example IDs to be 8 characters each to match the
documented “first 8” convention (ensure every sample ID in the file uses the
first 8 chars of a commit hash so the examples and the rule are consistent).
Correct the recap/handoff REST fallback in _shared/TROUBLESHOOTING.md to POST /agentmemory/smart-search (/agentmemory/recall is not a registered route), and add language identifiers to all opening code fences across the skill docs to satisfy markdownlint MD040.
healdigital
pushed a commit
to healdigital/agentmemory
that referenced
this pull request
Jul 27, 2026
* feat(skills): detailed tiered skills covering the whole system Restructure the 8 action skills into the tiered format (SKILL.md under 100 lines, EXAMPLES.md, shared troubleshooting, anti-patterns, cross-refs) and add 7 reference skills covering MCP tools, REST API, config, connect adapters, hooks, architecture, and skill authoring. Reference data tables are generated from source by scripts/skills/generate.ts and guarded against drift by npm run skills:check in CI, so the docs stay current as the repo changes. * docs(skills): fix recall REST mapping and label code fences Correct the recap/handoff REST fallback in _shared/TROUBLESHOOTING.md to POST /agentmemory/smart-search (/agentmemory/recall is not a registered route), and add language identifiers to all opening code fences across the skill docs to satisfy markdownlint MD040.
This was referenced Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Turns the agentmemory skills from thin stubs into a detailed, tiered knowledge base that covers every part of the system and stays current as the repo changes.
Action skills (8, rewritten)
Each is now tiered: SKILL.md (under 100 lines) with Quick start, Why, Workflow with decision gates, a WRONG/RIGHT anti-pattern callout, a checklist, and cross-links, plus an EXAMPLES.md of worked transcripts. The duplicated MCP-recovery block is extracted once to plugin/skills/_shared/TROUBLESHOOTING.md and referenced.
Reference skills (7, new)
Stays current automatically
scripts/skills/generate.ts derives the tool table (53), REST endpoints (117), env vars (34), connect adapters (17), and hook events (12) directly from source into AUTOGEN blocks. scripts/skills/check.ts lints every skill (frontmatter, Use-when trigger, under-100-line cap, no inlined troubleshooting, plugin.json count match) and re-runs the generator in --check mode to fail on drift. Both wired into CI via npm run skills:check.
Counts
15 skills total: 8 invocable, 7 reference. README and plugin.json updated.
Validation
Summary by CodeRabbit
New Features
Documentation
Chores