Agent framework integration

Use createAgentSkillKit() to wire skills into Convex Agent, Mastra, or any framework that controls its own tool loop.

When you use a Crux adapter directly (@crux/anthropic, @crux/openai, @crux/google, @crux/ai), skills are fully automatic — Crux owns the tool loop, so the executor can intercept LoadSkill mid-call and re-resolve the system prompt without your code touching it.

External agent frameworks own that loop themselves. Convex Agent and Mastra, for instance, decide when to call the model, when to execute tools, and how the system prompt is assembled per turn. Crux cannot reach inside that loop. createAgentSkillKit() is the bridge: it gives you the same session-backed LoadSkill semantics, driven through a persistence port you provide.

The Problem the Kit Solves

Without the kit, integrating skills into a framework like Convex Agent means doing all of this yourself:

Pre-resolve the Crux prompt to extract LoadSkill / LoadReference tools
Convert those tools to the framework's tool format
Wrap LoadSkill with session snapshot persistence so loaded skills survive across turns
Read persisted skill IDs at the start of each turn
Pass them into the resolve input so the system prompt includes loaded skill content

createAgentSkillKit() handles steps 1, 2, 4, and 5. You provide step 3 — the persistence layer — as a SkillActivationPersistence port that stores the full SkillActivationSnapshot.

What the Kit Gives You

const kit = await createAgentSkillKit(prompt, {
  target: { threadId },
  persistence,
})

Property	What it does
`kit.tools`	Session-bound `LoadSkill` and `LoadReference`, ready to merge into your agent's tool set.
`kit.resolveInput(baseInput)`	Takes your per-turn dynamic input and returns it with `_crux_activeSkills` injected. Call this before `prompt.resolve()`.
`kit.getActiveIds()`	Returns the currently active skill IDs from your persistence layer. Useful for debugging and UI.

The preferred persistence port stores snapshots:

Method	Called when	What it should do
`load(target)`	Before pre-resolve and each `resolveInput()` call	Return a `SkillActivationSnapshot` or `null`
`save(target, snapshot)`	After `LoadSkill` succeeds	Persist `activeSkillIds` and `injectedSkillIds` for the target

Convex Agent

For Convex Agent, use @crux/convex/agent and pass skill tools through convexTools() so skill activation/deactivation remains observable in the Crux trace. See the Convex Agent, tools, and skills guide for the full setup.

Behavior Across Turns

Frameworks that compose the system prompt before running tools have one quirk worth understanding: when LoadSkill fires, the system prompt for that turn was already composed. So the skill content reaches the model two different ways depending on the turn:

Turn	Where the skill content lives
The turn `LoadSkill` is called on	Tool result — immediate and functional, but presented as supplementary information
Every subsequent turn	System prompt — authoritative and persistent, via `kit.resolveInput()`

In practice this is rarely a problem: the tool-result version is still rich enough to act on, and by the next turn the skill is in its proper authoritative position. If you need strictly-authoritative behavior on the loading turn itself, switch to a Crux adapter, which can re-resolve mid-loop.

Persistence Choices

The kit is intentionally agnostic about where activation snapshots live. A few patterns:

Storage	Good for
`cruxConvexStore` keyed by thread	Convex backends — co-locates skill state with the thread
A field on the thread document	Simplest if you already store thread metadata
Redis	Stateless function runtimes that need fast per-conversation lookups
In-memory map	Local development, tests, or single-process agents

Whatever you pick, load() and save() must agree on the storage — they are called from the same conversation but at different points in the request lifecycle.

Skills overview — how skills work in adapter-managed agents
API reference — full type signatures for createAgentSkillKit
Agents — the underlying Crux agent primitives