Shipping Prompts with Your Marketplace Agent

You built a support-triage agent. The handler works. Tests pass. Prompts live in ./prompts/system.md beside your code. You run human marketplace publish and wait for the first customer install.

Then support ticket #1 arrives: ctx.prompts.load('support-triage/system') threw PromptNotFound. Your customer's org has your handler binary — not your laptop's ./prompts folder.

This is the marketplace author's problem: prompts must ship with the agent and resolve at install time, the same way HUMΛN reference agents resolve in production. Disk-based loading is a dev workflow. Install-time seeding is the production workflow.

This article closes the loop — dev → manifest → marketplace → customer install → runtime — so your third-party agent behaves like a first-party one.

The developer's problem

Marketplace agents are npm packages (or equivalent bundles) installed into customer orgs. Each install creates:

A deployed handler
Delegation scopes for operations
Connector grants for integrations

Without an explicit prompt seeding path, authors fall back to:

Hardcoding prompts in source — unversioned, unreviewable, fails Check #15.
Expecting customers to copy ./prompts — fragile, undocumented, breaks on upgrade.
Calling createPromptRegistry() per execution — slow, bypasses DB versioning, wrong pattern for handlers.

None of these survive enterprise review. Prompts are IP and safety surface — they need identity, versioning, and certification like any other artifact.

How disk-based loading works (dev workflow)

During local development, prompts live in your repo:

my-support-agent/
  src/handler.ts
  prompts/system.md
  install-manifest.ts

Validate before commit:

human prompts lint --dir ./prompts
# ✓ support-triage/system

human prompts render support-triage/system \
  --var product="Acme Cloud" \
  --var tier="enterprise"

Your handler uses the canonical runtime API — not a per-call registry:

import { handler } from '@human/agent-sdk';

export default handler(async (ctx, input) => {
  const prompt = await ctx.prompts.load('support-triage/system', {
    variables: { product: input.product, tier: input.tier },
  });

  const result = await ctx.llm.complete({
    system: prompt.render(),
    prompt: input.customerMessage,
    promptMetadata: prompt.toCallMetadata(),
  });

  return { triage: result.content };
});

Locally, the runtime resolves from disk + org overlay. Customers do not have your disk. You must declare what to seed.

agent_prompt_contributions bridges dev → marketplace → runtime

ECC-04.2 adds agent_prompt_contributions to InstallManifest. Each entry describes one prompt file inside your package:

import type { InstallManifest } from '@human/core';

export const manifest: InstallManifest = {
  agent_id: 'acme.support-triage',
  name: 'Acme Support Triage',
  version: '1.2.0',
  capabilities: ['support/triage'],
  agent_prompt_contributions: [
    {
      prompt_key: 'support-triage/system',
      scope: 'org',
      namespace: 'com.acme.support',
      content_ref: 'prompts/system.md',
      version: '1.2.0',
      type: 'system',
    },
  ],
};

Field	Purpose
`prompt_key`	Logical id passed to `ctx.prompts.load()`
`scope`	`org` (typical for marketplace agents), `core`, or `marketplace`
`namespace`	Optional org-scoped namespace for multi-tenant authors
`content_ref`	Path relative to package root — must end in `.md`
`version`	Semver seeded into `prompt_versions`
`type`	`system`, `task`, or `lens`

Marketplace review runs Check #15 Prompt Safety Certification on these files — structural validation, Prompt Defense Baseline, malicious-pattern scan. Listings expose prompt_certification (SHA-256 per prompt_uri), never prompt bodies.

The install-time seeder — what happens when a customer installs

When a customer runs human marketplace install acme-support-triage (or installs via Command Plane), the marketplace installer:

Resolves the package root on disk
Reads each content_ref file
Validates Defense Baseline and schema
Calls publishPrompt() into the customer's org registry
Emits gate event agent_prompts_seeded

From the customer's perspective, nothing manual happens — no "copy prompts into Settings." After install, ctx.prompts.load('support-triage/system') hits the DB the same way invoice-processor loads core/agents/invoice-processor/system for HUMΛN reference agents.

If certification hashes drift between review and install, install blocks with PROMPT_CERTIFICATION_DRIFT — buyers get integrity, authors get a clear fix path (republish with matching hashes).

Runtime resolution — identical for you and for HUMΛN

At execution time, handlers do not branch on "am I marketplace or first-party?":

const prompt = await ctx.prompts.load('support-triage/system', {
  variables: { product, tier },
});

await ctx.llm.complete({
  system: prompt.render(),
  prompt: userMessage,
  promptMetadata: prompt.toCallMetadata(), // version + uri for telemetry
});

Telemetry ties LLM calls to prompt version. The Prompt Refinement Agent can propose improvements. Operators roll back bad publishes with human prompts rollback support-triage/system --to 1.1.0.

Do not call createPromptRegistry() inside handlers — that pattern is for CLI lint/render tooling, not per-execution agent code (see @human/agent-sdk README).

Prompt versioning for published agents

Shipping v1.2.0 of your agent package does not automatically overwrite every customer's active prompt pointer. Versioning works like any semver artifact:

Patch / minor prompt fix (1.2.0 → 1.2.1):

Bump version in agent_prompt_contributions
Publish new marketplace package
New installs seed 1.2.1
Existing installs keep 1.2.0 until they upgrade the agent or an operator publishes explicitly

Breaking prompt change (1.x → 2.0.0):

Publish under a new prompt_key suffix or major semver
Document migration in release notes
Offer rollback: human prompts rollback support-triage/system --to 1.2.0

Hotfix without agent package bump:

Operators with prompt:publish can publish content directly via API/CLI
Prefer package bumps for reproducibility — install seeding should match marketplace manifest

Test the lifecycle locally before publish:

human prompts lint --dir ./prompts
human prompts publish support-triage/system --scope org
human prompts versions support-triage/system

Checklist before your next marketplace publish

Prompts in prompts/**/*.md with Defense Baseline block
agent_prompt_contributions matches every ctx.prompts.load() key
human prompts lint clean
human marketplace review --prompts-dir . (Check #15)
Handler uses ctx.prompts.load() — no inline system strings

Your agent's business logic is the differentiator. Governed, shippable prompts are how customers trust it in production — and how you sleep after the first $95k-scale escalation lands in someone else's org.

Series: Developer guide to ctx.prompts · Protocol-level prompt management · Self-improving prompt loop