Content surfaces are content-only (markdown / TOML files): no runtime dispatch, no telemetry wrapping, no home-bin pointer — pure file writers. Each supporting adapter writes the native file(s); unsupporting adapters skip + warn. memory is the fourth content surface with the same contract, except it edits a shared, user-authored memory/rules file (AGENTS.md / CLAUDE.md / GEMINI.md) via marker-fenced managed blocks instead of writing files agent-connector wholly owns — see MemoryDef below.

SurfaceToolPolicy is shared: { allow?: string[]; deny?: string[] } — rendered to each host's allowed-tools / tools[] / readonly.

Plus two runtime-dispatched handler surfaces beyond the content writers — a singular statusline and actions, each set up below.

Status line#

A singular statusline — a HUD render(ctx) handler with top-level/per-host options; claude-code and antigravity-cli (top-level statusLine) and qwen-code (nested ui.statusLine in settings.json) today, other hosts skip-warn.

Actions#

actions — user-invokable run(ctx) handlers dispatched by agent-connector action with label/icon/placement/confirm metadata; v1 ships the dispatch backbone, and host affordance emitters now ship for droid, hermes, kiro, omp, openclaw, pi, warp, and zed (plus the nemoclaw fork, which inherits openclaw's emitter); hosts with no verifiable emission target skip-warn.

CommandDef#

A slash command.

SkillDef#

An Agent Skill (folder + SKILL.md, Agent Skills open standard).

SubagentDef#

A named subagent (system-prompt + tool/model scoping).

commands: [
  {
    name: "deploy",
    description: "Deploy the current service to an environment.",
    argumentHint: "[environment]",
    prompt: "Deploy {{args}} using the project's release runbook.",
    tools: { allow: ["Bash", "Read"] },
  },
],
skills: [
  {
    name: "db-triage",
    description:
      "Triage a failing query. Use when a SQL error or slow query is reported.",
    body: "# DB triage\nInspect the plan, check indexes, suggest a fix.",
    resources: { "references/indexes.md": "..." },
  },
],
subagents: [
  {
    name: "schema-reviewer",
    description: "Reviews migrations for backwards-compatibility.",
    prompt: "You are a careful schema reviewer...",
    readonly: true,
  },
],

MemoryDef#

Standing guidance declared once and upserted by every supporting adapter as a managed block into the memory/rules file that host actually reads. Unlike the three surfaces above, the target file is shared and user-authored — agent-connector never touches bytes outside its own marker pair.

memory: [
  {
    // name defaults to "memory" → blockId "acme-db/memory"
    description: "Standing guidance for agents working with acme-db.",
    content:
      "Use the acme-db MCP tools for schema questions; never hand-edit migrations.",
  },
],
platforms: {
  // optional per-host tuning — both fields are escape hatches:
  "claude-code": { memory: { mode: "agents-import" } }, // opt-in @AGENTS.md bridge
  codex: { memory: { path: "docs/AGENTS.md" } },        // org convention override
},

Managed blocks: markers, hashes, reversibility#

Every memory write goes through one dependency-free engine (core/managed-block.ts). The block is fenced by HTML-comment markers carrying the blockId (<connectorId>/<name> — unique per connector, so multiple connectors coexist in one file) and a content hash (first 12 hex of sha256 over the normalized inner content):

<!-- agent-connector:begin acme-db/memory hash=3f9c2a81d04e -->
<!-- Managed by agent-connector for "acme-db". Do not edit between these markers: run your connector package's upgrade/sync command to rewrite this block; run its uninstall command to remove it (framework fallback: `agent-connector uninstall acme-db`). -->
Use the acme-db MCP tools for schema questions; never hand-edit migrations.
<!-- agent-connector:end acme-db/memory -->

• Idempotent: unchanged content → an O(1) skip (no mtime/git churn); replacement is in place — zero bytes outside the marker pair ever change, no move-to-top, no blank-line reflow. New blocks append at EOF with exactly one blank separator line; a missing file is created and recorded as agent-connector-created.
• Edit detection: if the actual inner hash differs from the recorded hash=, the user edited inside the block — sync warns and leaves the edit intact; only install --force overwrites, after a timestamped backup.
• Robust scanning: line-anchored, CRLF-preserving, BOM-safe, and fence-aware (marker text quoted inside code fences never matches); lone stray markers are recovered safely and duplicate pairs collapse on upsert.
• Fully reversible: memory installs last among the content surfaces and is removed first on uninstall — a prefix scan over the connector's marker namespace (plus the persisted ownership ledger) excises every block, reclaims the blank separator line, and deletes the file only when agent-connector created it and nothing else remains. doctor verifies each installed block: file present / block present / hash intact / user-edited.

AGENTS.md-first: where the block goes#

AGENTS.md adopters read the open AGENTS.md standard file (the Linux Foundation-stewarded "README for agents" format) — so you write the guidance once and it lands in the standard file across adopter hosts. agent-connector never flips host settings to make AGENTS.md readable (probe-and-respect only), and the non-reader hosts are wired per their own official docs — CLAUDE.md and GEMINI.md, plus the dedicated rules-dir hosts (.amazonq/rules, .continue/rules, .windsurf/rules):

Validation rules#

• Each name must be kebab-case ^[a-z0-9][a-z0-9-]*$; no duplicate name within a single surface array.
• Required non-empty strings: command prompt; skill description + body; subagent description + prompt.
• Skill description length must be <= 1024 (throws otherwise).
• Skill resources keys must be SAFE relative paths inside the skill dir — empty, ., absolute, or any ..-traversal key is rejected.
• Memory content must be non-empty; hard ConnectorConfigError above 16 KiB (it is injected into every prompt of every targeted host) or when it contains the literal marker tokens agent-connector:begin / agent-connector:end. A soft 4 KiB budget is an install-time warn, not a config error.

Per-platform surface support#

Adapters that don't support a surface skip with a warning. <n> is the surface name; skills are uniformly folder-per-skill SKILL.md (only the parent dir differs per platform). Memory targets are listed separately under AGENTS.md-first above.