Skills, memory, and extensions¶
This is a usage guide. To implement an extension, continue to Building a Plugin or Building an Agent. To connect an existing product, use Agent Integrations.
An instruction, a tool, a remembered fact, and an agent are different kinds of capability. Choose the smallest extension that provides what the task lacks.
Capability map¶
| Component | Provides | Does not imply |
|---|---|---|
| Skill | A discoverable procedure, possibly with scripts and reference files | A new runtime tool or unrestricted execution |
| SkillForge | Retrieval from local skills, memory-backed experience, and Skill Hub | Autonomous source-code changes |
| Memory Engine / EverOS | Persistence and recall across sessions | Every past message stays in the model context |
| MCP server | Tools, resources, or prompts exposed by an external service | An independent agent session |
| Plugin | Runtime contributions such as tools, hooks, services, or memory backends | Isolation from the host process |
| Specialized agent | Its own identity, configuration, tools, and session behaviour | Automatic access to all host tools or credentials |
| Playbook | A named reusable procedure or graph | A skill indexed by SkillForge |
| Evolver | Separate benchmark-driven evaluation of harness changes | A production agent rewriting itself during a session |
See Architecture for assembly boundaries and DAG orchestration for coordinating specialized agents.
Discover and manage skills¶
Start by inspecting what the current installation offers:
raven skill list
raven skill get --help
raven skill block --help
SkillForge uses four sources: local files, skills/cases recalled through the configured memory backend, remote Skill Hub candidates, and project skills kept in the working directory's repository. Availability depends on configuration and service connectivity; a catalog result is not proof that a bundle is installed or its required tools exist.
Searching Skill Hub sends text off the machine. The source is on by default and
uses the shared catalog (https://skillhub.evermind.ai); a config may name
another URL at skillForge.router.hub.endpoint, and RAVEN_SKILLHUB_URL
overrides it for both this retrieval and the SkillHub page (a value Raven
refuses turns conversational retrieval off for that process rather than
falling back). While the source is on, Raven sends text from the session (the
message, or a query the model writes from it) to that address whenever it looks
for a skill. Turn it off with the Skill Hub switch on the settings dialog's
Skills page, or set skillForge.router.hub.enabled to false; the URL is
kept, so turning it back on returns to the same catalog. A legacy explicit
null endpoint keeps the source off. Switching applies to the next search
either way, with no reload.
Retrieved skills reach the model as a small name/description menu on eligible
turns; the model uses find_skill to search and read_skill to fetch a body.
Only skills marked always sit in the system prompt. Choosing skills costs a
turn no extra model calls, though a lookup can still reach the Skill Hub, and
not every turn receives a menu.
Skill directories¶
A skill goes in one of two directories, depending on whether it is for the user or for one project:
- Agent home's
skills/— the user-level directory,skills/under the agent home:~/.raven/workspace/skillsby default, moved byRAVEN_HOMEand by the--homeoption ofraven agent,raven gatewayandraven tui. - The project's
.agents/skills— read from the turn's working directory up to its git root, each directory on the way contributing one; when both hold the same skill name, the nearest directory is the one offered. With no git root above the working directory, only that directory is read. The flat<name>/SKILL.mdlayout is the one recognized, and a symlink counts only when its resolved target stays inside the git root. Neither the user's home nor agent home, nor agent home's ancestors, is ever a project directory.
Project skills appear in the same name/description menu and through
find_skill as project/<name>, and read_skill / use_skill resolve those
ids per turn against the turn's own working directory, so two sessions in two
checkouts never see each other's project skills. A project skill is never
injected into the system prompt, whatever its frontmatter says. Only the leader
agent reads them; a sub-agent does not. The source is on by default and can be
switched off with skillForge.projectSkills.enabled; either direction applies
to the next search, with no restart.
An installer that writes the same layout can put a skill in the project:
gh skill install <owner>/<repo> skills/<name>/SKILL.md --dir .agents/skills
Bundle downloads have a separate consent setting:
{
"skillForge": {
"autoInstall": "prompt"
}
}
autoInstall defaults to auto; prompt requests interactive terminal
consent and behaves like off without a TTY. off skips the bundle download,
but does not block reading a vetted skill body. Use the blocklist when the
skill itself should be unavailable. Review scripts before execution; a catalog
safety score is not a security guarantee, and missing scores are not a hard
rejection in the current policy. Successful installs are audited under
<workspace>/skills/hub/installs.jsonl.
In the web UI, the settings dialog's Skills page switches skills, and Skill Hub search, on and off; its Add button leads into the chat with the request half written, because a skill is installed by asking Raven, under the consent setting above.
Memory and learning boundaries¶
EverOS is the default memory-backend plugin, distributed separately from the
Raven core. It recalls user context and agent experience through the Memory
Engine. Use raven plugins to inspect the active backend, and configure memory
through onboarding and the deployment's plugin settings.
Keep three mechanisms separate:
- Context assembly decides what the current model call sees; long histories may be archived or compacted.
- Memory storage and recall retain selected knowledge beyond a session.
- Experience extraction is provided by the selected memory backend. Configure
it through that backend's plugin settings. The host does not use
skillForge.extractionto start a local extraction pipeline.
SkillForge retrieves and offers skills and manages downloaded bundles. Feedback-driven skill versioning and retirement are not implemented by the host. Inspect the memory backend's stored cases, skills, and health to check what experience it has retained. The separate Evolver tool evaluates harness changes against benchmarks; start with Evolver: usage and experiments, then use Design and implementation for implementation details.
From a completed task to reusable knowledge¶
First decide what needs to survive:
| Information | Appropriate home | How to check it |
|---|---|---|
| User preference or personal context | Memory backend's user track | Inspect stored memory and test recall in a new session |
| Agent experience or reusable case | Memory backend's agent track, when supported | Inspect the case/skill actually returned by that backend |
| Reviewed instructions | A local Skill | Read its body and verify required tools |
| Repeatable multi-step execution | Playbook | Validate and test the stored graph |
| Source documents and passages | Knowledge base | Verify indexing and retrieved source text |
| Evidence of a failed run | Trajectory bundle | Replay it and retain the relevant artifacts |
EverOS exposes user and agent recall separately: user memories supply personal
context; agent cases/skills can supply SkillForge candidates. Keep the intended
userId and agentId stable across the sessions you want to connect.
A different agent identity or memory backend is not automatically the same
memory collection.
Try a non-sensitive preference such as “I prefer a short checklist before instructions.” Complete the turn, inspect the memory view/backend if available, then open a new session under the same identity and ask a related question. Verify the recorded memory and retrieved context, not only the model's claim that it remembers. Repeating the preference in the test prompt would not demonstrate recall.
For reusable work, complete and verify a small task first, then inspect whether the backend recorded a useful case or skill. If it did not, explicitly author and review a local Skill or create a Playbook. Do not treat every successful answer as an automatically installed procedure.
Host memory writes are queued off-turn, with bounded queues and retries. An answer finishing does not mean backend indexing finished; outages, queue limits, and shutdown can leave data unindexed or in an uncertain in-flight state. Memory persistence is not a backup of the entire transcript.
Context pressure is not long-term learning¶
Curator selects history for the next context window. Its fast path avoids a model call below pressure thresholds; its slow path can spend bounded model calls producing a plan, with deterministic fallback when no valid plan arrives. Archived messages can be retained verbatim on disk and retrieved later, but are not necessarily present in every prompt.
In-turn Compaction is different: it can prune older tool-result bodies and summarize the transcript head while retaining recent messages. It defaults to off and does not write long-term memory notes. To opt in:
{
"agents": {
"defaults": {
"compaction": {
"enabled": true
}
}
}
}
Merge rather than replace the rest of your agent configuration. Compaction can use the turn's model and incur charges; it does not enlarge the provider's actual context limit. Curator and compaction are not substitutes for an explicit task brief or a source file that the agent can re-read.
Diagnose missing recall or skills¶
| Symptom | Check |
|---|---|
| New session lacks a preference | Memory backend health, indexing completion, identity, and recall relevance |
| A skill is listed but unused | Whether its body was fetched, required tools, blocklist, and selected agent |
| No skill appeared after a task | Actual backend extraction support; skillForge.extraction alone does not activate a host pipeline |
| Long task lost a detail | Archived versus in-window history, compaction, and a retrievable source |
| Unexpected model cost | Backend extraction, embedding, and the Curator slow path |
Memory views may expose private sessions and inferred preferences. Backend-specific deletion and retention controls must be checked separately; deleting a host session or blocking a skill is not proof that all backend records were deleted.
Extend tools or build an agent¶
Use MCP when a capability already exists behind a service interface. Configure
the server, verify its tool list and authentication, and then test a read-only
operation before permitting mutations. raven plugin auth <server> handles
configured MCP OAuth; it is not an installer for arbitrary plugins.
In the web UI, the settings dialog's MCP page switches, retries and
authorizes configured servers; its Add button leads into the chat, where
Raven connects a server from the PlugHub catalogue, and a server the catalogue
does not list is written into tools.mcpServers in config.json by hand.
The Plugins page beside it lists Agent Plugin
packages, which bring skills and MCP servers of
their own.
Use a Raven plugin for in-process tools, hooks, services, or memory backends.
Its declarative raven-plugin.toml names contributions; code runs in the host
trust domain. raven plugins lists installed contributions. A plugin Tool Gate
and the platform Permission Gate are distinct contracts.
Use raven agents new <name> to scaffold a specialized agent when it needs a
separate identity and execution profile. Read raven agents new --help first;
the resulting folder includes its own README. In a source checkout,
agents/BUILDING.md documents the launcher, configuration, plugin factories,
and discovery. Keep runtime state outside the definition folder and distinguish
the agent's state root, ACP home, and the user's working directory.
Operate the complete workflow¶
| Task | Starting point | Verify before relying on it |
|---|---|---|
| Reuse expertise | raven skill list |
Body, required tools, download consent |
| Retain knowledge | raven plugins and memory configuration |
Backend health and intended user/agent identity |
| Connect a tool service | MCP configuration and raven plugin auth --help |
Credential scope and actual available tools |
| Coordinate agents | A DAG or playbook | Roster readiness, references, shared limits |
| Run scheduled work | raven cron --help |
Schedule, recipient, permissions, resident host |
| Enable proactive work | Proactive Reminders and Follow-ups | Opt-in configuration, interruption policy, cost |
| Connect messaging | raven channels --help |
Sender allowlist, credentials, delivery |
| Diagnose a run | raven doctor, tracing, trajectory tools |
Redacted evidence, not just a successful handshake |
For recurring or unattended work, review Permissions and security and Self-Hosting first. Model context, memory, downloaded skills, child processes, and network peers each introduce their own trust and cost boundaries.