Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: document managed routing skills

Thiago Silvab578fb601f3a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a2e6823a..be9b9137 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Changed
+- `install-instructions` now refreshes a slim markered CLAUDE.md/AGENTS.md
+ snippet and installs or updates managed ai-memory Agent Skills by default,
+ with `--no-skills` for snippet-only refreshes and `--skills-*` flags for
+ scope, agent family, target root, and forced unmanaged replacement. Added
+ `install-skills` for refreshing those prompt-packaging skills directly, and
+ `memory_install_self_routing` now returns the slim block, managed skill
+ payloads, target hints, and overwrite guidance for agents that install
+ routing through MCP.
+
## [1.3.0] - 2026-06-24
### Added
diff --git a/README.md b/README.md
index 9ce52c88..e66eb31a 100644
--- a/README.md
+++ b/README.md
@@ -290,10 +290,11 @@ loopback server. With the local Docker quick start above, no
`AI_MEMORY_SERVER_URL` override is needed.
To remove ai-memory later, run `ai-memory uninstall --apply` from the
-same host environment. It removes ai-memory-owned config entries and
-generated plugin files only after matching their ai-memory signatures;
-use `--mcp-url` if you installed MCP with a custom endpoint, and
-`--mcp-name` only when you need to narrow removal to one matching entry.
+same host environment. It removes ai-memory-owned config entries, instruction
+blocks, managed skill files, and generated plugin files only after matching
+their ai-memory signatures; use `--mcp-url` if you installed MCP with a custom
+endpoint, and `--mcp-name` only when you need to narrow removal to one matching
+entry.
### Install Notes
@@ -315,10 +316,10 @@ use `--mcp-url` if you installed MCP with a custom endpoint, and
`ai-memory install-hooks --agent <agent> --apply` after upgrading the binary.
Remote/homelab servers must still be redeployed separately; local wrapper
upgrade only updates the client machine. Existing project prompt files keep
- working, but refresh the managed ai-memory routing block
+ working. Refresh the managed ai-memory routing package
(`ai-memory install-instructions`, or `--target AGENTS.md` for AGENTS-based
- projects) when you want new tool guidance such as proactive retrieval and
- `memory_auto_improve`.
+ projects) when you want new tool guidance. The refresh writes the slim
+ markered snippet and managed Agent Skills from the same binary-owned assets.
For Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI,
Grok Build CLI, OpenClaw, VS Code Copilot, curl-based hook installs, source builds,
@@ -473,16 +474,18 @@ Useful entry points:
`/wiki/web`. Set `--web-slug /` if you want the browser or custom SPA at
`/wiki` itself.
-Install the routing snippet once so agents proactively call the right
-MCP tool for those prompts:
+Install the managed routing package once so agents proactively call the
+right MCP tool for those prompts:
```bash
ai-memory install-instructions
```
-See [`docs/usage.md`](docs/usage.md) for handoff examples, proactive
-query routing, bootstrap details, web UI screenshots, and the raw-wiki
-inspection commands. CLI URL/auth configuration lives in
+That command writes or updates the slim `<!-- ai-memory:start -->` block and
+the managed ai-memory Agent Skills that carry the detailed routing guidance.
+See [`docs/usage.md`](docs/usage.md) for handoff examples, proactive query
+routing, bootstrap details, web UI screenshots, and the raw-wiki inspection
+commands. CLI URL/auth configuration lives in
[`docs/install.md`](docs/install.md#configuring-the-cli-url-and-auth).
## LLM Providers
@@ -577,7 +580,7 @@ diagram, crate breakdown, schema notes, and invariants.
| File | What it is |
|---|---|
| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. |
-| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, routing snippet, migration from other memory tools, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
+| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, migration from other memory tools, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
| [`docs/macos.md`](docs/macos.md) | macOS install paths: native release binary (recommended), source build, the Docker wrapper, hook-platform notes, and current macOS limitations. |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 08e8d59d..db511ed7 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -233,7 +233,7 @@ invariants below.
| `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. |
| `memory_forget_sweep` | destructive | M8 retention pass. `dry_run=true` for preview. |
| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. |
-| `memory_install_self_routing` | read-only | Return the canonical routing snippet for CLAUDE.md / AGENTS.md. |
+| `memory_install_self_routing` | read-only | Return the canonical slim routing snippet plus managed Agent Skill payloads and target hints for CLAUDE.md / AGENTS.md installs. |
`memory_briefing`, `memory_explore`, `memory_write_page`,
`memory_install_self_routing`, `memory_read_page`, `memory_delete_page`,
@@ -244,14 +244,21 @@ prose halves of "what's going on", `memory_write_page` covers explicit
durable annotations without abusing single-use handoffs,
`memory_install_self_routing` exists for the meta case where the agent
must re-write its own routing rules into a project's `CLAUDE.md` /
-`AGENTS.md`, `memory_read_page` complements `memory_query` for the
-"I need the full page, not a snippet" case (e.g. opening a decision page
-end-to-end), `memory_auto_improve` exposes a safe default-on learning review
-through the same approval/write path as pending writes, and `memory_delete_page` is the exact-path destructive pair
+`AGENTS.md` and install the companion managed Agent Skills into
+`.claude/skills` or `.agents/skills`, `memory_read_page` complements
+`memory_query` for the "I need the full page, not a snippet" case
+(e.g. opening a decision page end-to-end), `memory_auto_improve` exposes a
+safe default-on learning review through the same approval/write path as
+pending writes, and `memory_delete_page` is the exact-path destructive pair
needed by admission-aware mirrors. `memory_handoff_cancel` is the safety valve
for mistaken handoff creation. The narrow-surface discipline still holds —
every new tool has to earn its slot — but the v1 count is 16, not 10.
+The managed Agent Skills are a narrow prompt-packaging exception to the
+otherwise wiki-centered architecture. They are static `SKILL.md` files that
+teach agents when to call ai-memory MCP tools; they are not durable wiki pages,
+not auto-improvement output, and not a runtime skill router inside ai-memory.
+
MCP parameter aliases are intentionally sparse: `memory_query.query` accepts
`q|search`, and limit fields accept `n` / `top_k` where shipped. Project and
cwd parameters use their canonical names.
@@ -268,7 +275,7 @@ checkpoints restore-page llm-test
forget-sweep lint auto-improve
auto-improve-report curator pending-writes embed
generate-auth-token setup-agent bootstrap
-install-instructions reorg purge-project
+install-instructions install-skills reorg
rename-project move-project audit-contamination
uninstall auth user
```
diff --git a/docs/auto-improvement-loop.md b/docs/auto-improvement-loop.md
index 11415b88..87e1aaa8 100644
--- a/docs/auto-improvement-loop.md
+++ b/docs/auto-improvement-loop.md
@@ -31,7 +31,10 @@ The safe product shape is:
Do not copy Hermes' agent-local skill system directly. ai-memory's durable unit
is the project wiki page, not a `SKILL.md` package. The analogous targets are
`gotchas/`, `decisions/`, `concepts/`, `procedures/`, `_rules/`, small
-`_slots/` state pages, and pending review pages under `_pending/`.
+`_slots/` state pages, and pending review pages under `_pending/`. The managed
+ai-memory Agent Skills installed with routing are a narrow prompt-packaging
+exception: static files that teach agents when to call MCP tools, not durable
+memory pages or auto-improvement outputs.
## Hermes Findings
@@ -73,7 +76,7 @@ The default is off, preserving existing behavior. When enabled:
| Foreground memory, interactive CLI | Prompt inline when possible. |
| Foreground memory, no prompt channel | Stage to pending storage. |
| Background memory | Stage to pending storage. |
-| Skill writes | Always stage, because skill files can be large. |
+| Hermes skill writes | Always stage, because skill files can be large. |
| User denies inline memory write | Block, do not stage. |
| Prompt machinery fails | Stage rather than silently dropping the write. |
@@ -277,8 +280,9 @@ Default-available auto-improvement must not surprise existing installs:
preserve all existing wiki files and session/observation rows.
5. Existing installed `CLAUDE.md`/`AGENTS.md` blocks remain valid. Operators pick
up newer proactive retrieval guidance by running `ai-memory install-instructions`
- or asking an agent to refresh the ai-memory routing block. The marker-based
- replacement must remain idempotent.
+ or asking an agent to refresh the ai-memory routing package. The marker-based
+ replacement must remain idempotent, and the managed Agent Skill files should
+ refresh from the same binary-owned assets as the slim snippet.
6. Target-page mutations must pass through proposal staging first and must keep
approval attribution separate from the autonomous
`auto_improve` proposal actor.
@@ -388,11 +392,12 @@ proposal state, approval status, evidence metadata, and audit rows, but the
review artifact itself should be inspectable and versioned like the rest of the
wiki.
-Because this is now an MCP tool surface, the standard prompt snippets and
-regression tests assert `memory_auto_improve` appears in both prompt surfaces.
-Existing installed `CLAUDE.md`/`AGENTS.md` snippets update idempotently when the
-operator runs `ai-memory install-instructions` or asks an agent to refresh the
-ai-memory routing block.
+Because this is now an MCP tool surface, the standard prompt snippets, managed
+Agent Skills, and regression tests assert `memory_auto_improve` appears in the
+combined prompt-routing surface. Existing installed `CLAUDE.md`/`AGENTS.md`
+snippets update idempotently when the operator runs
+`ai-memory install-instructions` or asks an agent to refresh the ai-memory
+routing package.
### Upgrade note for existing installs
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 966b6e87..cecfaf00 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -192,12 +192,17 @@ basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a re
| `memory_delete_page` | Delete a single exact-path page with admission hooks | destructive |
| `memory_forget_sweep` | Retention sweep (M8); soft-delete below cold threshold; `dry_run=true` previews | destructive |
| `memory_lint` | Rule-based + optional LLM contradiction findings → `wiki/_lint/<date>.md` | destructive |
-| `memory_install_self_routing` | Returns the canonical CLAUDE.md / AGENTS.md routing block + per-agent filename hints | read-only |
+| `memory_install_self_routing` | Returns the canonical slim CLAUDE.md / AGENTS.md routing block, managed Agent Skill payloads, target hints, and overwrite guidance | read-only |
Tool param aliases stay narrow: shipped aliases cover `query|q|search` and
`limit|n|top_k`; project and cwd parameters use canonical names unless the
code adds a concrete alias.
+Managed ai-memory Agent Skills are prompt packaging for this tool-routing
+guidance only. They are installed as ordinary `SKILL.md` files so agents can
+progressively load detailed instructions, but ai-memory does not store durable
+memory in them and does not include a runtime skill router.
+
## 11. Identity & project scoping (3-tuple from day one)
Lesson from basic-memory's v0.20 trauma: `(workspace, project, page_path)`. Even if v1 ships single-workspace, the schema and every API/tool param encodes the full 3-tuple. No retrofits.
@@ -231,7 +236,7 @@ To stay scoped:
- No alternative embedded vector backends (sqlite-vec only).
- No alternative graph DB (SQL recursive CTEs only).
- No multimodal (text only).
-- No "skills" / slash-command bundle in v1 (agentmemory plugin format) - focus on hooks + MCP first.
+- No general "skills" / slash-command bundle in v1 (agentmemory plugin format). The narrow exception is the managed ai-memory Agent Skills that package routing guidance for agents; hooks + MCP remain the product surface.
- No LongMemEval-style benchmark harness in v1 - add in v0.4.
## 14. Mistakes-to-avoid checklist (from issue research)
diff --git a/docs/install.md b/docs/install.md
index bc0e482e..e3038f20 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -16,6 +16,7 @@ path (docker + Claude Code). This page covers everything else:
(cargo install, building from source)
- [LLM provider tiers + self-hosted Ollama](#llm-provider-tiers)
- [Subcommand reference](#subcommand-reference)
+- [Managed routing snippets and Agent Skills](#managed-routing-snippets-and-agent-skills)
- [Operating without auth](#operating-without-auth) (local-only)
- [Keeping ai-memory up to date](#keeping-ai-memory-up-to-date)
@@ -71,12 +72,14 @@ The CLI commands (`bootstrap`, `status`, `search`, `lint`, `auto-improve`,
`setup-agent`: with `AI_MEMORY_SERVER_URL` set, `install-mcp` derives the
`/mcp` endpoint and `install-hooks` uses the bare server origin.
-After upgrading ai-memory, refresh the managed routing block in existing
+After upgrading ai-memory, refresh the managed routing package in existing
projects so Claude Code/OpenCode/Codex/Gemini pick up new tool guidance and
proactive retrieval rules. From an agent, ask "refresh the ai-memory routing in
this project"; from the terminal, run `ai-memory install-instructions` (or pass
-`--target AGENTS.md` for non-Claude prompt files). The update is idempotent and
-only replaces the `<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` block.
+`--target AGENTS.md` for non-Claude prompt files). The update is idempotent:
+legacy long snippets between `<!-- ai-memory:start -->` /
+`<!-- ai-memory:end -->` are replaced in place with the slim snippet, and
+managed Agent Skills are installed or updated alongside it.
---
@@ -943,9 +946,70 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
| `install-mcp --client` | `docker run --rm` | MCP-config snippet per client |
| `install-hooks --agent` | `docker run --rm` | Hook-config snippet for an existing hooks dir |
| `setup-agent --agent --to --host-prefix` | `docker run --rm -v` | Extract bundled scripts + print config (one-shot) |
-| `uninstall --apply` | same host environment used for install | Remove only ai-memory-owned hooks, MCP entries, and instruction blocks; generated plugin files are deleted only after content validation. Use `--mcp-url` for custom MCP endpoints and `--mcp-name` only to narrow removal. |
+| `install-instructions [--target] [--print] [--no-skills]` | same host environment used for the agent prompt files | Install or update the slim CLAUDE.md / AGENTS.md routing block and, by default, the managed ai-memory Agent Skills |
+| `install-skills --scope --agent` | same host environment used for the agent skill dirs | Install or update only the managed ai-memory Agent Skills |
+| `uninstall --apply` | same host environment used for install | Remove only ai-memory-owned hooks, MCP entries, instruction blocks, managed skill files, and generated plugin files after content/marker validation. Use `--mcp-url` for custom MCP endpoints and `--mcp-name` only to narrow removal. |
| `llm-test --provider …` | `docker run --rm -e …` | Smoke-test an LLM provider |
+### Managed routing snippets and Agent Skills
+
+ai-memory's routing install is agent-facing prompt packaging. It does not add a
+runtime skill router, and `SKILL.md` files are not durable memory pages. The
+wiki remains the durable source of truth.
+
+`ai-memory install-instructions` now writes two managed prompt artifacts by
+default:
+
+1. A slim instruction block in `CLAUDE.md`, `AGENTS.md`, or the file passed with
+ `--target`. The block is bounded by `<!-- ai-memory:start -->` and
+ `<!-- ai-memory:end -->`.
+2. Managed ai-memory Agent Skills containing the detailed tool-routing guidance.
+
+Re-running the command is safe. If a project still has the old long ai-memory
+block between those markers, the refresh replaces that block in place with the
+slim snippet and leaves unrelated instructions before and after it alone.
+Managed skill files contain an ai-memory ownership marker; same-name user skills
+without that marker are preserved unless you explicitly force replacement.
+
+`install-instructions` flags for skills:
+
+| Flag | Meaning |
+|---|---|
+| `--no-skills` | Refresh only the markered instruction block. |
+| `--skills-scope <scope>` | Choose project-local or user-global skill roots. Values: `project`, `global`. Defaults to `project`. |
+| `--skills-agent <agent>` | Choose `.claude/skills`, `.agents/skills`, or both. Values: `claude-code`, `agents`, `both`. By default, `CLAUDE.md` targets imply `claude-code`, `AGENTS.md` targets imply `agents`, and both instruction files imply `both`. |
+| `--skills-target-dir <dir>` | Write managed skill directories below an explicit root instead of inferring from scope and agent. |
+| `--skills-force` | Replace unmanaged same-name skills during `install-instructions`; without it, they are left untouched and the command exits with an actionable error. |
+
+Use `install-skills` when the instruction block is already right and only the
+Agent Skill files need a refresh:
+
+```bash
+ai-memory install-skills
+ai-memory install-skills --scope global --agent agents
+ai-memory install-skills --agent both --print
+ai-memory install-skills --target-dir .custom/skills --force
+```
+
+`install-skills` flags:
+
+| Flag | Meaning |
+|---|---|
+| `--scope <scope>` | Install into this project or the current user's global skill roots. Values: `project`, `global`. Defaults to `project`. |
+| `--agent <agent>` | Install into Claude Code's skill root, the cross-agent skill root, or both. Values: `claude-code`, `agents`, `both`. Defaults to `claude-code`. |
+| `--target-dir <dir>` | Write managed skill directories below an explicit root; `--scope` and `--agent` are ignored. |
+| `--print` | Print target paths and `SKILL.md` contents without writing files. |
+| `--force` | Replace unmanaged same-name skills; without it, user-authored same-name skills are preserved. |
+
+Default skill target roots:
+
+| Scope | `--agent claude-code` | `--agent agents` |
+|---|---|---|
+| `project` | `.claude/skills` | `.agents/skills` |
+| `global` | `~/.claude/skills` | `~/.agents/skills` |
+
+Each managed skill is written as `<root>/<skill-name>/SKILL.md`.
+
Data dir inside the container is `/data` (mounted via the compose
volume). Outside docker, override with `AI_MEMORY_DATA_DIR=/path`.
@@ -1130,8 +1194,8 @@ write to `~/.local/share/ai-memory/hooks/`.
- [`docs/deploy.md`](deploy.md) - homelab deploy walkthrough
(`bin/deploy`, cloudflared TLS, env-file management)
-- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI,
- routing snippet, migration from other memory tools, and raw-wiki inspection
+- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI, slim
+ routing snippet + managed Agent Skills, migration from other memory tools, and raw-wiki inspection
- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config
reference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot
- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actually
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index dc4008bd..fa561ffd 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -42,6 +42,12 @@ endpoint. The trade-off:
For MCP-only use, you can still cover the session-boundary gap by asking
the LLM to call `memory_handoff_begin` manually before quitting.
+For proactive tool use in MCP-capable clients that read project instructions,
+also install the managed routing package from
+[`docs/usage.md`](usage.md#install-the-routing-snippet-and-agent-skills). The
+slim instruction block stays in the agent rules file, while supported Agent
+Skills carry the detailed ai-memory tool-routing guidance.
+
## Custom lifecycle bridges
Built-in integrations should use `ai-memory install-hooks` rather than
@@ -493,6 +499,14 @@ Model (any client): I can call: memory_query, memory_recent,
memory_status reports: 0 pages, 0 observations, 0 sessions.
```
+If the model sees the tools but does not call them proactively, refresh the
+managed routing package. The `memory_install_self_routing` tool is read-only:
+it returns the slim markered instruction block, marker strings, agent filename
+hints, managed skill payloads (`name`, `description`, `relative_path`,
+`content`), project/global target hints for `.claude/skills` and
+`.agents/skills`, and overwrite guidance. Agents should use their own file
+editing tools to write those artifacts while preserving unrelated user content.
+
If the model doesn't see any of those tools, the MCP registration
isn't being picked up. Check:
@@ -523,7 +537,7 @@ that *starts* the next one - to play nicely with ai-memory:
| Side | What's needed | Covered by |
|---|---|---|
| **Ending side** | The agent must create a handoff, either through a true session-end hook or by calling `memory_handoff_begin`. | Built-in for Claude Code, Cursor, Gemini CLI, Grok Build CLI, OpenClaw, and OMP. Codex, OpenCode, and Antigravity CLI have no true session-end event in the current integration, so ask them to call `memory_handoff_begin` before quitting when you need a handoff. |
-| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / Cursor / Gemini CLI / Antigravity CLI / OpenClaw / OpenCode / OMP. Grok is explicitly excluded because it ignores SessionStart stdout; use (b). (b) works for any MCP-capable client if you nudge the model - see [the routing snippet](usage.md#install-the-routing-snippet). |
+| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / Cursor / Gemini CLI / Antigravity CLI / OpenClaw / OpenCode / OMP. Grok is explicitly excluded because it ignores SessionStart stdout; use (b). (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |
So a typical mixed workflow looks like:
diff --git a/docs/usage.md b/docs/usage.md
index eba0f52d..5f32a6ad 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -2,7 +2,7 @@
This page covers what happens after ai-memory is installed: handoffs,
compaction recovery, proactive memory queries, the web UI, and the
-project-rule routing snippet.
+managed routing snippet + Agent Skills package.
## Cross-agent handoff
@@ -42,8 +42,8 @@ though its raw chat history was compacted away.
Hooks handle capture without prompting. Proactive querying depends on
the agent knowing which MCP tool to call for each situation. Install the
-routing snippet into the project rules file once, then agents can use
-the wiki without you naming tools explicitly.
+managed routing package once: a slim always-loaded snippet points agents
+at the managed ai-memory Agent Skills that carry detailed tool routing.
| You say | Agent calls | Effect |
|---|---|---|
@@ -66,7 +66,7 @@ full page before acting: rules are constraints, gotchas are preflight warnings,
procedures are checklists, and decisions are settled architecture unless the
user explicitly asks to revisit them.
-## Install the routing snippet
+## Install the routing snippet and Agent Skills
From an agent, say:
@@ -74,12 +74,14 @@ From an agent, say:
Install ai-memory routing into this project.
```
-The agent calls `memory_install_self_routing`, receives the canonical
-snippet, and writes it to the right rules file (`CLAUDE.md` for Claude
-Code, `AGENTS.md` for Codex / OpenCode / Cursor / Gemini CLI /
-Antigravity CLI). The
-block is wrapped in `<!-- ai-memory:start -->` and
-`<!-- ai-memory:end -->`, so re-runs replace it in place.
+The agent calls `memory_install_self_routing` and receives the slim
+`markered_block`, marker strings, rules-file hints, managed skill payloads,
+skill target hints, and overwrite guidance. It then uses its normal file-edit
+tool to preserve unrelated user content, replace or append the
+`<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` block, and write each
+managed skill below the selected skill root. Skill files are ai-memory-managed
+only when they contain the managed marker, so unmanaged same-name skills should
+not be overwritten unless the human explicitly forces replacement.
From a terminal:
@@ -87,11 +89,42 @@ From a terminal:
ai-memory install-instructions
ai-memory install-instructions --target AGENTS.md
ai-memory install-instructions --print
+ai-memory install-instructions --no-skills
```
+`install-instructions` installs or updates managed skills by default. Use
+`--no-skills` only when you intentionally want a snippet-only refresh. Skill
+flags mirror `install-skills` with an `--skills-` prefix:
+`--skills-scope project|global`, `--skills-agent claude-code|agents|both`,
+`--skills-target-dir <dir>`, and `--skills-force`.
+
Auto-detect extends `CLAUDE.md` when it exists, `AGENTS.md` when it
-exists, both when both exist, or creates `CLAUDE.md` when neither
-exists. Use `--target AGENTS.md` for non-Claude-only projects.
+exists, both when both exist, or creates `CLAUDE.md` when neither exists. Use
+`--target AGENTS.md` for non-Claude-only projects. The skill target follows the
+instruction target unless you override it: `CLAUDE.md` implies
+`.claude/skills`, `AGENTS.md` implies `.agents/skills`, and both files imply
+both skill roots.
+
+To refresh only the managed Agent Skills:
+
+```bash
+ai-memory install-skills
+ai-memory install-skills --scope global --agent agents
+ai-memory install-skills --agent both --print
+ai-memory install-skills --target-dir .custom/skills --force
+```
+
+Project-local skill roots are `.claude/skills` for Claude-compatible installs
+and `.agents/skills` for cross-client installs. Global roots are
+`~/.claude/skills` and `~/.agents/skills`. `--target-dir` points at an explicit
+skill root and bypasses scope/agent inference. `--print` previews target paths
+and `SKILL.md` contents. `--force` allows replacement of unmanaged same-name
+skills; without it, user-authored skills are preserved.
+
+This is prompt packaging only. ai-memory does not run a runtime skill router,
+does not store durable memory in `SKILL.md`, and does not turn the
+auto-improvement loop into a skill-authoring system. Durable knowledge still
+lives in the wiki.
## Bootstrap an existing project