Ecosystem & Interop

Part of the PersonalClaw research-learnings library. Source-agnostic; distilled 2026-07-13 from a 95-source competitive-research corpus.

Principles (the durable truths)

Distribution is the product. An ~80-line behavioral-guidelines document, packaged simultaneously in three harness formats (a per-project agent-instructions file, an installable plugin with a skill manifest, and an editor rules file), reached ~190k GitHub stars. The content was trivial; the multi-format packaging and one-command installability were the value. Ecosystem reach is a packaging problem before it is a content problem.

One canonical source, N generated projections — never forked copies. Every mature interop story in the corpus keeps a single authoritative artifact (a typed doc file, a canonical SKILL.md, a canonical agent prompt) and generates every other surface from it: CLI docs, website, MCP responses, per-tool rule files, plugin wrappers, hosted-API deployments. Where copies must physically exist (skills vendored into agent bundles), the discipline is copy-with-sync-script plus a CI drift check — never trust convention. Deployment-mode differences are expressed as an appended delta to the canonical source, never a fork.

Self-description beats documentation. Agents should never scrape --help or prose docs. The winning shape is a capability manifest generated from the real command/route/node registry (so it cannot drift), with a CI test that fails when a capability is added undescribed, plus typed response envelopes and append-only stable error codes agents can branch on. “An OpenAPI spec for a CLI” is the mental model; multiple independent systems converge on it.

Credentials never travel. Every pack/bundle/distribution format in the corpus structurally excludes secrets: auth files and .env stay on the installing machine, installers write an .env.EXAMPLE and declare env_requires instead, team templates state “connections are the only credential store,” and org install links carry zero tokens (“possession of the ZIP grants no workspace access”). This is a format-level invariant, not a policy suggestion.

Interop dialects are boundary adapters, never architecture. OpenAI-compat inbound APIs, MCP (client, server, and reverse-server), ACP for hosting external agents, and A2A for peer agents all appear as thin adapters at the edge of a system whose internal model is its own. The strategic doctrine that survives: A2A is “an in-workflow handoff mechanism, not an enterprise-wide networking layer” — adopt protocols where a concrete handoff needs them, resist protocol-first architecture.

Ecosystems are catalogs-as-data with CI guards. Rosters, tool-support matrices, and scenario bundles live as JSON catalogs (slug-keyed, where slug = filename stem, “rename-proof and testable”), consumed identically by CLI installers and browse/install apps, with CI checks that fail when catalog and on-disk content disagree. Doctrine documents are deliberately kept out of the installable catalog (strategy ≠ units).

Community catalogs need a trust ladder, not just a scanner. The converged supply-chain shape: mandatory install-time scanning (exfiltration, prompt injection, destructive commands, supply-chain), a trust tier per source (builtin → official → trusted → community), a provenance lockfile (URL + content hash + scanner verdict + scanner version), quarantine for flagged items, and an override flag that can bypass caution but never a dangerous verdict. Registries add human review: releases hidden until review passes, third-party scan results surfaced on listing pages. See security-and-guardrails for the install-gate mechanics.

Minimal external tool surfaces outperform tool sprawl. Two independent large systems expose their entire ecosystem to external agents through exactly TWO tools (search + get / search_capabilities + execute_capability), with per-result token budgets and follow-up hints. Everything else becomes a discovered capability behind those two, namespaced by provider.

Machine-readable exports make everything composable. A public CSV/JSON export of an index (even with empty pre-allocated feedback columns), llms.txt/llms-full.txt doc indexes, and digest exports turn a product into an ecosystem node other tools can build on — near-zero cost, disproportionate leverage.

Mechanisms (implementation-ready designs)

M1. Agent-as-distribution (profile pack)

A whole agent persona ships as any clonable git repo (or local dir) with a distribution.yaml manifest at root: name, version, description, requires (host version constraints), author, license, env_requires (per-var: name / description / required / default), optional distribution_owned path list. Install previews the manifest, lists required env vars, warns about bundled cron jobs, writes .env.EXAMPLE. Update re-clones and overwrites ONLY distribution-owned paths (identity file, skills/, cron/, MCP wiring); user data (memories, sessions, auth, .env) is never touched; local config preserved unless --force-config. Publishing is just a git push; private repos work via the user’s normal git credentials. Hard boundary: credentials are never part of a distribution. Multiple independent systems converge on this pack shape — team templates (skills + MCP config + commands + agents + provider settings, “templates should stay boring — a single known-good starting point”), domain packs (skills + workflow templates + slash commands + connector configs + agent presets), and roster packs (below) are the same genre at different scopes.

M2. Multi-harness export contract (tools catalog)

A per-tool JSON contract renders one canonical corpus into 16+ agent-tool formats. Per tool entry: format (renderer contract — same format name guarantees byte-identical output, so two tools may share a format only if their rendered files are identical), installKind (per-agent = one file/dir per agent | roster = one combined conventions file | plugin = built artifact), detect.dirs (sniff which tools are installed), dest path templates with {slug}, slugFrom: source|name, user-vs-project scope, a version-probe command, plus presentation metadata for a browse app. CI enforces catalog↔renderer-script agreement. The lightweight version: one canonical SKILL.md hand-generates CLAUDE.md / .cursor/rules/*.mdc / plugin-dir variants, with a contributor rule requiring sync — but generated projections beat manual sync (a token-diet skill auto-generates all per-tool rule files from one source specifically “to prevent drift”).

M3. Self-describing platform manifest + typed envelopes

manifest --json emits apiVersion, global options (flag/type/choices/default), and per-command entries: arguments (required/variadic), options, a JSON-support flag, responseTypes, examples, nested subcommands — generated from the real command-registry metadata so it cannot drift; the two facts the registry lacks live in explicit allowlist maps; a CI test fails when a command is added without being described. Every command returns a typed envelope: success {"type": "<domain>.<variant>", "data": {...}}; errors {error, code, suggestions?} where code is stable and machine-branchable (“branch on it, never on the human-readable string”), the code set is append-only (~37 codes; meanings never change, codes never removed), and suggestions carries did-you-mean candidates {name, reason}. Three surfaces — terminal output, --json, programmatic import — are thin wrappers over the same functions, guaranteeing identical data. Consumer utilities (parseResponse, isError, assertResponse that throws + narrows types) ship for subprocess callers. Companion agent-CLI conventions from a second system: stable JSON envelopes to stdout / progress to stderr, --plain line mode, typed exit codes (0 ok, 1 runtime, 2 usage, 3 auth-unavailable, 4 transport-unavailable, 5 partial — distinct so schedulers retry instead of alerting), and a process-wide DISABLE_LIVE_WRITES kill switch auto-set in CI.

M4. Two-tool retrieval surface with budgets and breadcrumbs

Expose an entire docs/capability corpus over MCP as exactly search(query, limit=8) + get(name, section?). Internals worth copying: an inverted keyword index built from per-entity keywords[] metadata (NL queries resolve without a hardcoded alias map — improving docs automatically improves search); layered scoring (exact=100, prefix=90, substring=85, all-words=75, ≥half-words=50, keyword-index boost=90) with sub-component demotion (parent outranks its child on ties); context budget control (~1.5K tokens per brief result, 4000-char cap per topic, brief results carry ≤6 key props); every result embeds a hint naming the exact next call, and empty results return example query shapes; get supports section sub-addressing to avoid context overload. The capability-rail variant namespaces everything (plugin:<id>:<objectId>, mcp:<connection>:<tool>) behind the same two tools, returns instructional payloads with provenance framing for skill/context capabilities, renders $ARGUMENTS server-side for commands (nothing executes), and reports honest degraded statuses (needs_connection, needs_install, content_not_synced); DB-only scored search (title +5 exact/+3 prefix, description +2, searchText +1).

M5. Skills federation: multi-source hub + provenance lockfile

Install sources: an official registry, GitHub “taps” (any repo containing skills/<slug>/SKILL.md is a source), the /.well-known/skills/index.json convention (any website can publish skills), other marketplaces, and direct URLs. All installs pass a mandatory security scan; trust ladder builtin → official → trusted → community; provenance recorded in a lockfile (lock.json: URL, content hash, scanner version, findings) plus a quarantine dir and audit log. Bundled-content sync uses a hash manifest of origin hashes: user-edited bundled entries are “skipped forever” on update; an explicit reset re-baselines, --restore reverts to pristine. The minimal know-how lockfile: skills-lock.json pinning {source, sourceType, skillPath, computedHash(sha256)} per imported skill — enabling upstream-drift-vs-local-evolution detection. The two-file manifest that makes any git repo an installable source: marketplace.json (registry wrapper: id, owner, plugins[] with category) + plugin.json (name/version/skills[] relative paths).

M6. Inbound OpenAI-compat API with agent-as-model mapping

Serve /v1/chat/completions|models|embeddings|responses where the model field targets an agent (<namespace>/<agentId>), not a provider model; the OpenAI user string derives a stable session key for cross-call continuity; SSE streaming; explicitly documented as an owner-level credential surface. Two independent systems implement this exact mapping. The capture-proxy variant inverts it: a local OpenAI/Anthropic-compatible proxy that other agents on the machine are pointed at — it injects the local skill catalog into system prompts, records full session artifacts (turns, tool calls/results/errors, which skills were injected vs actually read/modified via a file-path→skill map), and feeds a learning pipeline. Critical discipline from that design: prompt-time injection alone is NOT evidence of use — only actual reads/writes count (see self-improvement-loops).

M7. Reverse MCP / agent-as-server, and the hardened read-only variant

Expose the assistant itself as a stdio MCP server (e.g. 10 messaging tools: conversations_list, messages_send, events_poll, …) so external agents and IDEs can drive it. For remote/read surfaces, the hardened profile: exactly two query-only tools; no writes, no live fetches, no migrations reachable (“an agent request cannot trigger a migration” — store prep happens only via the trusted CLI); fail-closed startup requiring a ≥32-byte bearer token distinct per surface plus an explicit public URL treated as a security boundary (exact Host/Origin match; forwarded-host headers untrusted); loopback TCP peer required; optional scope pinning that tool arguments cannot override; hard limits (64 KiB bodies, 30 s deadline, 20-burst/1-per-sec/4-concurrent per token, 100 results max, 2 MiB result cap, broad scans over >10k rows rejected); Cache-Control: no-store; all returned user content framed as untrusted (“must not be treated as instructions, credentials, authorization, or authority”).

M8. External-agent hosting (ACP) and A2A peering

Host third-party coding agents (Claude Code, Codex, …) as long-lived child processes inside platform-owned workspaces via ACP: a session pool binds runtimes to chat sessions; idle reaping (30 min for session-bound, 5 min unbound); per-agent budget caps unbound runtimes (max 4); a local HTTP tools-proxy (loopback) bridges the platform’s MCP tools into the hosted agent so it gains capabilities without direct system access. A2A support means both directions — expose self as an A2A-compatible agent AND call other A2A agents as workflow steps — via an off-the-shelf protocol library, with per-project protocol-server configs. Strategy note: treat A2A as in-workflow handoff plumbing; “federated discovery only where needed / last.”

M9. Marker-fenced managed context injection into host harnesses

A tool that wants to teach other agents about itself writes a managed block into the host project’s agent file (CLAUDE.md / AGENTS.md / .cursorrules, selected by --agent claude|cursor|codex or arbitrary path): content fenced by <!-- X:START --> / <!-- X:END --> markers, replaced in place on regeneration (with legacy-marker migration), refreshed by the upgrade command, and checked for presence by a doctor diagnostic. The injected content teaches a workflow, not just facts — an ordered discovery procedure (list templates → fetch skeleton → read component docs) plus explicit anti-patterns — and ships 2-3 probe prompts (“if the agent can’t answer these, the context isn’t loaded”); the publisher measured a 0% probe pass rate without the docs installed, making the probes a cheap litmus that the machine-readable layer is actually present.

M10. Ship-the-docs-with-the-tool agent skill (measured)

Bundle a SKILL.md inside the distribution (resolved at runtime via doctor get install-dir), pointing at an offline nav-indexed wiki and an exact-signature API reference (“to cut down on errors from hallucinated values”), mandating a strict-mode verify/compile loop and explicit negative scope (“do NOT use for X”; never start the long-running server). Published eval (5 tasks, ≤3 retries): with-skill 4/5 first-try compiles, 6 total attempts, 0 silent spec misses, 92% quality vs without-skill 0/5, 14 attempts, 3 silent misses, 63% — at +58% tokens and roughly flat wall time. This is the acceptance-bar methodology for any “external agents can drive my platform” surface.

M11. One source, two deployment wrappers + vendored-copy drift control

Each named agent ships as both a local plugin and a hosted managed-API deployment from ONE canonical prompt file (agents/<slug>.md with frontmatter); the hosted wrapper references it via system: {file, append: "<headless delta>"} — mode differences as appended text, never a fork. Skills authored once under a vertical source-of-truth dir are copied into agent bundles by a name-keyed rmtree+copytree sync script; a pre-commit/CI checker flags drift via directory compare (diff_files or left_only or right_only) and additionally lints prose→bundle consistency (regex-extract backtick-quoted hyphenated identifiers from agent prose; error if an agent references a skill it doesn’t bundle). Deploy pipeline: env-var substitution refusing values outside a safe charset; each skill dir zipped and uploaded, memoized by name; sub-agent manifests resolved recursively leaves-first; provenance stamped into metadata; --dry-run prints the fully resolved payload array. A once-per-branch pre-commit hook patch-bumps each touched plugin’s version, because version gates update delivery to already-installed users.

M12. Roster-as-CI-guarded-data (catalog trio)

Three JSON catalogs make a 230+ persona corpus installable and appable: (1) a divisions catalog ({label, icon, color} per division; CI fails if it disagrees with directories on disk or the converter scripts’ dir arrays); (2) the tools catalog (M2); (3) a runbooks catalog — each scenario = {slug, title, mode, duration, summary, doc, roster[]} where roster groups carry an activation field ("always" / "week 3+" / "as needed") so a team deploy is staged, not all-at-once; agents referenced by slug = filename stem; CI verifies every slug resolves to a real file. A desktop app consumes the same catalogs for browse + one-click team install. Anti-duplicate gate at contribution time: entity-neutralized 8-word shingle overlap (proper nouns regex-neutralized first so a find-replace “re-skin” still scores as near-duplicate); warn ≥20%, fail ≥40%, calibrated against the corpus (worst legitimate pair ~1.5%, median 0%).

M13. Extension manifest as the single user-facing abstraction

One “extension” concept wraps skills/MCP servers/plugins/providers/binaries/hooks: manifest fields source (built-in | external-plugin import | native manifest | MCP directory | manual), resources (installable primitives), setup (env vars, CTA, test action), contributions (allowlisted UI/runtime refs: settings panels, side panels, routes, control actions, tests), lifecycle (reload/detection hints). Start with exactly one external source adapter (the dominant plugin format in the ecosystem) rather than N importers. The org-distribution complement: install links ship the standard signed app plus an installer JSON (org name, URLs, branding — “no tokens, sessions, or secrets”); server-side tokens stored as SHA-256 hashes; MDM can drop the bootstrap file directly.

M14. Auto tool-surfacing from code (compile software into agent-operable systems)

AST-scan an app’s routes/controllers/schemas (web frameworks, OpenAPI, ORMs), detect multi-step user journeys and bundle each as a single agent capability, classify permissions at the tool boundary, and emit a runnable typed MCP server + an AGENTS.md — regenerated on every commit so the tool surface can’t drift from the code. This turns the recurring “backend routes exist but no agent/UI path reaches them” dead-path failure mode into a build step instead of a manual audit.

M15. Profile/identity composition as file composition

A profile is a directory (own config, env, identity file, memories, sessions, skills, cron, state DB); isolation is one env var the wrapper sets, with all path resolution routed through a single get_home() helper (119+ call sites in one implementation). Name-as-command: creating profile coder installs a coder wrapper binary; plus a sticky default (kubectl-context-style use). Clone granularity flags: config+identity+skills with fresh memory / everything except history / from-named-profile / blank-slate. The profile --description is not cosmetic — it is the routing signal an orchestrator LLM uses to assign work; auto-generated descriptions are flagged (description_auto: true) for human review. Persona/procedure split can be done mechanically: a converter classifies markdown headers into identity/rules/voice vs process buckets and emits SOUL-type vs AGENTS-type files from one source. Explicit non-goal: profiles isolate state, not filesystem authority.

M16. Multi-machine library sync via storage-only coupling

Sync a skills/templates/knowledge corpus across machines with NO server-to-server protocol: shared storage (S3/local FS) holds the library + a manifest (name → id/version/sha/description/uploaded_by/at) + a versioned registry (skill_id = sha256(name)[:12], monotonic version, content sha, per-file records, history capped at 20 entries, every version’s full bundle archived). Clients detect external changes by an mtime+size fingerprint and bump a generation counter so stale snapshots are droppable. Concurrent-edit safety: compare content SHA against the registry’s recorded sha before publish; on mismatch, an LLM merge combines both versions (“preserve ALL actionable guidance from both; on contradiction prefer the more specific; merged description covers both trigger sets”), falling back to keeping the incoming version. The git-flavored sibling: deterministic per-entity JSONL shards + SHA manifest + validate + pull→merge-import→export-union→push (see knowledge-pipelines for the shard format).

M17. Curated connector catalog with install-time tool selection

Protocol-server (MCP) catalog entries are repo manifests gated by maintainer PR review, disabled by default, no community tier. Install probes the live server and shows a tool checklist (pre-checks: prior selection → manifest defaults → all); checked tools persist as an include-filter. API-key entries prompt at install and write to the env store. Runtime discipline: tools namespaced mcp_<server>_<tool>; per-server include/exclude filters (“include wins”); server-initiated sampling on by default but rate-limited (max_rpm: 10, token cap 4096); ${VAR} interpolation resolved at connect time; OAuth via discovery + dynamic client registration + PKCE with tokens at 0o600; stdio child env filtered to configured vars plus a safe baseline, never the full shell env. GUI↔CLI parity invariant: every dashboard control edits the same file the CLI edits, and each surface documents its effect semantics (next session / restart / hot-reload).

M18. Prompt-card import (ecosystem-to-platform converter)

The viral distribution unit in the personal-AI niche is a self-contained “OS prompt” card: mission + phased interview + generated folder scaffold + standing rules + behavioral posture, compressed into one pasteable image/text. A converter that ingests such a card and maps it onto platform primitives (phases → interview workflow, folder tree → knowledge/project scaffold, rules → gates/triggers, posture → style constraints) turns the entire viral-prompt ecosystem into installable templates. The card genre also proves demand for installable “Domain OS” packs (intake interview + knowledge scaffold + standing rules + provenance posture as one unit).

M19. Machine-readable design system (typed docs agents can read)

A component/design system built “for humans and AI” co-locates a typed doc object with every component’s source: name, displayName, group, category, keywords[] (search aliases: “btn”, “cta”, “submit”), usage.description, usage.bestPractices[] as {guidance: true|false, description} (machine-readable Do/Don’t), usage.anatomy[] ({name, required, description}), props[] ({name, type, description, required, default}), theming variable mappings. The CLI is the canonical documentation source; the website is generated downstream (“nothing goes stale”); the hosted MCP surface (M4) builds its registries from the same corpus at module load. Each doc also exports a dense twin — a compressed translation for token-constrained contexts, governed by a checked-in compression-protocol skill with hard 1:1 invariants: bestPractices/features/notes/accessibility arrays must have identical length and order to the full doc (“Dense is a translation, not a different document — same information, fewer tokens”; compression rules: drop articles/filler verbs, fragments, w/, +, ;). Design principles that made it work: guidance over enforcement (“the system steers; it doesn’t police”), strong documented conventions so both people and AI “can predict how an unfamiliar component will behave,” and the observation that every change made for AI also helped humans. Ops detail: an npm-script alias for the CLI binary exists specifically because agents invoke wrong binary paths and fail silently.

M20. Doctor: read-only diagnostics with a contract

A doctor command converts tribal setup gotchas into a checkable ecosystem surface: N named checks (runtime version, core installed, core↔CLI version alignment, config validity, injected agent-docs presence with markers, peer deps), a hard “never installs or mutates anything” guarantee, exit code 0/1 contract for CI, --json envelope {apiVersion, type: "doctor", data: {checks, summary}}, and a suggested fix command per failure. The readiness-tier variant for live platforms: readiness is NOT boolean — (a) port ready, (b) handshake ready, (c) RPC ready (a cheap presence call succeeds) — diagnostics trust native RPC probes over log-scraping, capability failures are not core failures, and reports always identify WHICH tier failed. A doctor-anchored zero-config story (“Run Doctor / Run Doctor Fix” as a settings feature) shipped in a 7.5k-star consumer product. Complements M9: doctor verifies the managed context block a tool injected is still present and current.

M21. Fail-closed remote exposure for local-first surfaces

A local-first dashboard binds loopback by default (“no data leaves localhost”); a non-loopback bind with no auth provider registered refuses to start with an explicit error — never silently open. Bundled auth providers span the trust range: basic (scrypt + stateless HMAC tokens, rate-limited), platform OAuth (PKCE S256, 15-min tokens), self-hosted OIDC (JWKS-verified public PKCE client); the insecure override flag is loudly labeled dangerous. The web stack itself is an optional install extra — the base install ships no HTTP server at all. Same fail-closed shape as the hardened MCP surface (M7): exposure is opt-in, authenticated, and refuses ambiguous configuration. See security-and-guardrails.

M22. Agent-usability evals for the platform surface (vibe tests)

Evaluate whether the ecosystem surface itself is agent-usable: run the same prompt battery (categories: feature-with-constraint, workflow-description, clone-with-modification, data-display, responsive-challenge; complexity tiers) against different platform configurations, scored identically. Five checked invariants: (1) fair evaluators blind to configuration; (2) only the system-under-test varies; (3) never leak the answer (prompts carry expectedComponents used for evaluation ONLY — no pre-built retrieval commands derived from them); (4) representative environment (test the real npm/package delivery, not hand-written skill docs); (5) context-free sub-agents (fresh spawn per prompt, no inherited knowledge). A report app renders scorecards and screenshot galleries; the stated purpose is to “settle design debates with evidence instead of opinion.” This is the measurement half of M10’s ship-the-docs bet — cross-links verification-and-judging.

M23. The open skill-format standard as the interop lingua franca

The de-facto cross-harness unit of shareable know-how is an open spec: a folder + SKILL.md whose YAML frontmatter requires name (1-64 chars, [a-z0-9-], must match the directory name) + description (≤1024 chars, stating what it does AND when to use it — the description is the entire triggering mechanism because the body loads only after triggering); optional license, compatibility, metadata (string map with per-consumer namespaces so multiple hosts can extend one file, e.g. metadata.<host> carrying tags/category/gating), experimental allowed-tools. Progressive-disclosure contract: metadata ~100 tokens always in context → full body (<5000 tokens / <500 lines recommended) on activation → bundled scripts/ (deterministic code for fragile ops) / references/ (loaded on demand; >10k words ⇒ add grep patterns to the body) / assets/ (used in outputs, never read into context). A reference validator (skills-ref validate) exists; name validation regex ^[a-z][a-z0-9-]{1,63}$ with path-traversal guards on write. Host-specific extensions layer on without breaking portability: conditional activation gates (fallback_for_toolsets — skill visible only when a capability is MISSING; requires_toolsets — only when present), OS gating (platforms: [macos, linux]), per-skill config declarations resolved from host config and injected at load, declared binary/env requirements with installer specs (brew/uv/node/go/download) enabling one-click install UIs. Multiple independent systems (at least four in the corpus) read and write this exact format — making it the safest export/import target for any skills feature. Body-content doctrine lives in skills-and-prompt-craft.

M24. Machine-readable public exports as ecosystem glue

Three cheap export surfaces recur: (1) llms.txt + llms-full.txt doc indexes shipped with product documentation so any agent can orient without scraping; (2) a full CSV/JSON export of any curated index or digest — one content channel’s sole programmatic surface is a CSV with columns published_at, post_url, repo_slug, repo_url, repo_stars, repo_keywords, caption, likes, plays, comments, engagement columns pre-allocated before the feedback loop exists so later signals land without schema migration; (3) multi-rendering payloads — export items carry raw text + rendered plainText + rendered markdown + canonical URL in one envelope so downstream consumers never re-render. Complementary import-side rule: a headless work server exposes export/import with preview endpoints, and all writes gate on host approval.

Patterns & compositions

• The pack spectrum. Skill pack (one capability) → plugin (skills + commands + manifest) → agent/profile distribution (identity + config + skills + automations, M1) → roster/team pack (personas + scenario runbooks + staged activation, M12) → domain pack (skills + workflow templates + connectors + agent presets) → Domain OS pack (interview + scaffold + standing rules, M18). All share: manifest at root, credential exclusion, version gating updates, only-owned-paths overwritten on update.
• The interop quadrant. A platform participates in the ecosystem four ways at once: inbound dialect (OpenAI-compat API, agent-as-model, M6), outbound client (MCP client with curated catalog, M17), self-as-server (reverse MCP, hardened read-only remote surface, M7), peer (A2A in-workflow handoff, hosted external agents via ACP, M8). Each is an adapter; none dictates the internal model.
• One corpus, many readers. Typed co-located doc objects (M19) → registry → CLI (canonical) → website (generated downstream, “nothing goes stale”) → MCP two-tool surface (M3+M4). The same shape works for a component design system, a workflow-template library (see workflow-engine-design), or a skills catalog (see skills-and-prompt-craft); dense twins serve token-constrained contexts.
• Discovery channels stack. Passive: /.well-known/skills/index.json, GitHub taps, llms.txt, public CSV export. Curated: staff-reviewed registries with trust envelopes. Push: daily signal feeds (raw signal → entity extraction → plain-English pitch → multi-channel distribution → machine-readable index) — a ~30k-follower channel built entirely on this loop, with per-item provenance flags (“Spotted on …”) as the trust signal.
• GUI↔CLI single-source parity with effect semantics. Every dashboard control edits the same file the CLI edits (config file, env store, MCP block, skills dir); the REST API mirrors the frontend; and each surface documents when changes take effect (next session / gateway restart / hot-reload — “takes effect on the next event, no restart needed”). This parity is what keeps a GUI shell, a CLI, and external automation from becoming three divergent config dialects.
• Community vs enterprise catalog via one seam. A pluggable marketplace-provider registry (at most one active provider; community builds strip the public hub; enterprise plugs its own hub into the same capability/search/install routes) lets one codebase serve open-community and closed-org catalog dynamics without forking the install path. Pairs with capability-owner resolution: discovery never implies activation; at most one active owner per capability; losing providers are removed/disabled explicitly; business config survives ownership migration intact.
• Teach the ecosystem to use you. M9 (managed context block) + M10 (bundled skill + eval) + M14 (auto-generated tool surface) + M20 (doctor verifying it’s all wired) + M22 (measuring agent-usability) compose into a full “agents can operate this platform” story: generated context in the host harness, deep docs resolvable offline, probe prompts to verify loading, a manifest the agent branches on, and an eval harness proving the surface works.

Anti-patterns & failure modes

• Hand-synced copies drift — always. Even a flagship reference repo shipped a connector config with 2 JSON syntax errors that its own linter didn’t cover. Any file that exists in two places without a sync script + CI drift check will diverge.

• Prose-scraped interop is forgeable. Regex-extracting handoff/command blobs from agent output sits downstream of untrusted-document readers — a hostile document can embed a literal handoff blob. Cross-agent handoffs must be dedicated typed events/tool calls, gated by a target allowlist + additionalProperties:false schema + length caps, forwarding only the validated field.

• Tool sprawl on external surfaces. Exposing every internal capability as its own MCP tool overwhelms agent context and multiplies attack surface; the 2-tool search/get rail with namespaced discovered capabilities repeatedly wins.

• Marketplace re-skins. Community catalogs fill with find-replace duplicates (swap the market name, keep the prompt). Entity-neutralized shingle-overlap gating (M12) is the cheap LLM-free defense; without it the catalog’s signal decays.

• Shipping or touching user data on update. Any pack update that can overwrite memories, sessions, credentials, or user-edited copies destroys trust once. Distribution-owned path lists + hash-manifest “user edits skipped forever” are the fixes.

• UI-only capabilities. A surface admission rule from a disciplined local-first design: durable schema + attribution/freshness metadata + resumable sync + CLI and structured JSON access before any UI-only use. Contributed apps repeatedly ship tested backend routes no UI or agent reaches (dead paths both ways) — auto-surfacing from code (M14) or a manifest-vs-UI audit is required.

• Counting injection as adoption. Metering skill/pack “usage” by prompt-time injection inflates everything surfaced; only actual reads/loads/writes are evidence (M6 capture discipline).

• Storage calls on the hot interop path. Synchronous object-storage calls inside an async proxy loop caused intermittent stalls of the entire capture proxy — keep persistence off the request hot path.

• The article/marketing layer lies. Secondary coverage repeatedly misdescribed mechanisms (scaffolding attributed to an MCP server that only does search/get; unsourced “73% of projects fail at handoffs” stats). Catalog claims need primary-source verification before adoption.

• Ejectability as an ecosystem promise. “Everything works via the underlying runtime without the UI” — a control-plane product that stays a client of its own headless server API (never duplicating behavior in the shell) can be adopted piecemeal, embedded, or abandoned without lock-in; this composability is itself a distribution strategy (desktop shell / messaging connector / headless server from one codebase).

• Severity of exposure scales with declared capability. Device/companion-node protocols connect over the same typed wire protocol as first-party clients (role: node, challenge-nonce signed identity, pairing approval), but approval scope escalates with the declared command surface (pairing-only → operator.write → operator.admin for system-run), dangerous commands need explicit opt-in, and both the node’s declared surface AND a host allowlist gate each command (deny always wins). External peers are capability-declared, doubly gated participants — never trusted transports.

Quantitative findings

• Bundled skill + offline exact-signature docs + strict verify loop: 4/5 vs 0/5 first-try compile success, 6 vs 14 total attempts, 0 vs 3 silent spec misses, 92% vs 63% quality, at +58% tokens and roughly flat wall time.

• Probe prompts: 0% pass rate without the machine-readable docs installed — a reliable context-loaded litmus.

• Originality gate calibration: warn ≥20% / fail ≥40% shingle overlap; worst legitimate pair in a 230-file corpus ~1.5%, median 0%.

• Two-tool retrieval budgets: ~1.5K tokens per brief result; 4000-char per-topic cap; ≤6 key props per brief entry; scoring tiers 100/90/85/75/50 with keyword boost 90.

• Capability search scoring: title +5 exact / +3 prefix, description +2, searchText +1; ~37 append-only error codes in the reference envelope design.

• Hardened remote MCP limits: ≥32-byte token per surface, 64 KiB bodies, 30 s deadline, 20-burst / 1-per-sec / 4-concurrent per token, 100 results max, 2 MiB result cap.

• Hosted-agent (ACP) pool policy: 30 min idle reap session-bound / 5 min unbound; max 4 unbound runtimes per agent.

• MCP sampling defaults: on, but rate-limited to 10 rpm with a 4096-token cap.

• Shared-library publish gate (federated skill evolution): verifier threshold 0.75 with reject-by-default on unparseable output; retrieval blend similarity × (0.3 + 0.7 × effectiveness); near-duplicate pruning at pairwise embedding sim > 0.9; registry history capped at 20 versions.

• One 16-format export toolchain serves a single markdown corpus; one ~80-line document in 3 formats reached ~190k stars; a GUI-over-runtime desktop shell validating the always-on-assistant market shipped 198 releases in ~8 months.

• Skill frontmatter budgets (open standard): name 1-64 chars [a-z0-9-], description ≤1024 chars, metadata ~100 tokens always-loaded, body <5000 tokens / <500 lines, >10k-word references require grep patterns in the body.

• Skill catalog injection budget: full <available_skills> XML format (name/description/location) falls back to a compact no-descriptions form above a 30k-char budget; per-skill in-context cost ~24 tokens base with graceful compaction of over-budget lists.

• Distributed A/B publish quorum (federated skill library): up to 3 replay cases mined per candidate; accept iff candidate_mean >= threshold AND >= baseline_mean; server publishes only past min_results / min_approvals / min_mean_score, rejects at max_rejections; validation workers disabled by default, idle-gated, daily-quota-capped.

• Interview-to-install funnel: a single prompt-card artifact (7 interview phases, 4 standing rules, a 3-tier file scaffold) drew ~19.5k views organically — the “Domain OS” pack genre has proven pull with zero platform support.

• Local-first web auto-sync etiquette (a convenience layer, not automation): opt-in, 5-minute minimum interval, visible state, overlap protection, exponential failure backoff, “no work from hidden pages” — durable automation belongs to the jobs/scheduler layer.

• Vendored-skill drift detection: name-keyed rmtree+copytree sync + filecmp.dircmp CI check (diff_files or left_only or right_only) + prose-reference lint via regex `([a-z0-9]+(?:-[a-z0-9]+)+)` over agent prose.

• Version registry conventions: skill_id = sha256(name)[:12], monotonic version numbers (never dates — “multiple rounds/day make dates too coarse”), history capped at 20, every version’s full bundle archived.

Open questions

• Pack composition semantics. When two installed packs contribute overlapping skills/templates/triggers, no source defines a principled merge/priority model beyond skill-tier precedence chains (workspace > project > personal > managed > bundled) and “at most one active owner per capability” — is capability-owner resolution (explicit ownership, losers disabled, business config surviving migration) sufficient for rich packs?
• Update trust over time. Version-gated updates + hash manifests protect user edits, but nothing in the corpus re-scans an already-installed pack when its upstream turns malicious after install (the lockfile pins what was installed, not what it became). Continuous re-verification cadence is undesigned.
• A2A depth. The corpus contains A2A adapters and doctrine (“in-workflow handoff, not a networking layer”) but no measured production A2A deployment — the protocol’s real-world failure modes (identity, billing, partial-trust delegation) are unexplored here.
• Marketplace economics. Catalog dynamics (trust ladders, review gates, originality gating) are well-covered; sustainable incentive models for contributors (beyond stars) are absent from every source.
• Dialect convergence. OpenAI-compat, MCP, ACP, and A2A each solve adjacent slices; whether a personal-agent platform should expose all four (the interop quadrant) or bet on MCP subsuming the rest is unresolved — the corpus shows systems hedging by making each a thin adapter.