Skip to content

BuilderIO/agent-native / packages/core/docs

agent-native-docs

Unverified

How to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.

FileKindSize
AGENTS.mdmarkdown6.0 KB
SKILL.mdskill md2.2 KB
content/a2a-protocol.mdxmarkdown37.6 KB
content/actions-access-control.mdxmarkdown28.9 KB
content/actions-advanced.mdxmarkdown13.1 KB
content/actions-agent-tools.mdxmarkdown5.6 KB
content/actions-defining.mdxmarkdown31.2 KB
content/actions-other-surfaces.mdxmarkdown10.3 KB
content/actions-overview.mdxmarkdown8.3 KB
content/actions-run-context.mdxmarkdown9.1 KB
content/add-ui-to-your-agent.mdxmarkdown5.0 KB
content/administered-deployments.mdxmarkdown7.7 KB
content/agent-mentions.mdxmarkdown10.2 KB
content/agent-native-config.mdxmarkdown34.9 KB
content/agent-native-toolkit.mdxmarkdown17.3 KB
content/agent-resources.mdxmarkdown27.0 KB
content/agent-surfaces.mdxmarkdown33.8 KB
content/agent-teams.mdxmarkdown13.4 KB
content/agent-web-surfaces.mdxmarkdown10.7 KB
content/agentkit.mdxmarkdown14.0 KB
content/audit-log.mdxmarkdown14.3 KB
content/authentication.mdxmarkdown30.7 KB
content/automation-connectors.mdxmarkdown7.8 KB
content/automations.mdxmarkdown26.7 KB
content/aws-amplify.mdxmarkdown10.7 KB
content/aws-lambda.mdxmarkdown13.9 KB
content/aws-rds.mdxmarkdown1.7 KB
content/azure-postgresql.mdxmarkdown1.8 KB
content/azure-static-web-apps.mdxmarkdown9.1 KB
content/blueprint-installer.mdxmarkdown6.3 KB
content/cli-adapters.mdxmarkdown5.7 KB
content/client-advanced.mdxmarkdown13.1 KB
content/client-agent-chat.mdxmarkdown17.7 KB
content/client-data.mdxmarkdown19.3 KB
content/client-entry-points.mdxmarkdown1.2 KB
content/client-overview.mdxmarkdown10.6 KB
content/client-routing.mdxmarkdown5.7 KB
content/client-sync-internals.mdxmarkdown5.2 KB
content/cloneable-saas.mdxmarkdown16.6 KB
content/cloud-sql.mdxmarkdown2.3 KB
content/cloudflare.mdxmarkdown8.3 KB
content/code-agents-ui.mdxmarkdown26.6 KB
content/components.mdxmarkdown42.9 KB
content/context-awareness.mdxmarkdown24.9 KB
content/create-with-an-agent.mdxmarkdown8.8 KB
content/creating-templates.mdxmarkdown21.6 KB
content/cross-app-connect-design.mdxmarkdown8.4 KB
content/cross-app-sso.mdxmarkdown8.7 KB
content/custom-design-system.mdxmarkdown17.3 KB
content/data-programs.mdxmarkdown25.0 KB
content/decisions.mdxmarkdown7.9 KB
content/deno-deploy.mdxmarkdown7.2 KB
content/deploy-an-app.mdxmarkdown5.0 KB
content/deployment-environment-variables.mdxmarkdown16.3 KB
content/deployment.mdxmarkdown11.3 KB
content/dispatch.mdxmarkdown18.6 KB
content/docker.mdxmarkdown8.1 KB
content/docs-components.mdxmarkdown28.9 KB
content/doctor.mdxmarkdown21.3 KB
content/drafts/clips-experimental-features.mdmarkdown5.4 KB
content/drop-in-agent.mdxmarkdown16.0 KB
content/durable-background-runs.mdxmarkdown13.8 KB
content/durable-resume.mdxmarkdown10.0 KB
content/embedding-sdk.mdxmarkdown31.3 KB
content/environment-variables.mdxmarkdown29.9 KB
content/evals.mdxmarkdown12.4 KB
content/extensions.mdxmarkdown34.8 KB
content/external-agents-catalog.mdxmarkdown40.5 KB
content/external-agents.mdxmarkdown29.3 KB
content/file-uploads.mdxmarkdown10.7 KB
content/generative-ui.mdxmarkdown10.8 KB
content/getting-started-actions.mdxmarkdown2.7 KB
content/getting-started-pages.mdxmarkdown2.6 KB
content/getting-started.mdxmarkdown7.2 KB
content/harness-agents.mdxmarkdown16.9 KB
content/http-api.mdxmarkdown20.9 KB
content/integrations.mdxmarkdown33.8 KB
content/internationalization.mdxmarkdown6.2 KB
content/key-concepts.mdxmarkdown30.6 KB
content/koyeb.mdxmarkdown7.3 KB
content/locales/ar-SA/a2a-protocol.mdxmarkdown48.5 KB
content/locales/ar-SA/actions-access-control.mdxmarkdown40.8 KB
content/locales/ar-SA/actions-advanced.mdxmarkdown16.3 KB
content/locales/ar-SA/actions-agent-tools.mdxmarkdown8.1 KB
content/locales/ar-SA/actions-defining.mdxmarkdown42.2 KB
content/locales/ar-SA/actions-other-surfaces.mdxmarkdown14.5 KB
content/locales/ar-SA/actions-overview.mdxmarkdown11.3 KB
content/locales/ar-SA/actions-run-context.mdxmarkdown11.1 KB
content/locales/ar-SA/add-ui-to-your-agent.mdxmarkdown3.7 KB
content/locales/ar-SA/administered-deployments.mdxmarkdown6.4 KB
content/locales/ar-SA/agent-mentions.mdxmarkdown11.8 KB
content/locales/ar-SA/agent-native-toolkit.mdxmarkdown17.3 KB
content/locales/ar-SA/agent-resources.mdxmarkdown36.8 KB
content/locales/ar-SA/agent-surfaces.mdxmarkdown48.4 KB
content/locales/ar-SA/agent-teams.mdxmarkdown18.5 KB
content/locales/ar-SA/agent-web-surfaces.mdxmarkdown14.3 KB
content/locales/ar-SA/audit-log.mdxmarkdown15.9 KB
content/locales/ar-SA/authentication.mdxmarkdown39.8 KB
content/locales/ar-SA/automations.mdxmarkdown31.3 KB
content/locales/ar-SA/aws-amplify.mdxmarkdown14.9 KB
content/locales/ar-SA/aws-lambda.mdxmarkdown18.9 KB
content/locales/ar-SA/aws-rds.mdxmarkdown319 B
content/locales/ar-SA/azure-postgresql.mdxmarkdown344 B
content/locales/ar-SA/azure-static-web-apps.mdxmarkdown12.4 KB
content/locales/ar-SA/blueprint-installer.mdxmarkdown8.4 KB
content/locales/ar-SA/cli-adapters.mdxmarkdown6.7 KB
content/locales/ar-SA/client-advanced.mdxmarkdown17.8 KB
content/locales/ar-SA/client-agent-chat.mdxmarkdown23.0 KB
content/locales/ar-SA/client-data.mdxmarkdown23.8 KB
content/locales/ar-SA/client-entry-points.mdxmarkdown1.6 KB
content/locales/ar-SA/client-overview.mdxmarkdown13.9 KB
content/locales/ar-SA/client-routing.mdxmarkdown7.2 KB
content/locales/ar-SA/client-sync-internals.mdxmarkdown7.3 KB
content/locales/ar-SA/cloneable-saas.mdxmarkdown23.2 KB
content/locales/ar-SA/cloud-sql.mdxmarkdown317 B
content/locales/ar-SA/cloudflare.mdxmarkdown11.9 KB
content/locales/ar-SA/code-agents-ui.mdxmarkdown34.2 KB
content/locales/ar-SA/components.mdxmarkdown51.5 KB
content/locales/ar-SA/context-awareness.mdxmarkdown33.1 KB
content/locales/ar-SA/create-with-an-agent.mdxmarkdown12.2 KB
content/locales/ar-SA/creating-templates.mdxmarkdown26.8 KB
content/locales/ar-SA/cross-app-connect-design.mdxmarkdown1.5 KB
content/locales/ar-SA/cross-app-sso.mdxmarkdown9.7 KB
content/locales/ar-SA/custom-design-system.mdxmarkdown21.6 KB
content/locales/ar-SA/data-programs.mdxmarkdown33.3 KB
content/locales/ar-SA/decisions.mdxmarkdown9.1 KB
content/locales/ar-SA/deno-deploy.mdxmarkdown10.1 KB
content/locales/ar-SA/deploy-an-app.mdxmarkdown7.1 KB
content/locales/ar-SA/deployment-environment-variables.mdxmarkdown21.3 KB
content/locales/ar-SA/deployment.mdxmarkdown13.9 KB
content/locales/ar-SA/dispatch.mdxmarkdown27.3 KB
content/locales/ar-SA/docker.mdxmarkdown11.3 KB
content/locales/ar-SA/doctor.mdxmarkdown3.4 KB
content/locales/ar-SA/drop-in-agent.mdxmarkdown20.8 KB
content/locales/ar-SA/durable-resume.mdxmarkdown15.4 KB
content/locales/ar-SA/embedding-sdk.mdxmarkdown41.3 KB
content/locales/ar-SA/evals.mdxmarkdown13.3 KB
content/locales/ar-SA/extensions.mdxmarkdown34.0 KB
content/locales/ar-SA/external-agents.mdxmarkdown89.3 KB
content/locales/ar-SA/file-uploads.mdxmarkdown13.4 KB
content/locales/ar-SA/getting-started-actions.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started-pages.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started.mdxmarkdown9.7 KB
content/locales/ar-SA/harness-agents.mdxmarkdown22.3 KB
content/locales/ar-SA/internationalization.mdxmarkdown8.2 KB
content/locales/ar-SA/key-concepts.mdxmarkdown42.0 KB
content/locales/ar-SA/koyeb.mdxmarkdown10.2 KB
content/locales/ar-SA/mcp-apps.mdxmarkdown33.7 KB
content/locales/ar-SA/mcp-clients.mdxmarkdown35.0 KB
content/locales/ar-SA/mcp-protocol.mdxmarkdown27.6 KB
content/locales/ar-SA/messaging.mdxmarkdown59.2 KB
content/locales/ar-SA/multi-app-workspace.mdxmarkdown36.2 KB
content/locales/ar-SA/multi-tenancy.mdxmarkdown7.5 KB
content/locales/ar-SA/native-chat-ui.mdxmarkdown21.3 KB
content/locales/ar-SA/neon.mdxmarkdown244 B
content/locales/ar-SA/netlify.mdxmarkdown15.2 KB
content/locales/ar-SA/node-docker.mdxmarkdown878 B
content/locales/ar-SA/node-js.mdxmarkdown8.4 KB
content/locales/ar-SA/notifications.mdxmarkdown16.2 KB
content/locales/ar-SA/observability.mdxmarkdown45.2 KB
content/locales/ar-SA/observational-memory.mdxmarkdown10.9 KB
content/locales/ar-SA/onboarding.mdxmarkdown16.9 KB
content/locales/ar-SA/organizations-teams-permissions.mdxmarkdown5.9 KB
content/locales/ar-SA/package-lifecycle.mdxmarkdown3.0 KB
content/locales/ar-SA/plan-plugin.mdxmarkdown23.0 KB
content/locales/ar-SA/portal.mdxmarkdown636 B
content/locales/ar-SA/postgres.mdxmarkdown487 B
content/locales/ar-SA/pr-visual-recap.mdxmarkdown53.9 KB
content/locales/ar-SA/privacy-and-data-rights.mdxmarkdown6.2 KB
content/locales/ar-SA/processors.mdxmarkdown8.7 KB
content/locales/ar-SA/progress.mdxmarkdown10.7 KB
content/locales/ar-SA/pure-agent-apps.mdxmarkdown5.0 KB
content/locales/ar-SA/real-time-collaboration.mdxmarkdown55.6 KB
content/locales/ar-SA/recorder.mdxmarkdown16.7 KB
content/locales/ar-SA/recurring-jobs.mdxmarkdown23.8 KB
content/locales/ar-SA/render.mdxmarkdown11.2 KB
content/locales/ar-SA/sandbox-adapters.mdxmarkdown18.0 KB
content/locales/ar-SA/security.mdxmarkdown31.5 KB
content/locales/ar-SA/server-database.mdxmarkdown27.6 KB
content/locales/ar-SA/server-middleware.mdxmarkdown7.9 KB
content/locales/ar-SA/server-overview.mdxmarkdown12.2 KB
content/locales/ar-SA/server-plugins.mdxmarkdown9.1 KB
content/locales/ar-SA/server-routes.mdxmarkdown14.3 KB
content/locales/ar-SA/sharing.mdxmarkdown28.6 KB
content/locales/ar-SA/skills-guide.mdxmarkdown27.0 KB
content/locales/ar-SA/ssr-caching.mdxmarkdown7.4 KB
content/locales/ar-SA/supabase.mdxmarkdown264 B
content/locales/ar-SA/syncing-template-changes.mdxmarkdown11.7 KB
content/locales/ar-SA/telemetry.mdxmarkdown21.9 KB
content/locales/ar-SA/template-analytics.mdxmarkdown26.4 KB
content/locales/ar-SA/template-assets.mdxmarkdown31.9 KB
content/locales/ar-SA/template-brain.mdxmarkdown29.7 KB
content/locales/ar-SA/template-calendar-agent.mdxmarkdown10.2 KB
content/locales/ar-SA/template-calendar-developers.mdxmarkdown33.4 KB
content/locales/ar-SA/template-calendar-features.mdxmarkdown14.4 KB
content/locales/ar-SA/template-calendar-integrations.mdxmarkdown6.2 KB
content/locales/ar-SA/template-calendar.mdxmarkdown4.4 KB
content/locales/ar-SA/template-chat-agent.mdxmarkdown4.7 KB
content/locales/ar-SA/template-chat-developers.mdxmarkdown31.3 KB
content/locales/ar-SA/template-chat-features.mdxmarkdown9.9 KB

content/agent-resources.mdx

View on GitHub
---
title: "Agent Resources"
description: "Claude-Code-level customization per user — skills, memory, instructions, custom agents, scheduled jobs, MCP servers — backed by PostgreSQL/PGlite, not a filesystem."
---

# Agent Resources

<!-- i18n-copy-ignore: Agent-Native is a proper name; punctuation is locale-invariant. -->

Every agent-native app ships with **agent resources**: the customization layer that makes the agent yours. It contains team instructions (`AGENTS.md`), shared learnings (`LEARNINGS.md`), personal structured memory (`memory/MEMORY.md`), skills the agent pulls in on demand, custom sub-agents, scheduled jobs, and connected MCP servers — everything you'd expect from a Claude Code / Codex setup.

The twist: **it's PostgreSQL/PGlite rows, not filesystem files.** Each user gets their own set of agent resources stored in the database. There's no dev-box to spin up, no container per user, no files to mount. A multi-tenant SaaS can give every user a fully-customizable agent for essentially free, because all of it is rows — personal memory, personal MCP servers, personal skills, personal sub-agents — and the shared codebase hosts all of them at once.

<Diagram id="doc-block-13zbuxe" title="A Claude-Code setup, but stored as agent resources in PostgreSQL/PGlite" summary={"The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."}>

```html
<div class="ws-map">
  <div class="diagram-card cc">
    <span class="diagram-pill warn">Claude Code / Codex</span
    ><small class="diagram-muted">~/.claude/ on a local disk</small>
    <div class="ws-files">
      <span class="diagram-box">CLAUDE.md</span
      ><span class="diagram-box">skills/</span
      ><span class="diagram-box">memory</span
      ><span class="diagram-box">mcp.json</span>
    </div>
    <small class="diagram-muted">one codebase per developer</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-card an">
    <span class="diagram-pill accent">Agent-Native resources</span
    ><small class="diagram-muted">rows in one PostgreSQL/PGlite database</small>
    <div class="ws-rows">
      <span class="diagram-pill">AGENTS.md</span
      ><span class="diagram-pill">skills/&hellip;</span
      ><span class="diagram-pill">memory/&hellip;</span
      ><span class="diagram-pill">mcp-servers/&hellip;</span>
    </div>
    <small class="diagram-muted"
      >one codebase, many users, scoped
      <code>u:&lt;email&gt;:&hellip;</code></small
    >
  </div>
</div>
```

```css
.ws-map {
  display: flex;
  align-items: center;
  gap: 16px;
  flex-wrap: wrap;
}
.ws-map .diagram-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 16px 18px;
  flex: 1;
  min-width: 220px;
}
.ws-map .ws-files,
.ws-map .ws-rows {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin: 4px 0;
}
.ws-map .diagram-arrow {
  font-size: 24px;
}
```

</Diagram>

| Claude Code / Codex              | Agent-Native resources                             |
| -------------------------------- | -------------------------------------------------- |
| Files on your local disk         | Rows in a shared PostgreSQL/PGlite database        |
| One codebase per developer       | One codebase, many users                           |
| Needs a dev-box or container     | Runs on any serverless/edge host                   |
| Customization at `~/.claude/`    | Customization per-user, scoped `u:<email>:…`       |
| Per-project `CLAUDE.md` / skills | Per-app `AGENTS.md` + memory resources             |
| MCP config in a JSON file        | MCP config in JSON _or_ the settings UI, per scope |

Same capabilities. Different economics. See [Templates](/docs/cloneable-saas) for why this matters for SaaS.

## Overview {#overview}

Resources have three runtime scopes:

- **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
- **Shared / organization** — visible to all users in the app or organization. Good for app/team instructions, skills, and shared config.
- **Workspace** — inherited global defaults managed from Dispatch Resources. Good for company facts, positioning, brand guidelines, global guardrails, workspace-wide skills, and shared MCP servers. Apps read these at runtime; they are not copied into each app.

The in-app Resources tab shows all three scopes. Personal and shared/organization resources are editable there. Workspace-scope resources are read-only in app panels and edited centrally from Dispatch, so every app sees the same canonical files without a sync step.

The canonical paths that control how the agent uses each resource:

| Runtime resource        | Path                                    | How agents use it                               |
| ----------------------- | --------------------------------------- | ----------------------------------------------- |
| Guardrail instructions  | `AGENTS.md` or `instructions/<slug>.md` | Loaded every turn in every app that receives it |
| Global skills           | `skills/<slug>/SKILL.md`                | Listed as workspace skills and read on demand   |
| Brand/company resources | `context/<slug>.md`                     | Indexed every turn, read when relevant          |
| Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
| Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |

These paths apply across all three scopes — workspace, organization/app, and personal. The later scope wins when the same path exists at multiple levels.

## Take resources with you {#resource-pack}

Export a checksummed JSON pack of the text resources you can already read (`export-resource-pack`), and import it into another app or user (`import-resource-pack`). The Resources tab **Export pack** / **Import pack** controls call the same actions.

- Export includes only text. Binary uploads are omitted. API-key-shaped strings and MCP `env` / `headers` token fields are redacted; reconnect MCP after import.
- Import defaults to **personal** scope with skip-on-conflict. Organization import requires the same admin write ACL as editing organization files. Workspace import is not available.
- A pack that exceeds 200 text files or 1 MB fails with `too_large` instead of truncating. A checksum mismatch fails closed.

<Diagram id="doc-block-i69rby" title="Three scopes, one effective file" summary={"The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."}>

```html
<div class="ws-stack">
  <div class="diagram-card">
    <span class="diagram-pill">Workspace</span
    ><small class="diagram-muted">company-wide defaults from Dispatch</small
    ><code>context/brand.md</code>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
  <div class="diagram-card">
    <span class="diagram-pill">Organization / app</span
    ><small class="diagram-muted">team override for one app</small
    ><code>context/brand.md</code>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
  <div class="diagram-card">
    <span class="diagram-pill accent">Personal</span
    ><small class="diagram-muted">per-user override &mdash; wins</small
    ><code>context/brand.md</code>
  </div>
  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
  <div class="diagram-box ok">Effective <code>context/brand.md</code></div>
</div>
```

```css
.ws-stack {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 8px;
}
.ws-stack .diagram-card {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 12px 16px;
  min-width: 280px;
}
.ws-stack .diagram-arrow {
  font-size: 20px;
  align-self: center;
}
.ws-stack code {
  font-size: 0.85em;
}
.ws-stack .diagram-box {
  align-self: center;
  margin-top: 4px;
}
```

</Diagram>

## Getting Started: a 1-minute walkthrough {#getting-started}

Change how the agent behaves, in 60 seconds.

1. Open the **Resources** tab → **Shared** → `AGENTS.md` (create it with `+` → **File** if missing).
2. Add one rule, e.g.:

   ```markdown
   ## Tone

   Be concise. Lead with the answer.
   ```

3. Save, switch to **Chat**, ask anything — the agent follows the new rule immediately.

<Callout id="doc-block-8ly5wy" tone="info">

No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message.

</Callout>

**Next steps, when you want them:**

- **Skills** (`+` → **Skill**) — focused how-to files invoked in chat with `/skill-name`.
- **Agents** (`+` → **Agent**) — reusable sub-agent personas invoked with `@agent-name`.
- **Scheduled Tasks** (`+` → **Scheduled Task**) — prompts that run on a cron. See [Recurring Jobs](/docs/recurring-jobs) for schedules and triggers.
- **Memory** — shared `LEARNINGS.md` and personal `memory/MEMORY.md` keep durable context available across conversations.

## Global resources and canonical paths {#global-resources}

Workspace-scope resources are managed from Dispatch's **Resources** page and inherited by apps at runtime — no copy or sync step. Dispatch supports two grant scopes:

- **All apps** — global resources every app in the workspace inherits. Most company, brand, persona, positioning, messaging, and guardrail context should be **All apps**.
- **Selected apps** — resources granted to specific apps for app-specific context or tools. Use these sparingly.

The path determines how the agent uses a resource (see the table in [Overview](#overview) above). This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.

A useful starter pack for a new workspace:

```text
context/company.md              # what the company does, ICP, products, links
context/brand.md                # voice, visual identity, spelling, forbidden usage
context/messaging.md            # positioning, value props, proof points, objections
instructions/guardrails.md      # compliance, escalation, and approval rules
skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
agents/<slug>.md                # reusable custom agent profiles
```

Keep `context/` files factual and easy to skim. Put rules that must apply every turn in `instructions/guardrails.md`. Use `skills/company-voice/SKILL.md` when the agent should deliberately transform or review copy in the company's voice.

To override a global default for one app or team, create a shared/organization resource in that app with the same path. To override it for one person, create a personal resource with the same path. Do not copy the workspace file into every app; the runtime resolves the stack on read:

```text
workspace context/brand.md
-> shared/app context/brand.md
-> personal context/brand.md
```

For example:

```text filename="context/brand.md"
# Brand

- Voice: direct, warm, concrete
- Use: "workspace", "agent", "team"
- Avoid: unsupported superlatives and vague AI claims
```

## Resources Tab {#resources-tab}

The agent panel includes a **Resources** tab alongside Chat and CLI. It shows a folder-organized tree of all resources, an inline editor for any text file (Markdown, JSON, YAML, plain text), and the `+` menu's typed creation flows (Files, Skills, Agents, Scheduled Tasks). Users can browse inherited workspace defaults and create/edit/delete personal or organization resources.

When you open a resource, the editor shows an **Effective context** strip with the `workspace default -> organization/app override -> personal override` stack, so you can see what was inherited and why an override is active. Dispatch shows the same model from the control-plane side: on the **Resources** page use **Effective in app**, or expand **Stack** on a resource row in an app card's **Context** dialog.

When Dispatch approval policy is enabled, creating, updating, or deleting an **All apps** resource queues an approval request instead of applying immediately. The create/edit/delete dialogs show an impact preview before save.

Click the `?` icon in the Resources toolbar to jump back to these docs at any time.

## How the Agent Uses Resources {#how-the-agent-uses-resources}

The built-in app agent manages resources with the unified `resources` tool: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"`, or `"delete"`. External CLI/code agents can use the equivalent `pnpm action resource-*` commands.

### Agent scratch vs workspace visibility {#agent-scratch}

Every resource has a `visibility`: `workspace` (the normal, user-visible kind shown in the Resources tab) or `agent_scratch` (hidden working files the agent creates for itself — draft notes, intermediate results, a script it's iterating on). Agent writes default to `agent_scratch` unless the path is a durable instruction/skill/job/memory path, so the agent can work with temporary files without cluttering the Resources tab.

Scratch resources auto-expire — 24 hours after creation unless the agent sets its own `expiresAt` — so abandoned working files don't accumulate. Use `action: "promote"` (personal or shared scope only, not `workspace`/`all`) to turn a scratch file into a permanent workspace resource once the user actually wants to keep it, e.g. "save that as a real file." Promote keeps the same path and content and clears the expiry.

| Visibility      | Shown in Resources tab? | Expires?                            |
| --------------- | ----------------------- | ----------------------------------- |
| `workspace`     | Yes                     | No                                  |
| `agent_scratch` | No (hidden by default)  | Yes — 24h unless `expiresAt` is set |

At the start of every conversation, the agent automatically reads:

### AGENTS.md and instructions {#agents-md}

`AGENTS.md` is an instruction resource seeded by default and loaded every turn from workspace, shared/organization, and personal scopes in that order — workspace for company-wide defaults, shared/app for team rules, personal for per-user preferences. Files under `instructions/` are separate guardrail documents that also apply every turn (compliance rules, escalation policy, brand voice) and follow the same precedence. Both normal chat and integration-triggered runs load them before responding.

```text
AGENTS.md
instructions/customer-support-guardrails.md
instructions/legal-review-policy.md
```

### Reference resources {#reference-resources}

Reusable company context lives under `context/` (personas, positioning, product facts, brand guidelines, competitive notes). The agent sees an index of these and reads the relevant file with the `resources` tool (`action: "read"`) when a task may depend on it; use `action: "effective"` to see whether a workspace default is overridden for an app or user.

### Memory {#memory}

Agent resources have two current memory surfaces:

- `LEARNINGS.md` in **Shared** scope for project-wide conventions, corrections, and durable team knowledge.
- `memory/MEMORY.md` in **Personal** scope for structured memory about the current user.

The resource system also seeds a personal `LEARNINGS.md` for compatibility with older workspaces, but the chat preload path is shared `LEARNINGS.md` plus personal `memory/MEMORY.md`.

**What gets saved.** When you correct the agent ("always use X instead of Y"), share a preference ("I prefer concise answers"), or reveal context ("my team calls this 'the dispatch layer'"), the agent captures that learning so it doesn't repeat the mistake or re-ask. Project-wide learnings go in shared `LEARNINGS.md`; user-specific memory goes under `memory/`. The `capture-learnings` skill spells out when and how.

**Where it fits.**

| Surface            | Scope              | Written by                           | Read when                              |
| ------------------ | ------------------ | ------------------------------------ | -------------------------------------- |
| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                             |
| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn (shared copy only)          |
| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                             |
| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                             |
| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)           |
| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant |
| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app resources | MCP config refresh                     |

Users can edit these memory files directly in the Resources tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.

Every one of these surfaces — `AGENTS.md`, skills, memory, custom agents, MCP servers — is the same underlying resource shape: a `path` + `scope` + `content`, addressed and resolved the same way.

<DataModel
  id="doc-block-1rsm42e"
  title="The agent resource model"
  summary="One resource shape backs every agent resource file. The runtime keys it by path and scope and resolves the effective value on read."
  entities={[
    {
      id: "resource",
      name: "agent resource",
      note: "A single file in a user's agent resources — instructions, skill, memory, agent, MCP config, or job.",
      fields: [
        {
          name: "path",
          type: "string",
          note: "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md",
        },
        {
          name: "scope",
          type: "workspace | shared | personal",
          note: "Which level this row lives at",
        },
        {
          name: "owner",
          type: "string",
          nullable: true,
          note: "u:<email> for personal scope",
        },
        {
          name: "content",
          type: "text",
          note: "Markdown / JSON / YAML body",
        },
      ],
    },
  ]}
/>

## Skills {#skills}

Skills are Markdown resource files under the `skills/` path (preferably `skills/<name>/SKILL.md`) that give the agent on-demand domain knowledge, invoked in chat with `/skill-name`. Add them from the Resources tab or, in Code mode, from `.agents/skills/`.

See the [Skills Guide](/docs/skills-guide) — the single source for skill format, scope, discovery, and authoring.

## Custom Agents {#custom-agents}

Custom agents are reusable local sub-agent profiles stored as Markdown resources under `agents/*.md`. This is the canonical home for the custom-agent format.

Use them when you want a focused delegate with its own name, description, model preference, and instruction set. Unlike skills, custom agents are not passive guidance — they are operational personas the main agent can invoke through `@` mentions or by selecting them during sub-agent spawning.

### Agent format {#agent-format}

Custom agents use YAML frontmatter plus Markdown instructions:

<AnnotatedCode
  id="doc-block-yrvfel"
  title="A custom agent profile"
  filename="agents/design.md"
  language="markdown"
  code={
    "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated"
  }
  annotations={[
    {
      lines: "2",
      label: "@mention handle",
      note: "`name` is what appears in the `@`-dropdown and what the main agent delegates to.",
    },
    {
      lines: "3-4",
      label: "When to delegate",
      note: "The `description` is what the orchestrator reads to decide this profile fits a task.",
    },
    {
      lines: "5",
      label: "Model",
      note: "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one.",
    },
    {
      lines: "6",
      note: "`tools: inherit` for now — the field is reserved for future per-agent tool policies.",
    },
  ]}
/>

Recommended conventions:

- Store custom agents at `agents/<slug>.md`
- Use `model: inherit` unless the profile clearly needs a different model
- Keep `tools: inherit` for now; the field is reserved for future tool policies

### Remote agents vs custom agents {#remote-vs-custom-agents}

Agent resources include two agent types:

- **Custom agents** — local profiles in `agents/*.md`, executed inside the current app/runtime
- **Connected agents** — remote A2A peers described by manifests in `remote-agents/*.json` (legacy `agents/*.json` manifests are still recognized)

Use custom agents for delegation within one app. Use connected agents when you need to call another app over A2A.

## @ Tagging and / Slash Commands {#at-tagging}

Type `@` in the chat input to reference an agent, file, or resource, or `/` to invoke a skill — both open a dropdown at the cursor and add an inline chip when you select an item. See [Agent Mentions](/docs/agent-mentions) for the full mechanics (routing, `MentionProvider`, sub-agent selection) and [Skills Guide](/docs/skills-guide) for how skills are authored and discovered.

## Code vs App Mode {#dev-vs-prod}

The resource system works identically in both modes. What differs is the additional sources available for `@` tagging and `/` commands:

| Feature            | Code Mode                                                           | App Mode                                           |
| ------------------ | ------------------------------------------------------------------- | -------------------------------------------------- |
| @ tagging          | Codebase files + agent resources + custom agents + connected agents | Agent resources + custom agents + connected agents |
| / slash commands   | .agents/skills/ + resource skills                                   | Resource skills only                               |
| Agent file access  | Filesystem + resources                                              | Resources only                                     |
| Resources tab      | Full access                                                         | Full access                                        |
| AGENTS.md / memory | Available                                                           | Available                                          |

## Workspace Connections {#workspace-connections}

Workspace Connections let apps share the same provider account (Slack, GitHub, HubSpot, etc.) without duplicating credentials. A connection records provider identity, account labels, status, scopes, app grants, and credential references in PostgreSQL/PGlite. Secrets stay in the credential store; connections only point at credential key names such as `SLACK_BOT_TOKEN`.

See [Workspace Connections](/docs/workspace-connections) for the quickstart, connection/grant/credentialRef API, and concrete Slack, HubSpot, and GitHub examples.

## Resource API {#resource-api}

Resources can be managed from server code, actions, or the REST API.

### Server API {#server-api}

REST endpoints mounted automatically:

| Method   | Endpoint                                      | Description                          |
| -------- | --------------------------------------------- | ------------------------------------ |
| `GET`    | `/_agent-native/resources?scope=all`          | List resources                       |
| `GET`    | `/_agent-native/resources?scope=workspace`    | List inherited workspace resources   |
| `GET`    | `/_agent-native/resources/tree?scope=all`     | Get folder tree                      |
| `GET`    | `/_agent-native/resources/effective?path=...` | Show the effective inheritance stack |
| `POST`   | `/_agent-native/resources`                    | Create a resource                    |
| `GET`    | `/_agent-native/resources/:id`                | Get resource with content            |
| `PUT`    | `/_agent-native/resources/:id`                | Update a resource                    |
| `DELETE` | `/_agent-native/resources/:id`                | Delete a resource                    |
| `POST`   | `/_agent-native/resources/upload`             | Upload a file as resource            |

A resource read with `GET /_agent-native/resources/:id` comes with a `revision`. Send it back as `expectedRevision` with new `content` on `PUT`, and if someone saved other content after your read, nothing is written: the response is a 409 with `errorCode: "save_conflict"`, the content there now in `details.current.content`, and its revision in `details.currentRevision`. A `PUT` without `expectedRevision` still writes over whatever is there. A checked save can't also rename the resource: send the new `path` in its own `PUT` first. `<ResourceEditor saveContent>` does this for you: when someone else saved other content during an edit, it asks which version to keep and offers the other one back afterwards.

### Action API {#script-api}

The agent uses these built-in actions. You can also call them from your own actions:

```bash
# List all resources
pnpm action resource-list --scope all

# Read a resource
pnpm action resource-read --path "skills/my-skill/SKILL.md"

# Read inherited workspace context managed by Dispatch
pnpm action resource-read --scope workspace --path "context/brand.md"

# Show workspace -> organization/app -> personal precedence for a path
pnpm action resource-effective --path "context/brand.md"

# Write a resource
pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."

# Replace a resource only if nobody saved it since your read
pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..." --expected-revision "rev_…"

# Delete a resource
pnpm action resource-delete --path "notes/old.md"
```

The agent's resource reads start with a `[revision …, scope …]` line, and both of its write tools take that revision back as `expectedRevision` (`--expected-revision` on the command line). If someone saved the file after the read, nothing is written: the write fails with `errorCode: "save_conflict"` and the revision there now, so the agent reads the file again and redoes its edit. A write without a revision still replaces whatever is there.

## What's next {#whats-next}

- [**Skills Guide**](/docs/skills-guide) — author and scope the skill files referenced from `skills/`
- [**Agent Mentions**](/docs/agent-mentions) — `@`-mention and `/`-command mechanics in full
- [**Recurring Jobs**](/docs/recurring-jobs) — schedule the prompts created from Scheduled Tasks
- [**Workspace Governance**](/docs/workspace-management) — who reviews, approves, and owns workspace changes
- [**Multi-App Workspaces**](/docs/multi-app-workspace) — the deployment shape one workspace spans
- [**Workspace Connections**](/docs/workspace-connections) — share provider credentials across apps
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall