Product agent guides

Tool, resource, and prompt descriptions explain individual capabilities. An optional agentGuide explains how those capabilities work together as one product: when to use them, in what order, and where the product must stop or ask for clarification.

You author that judgment once in server.ts. Noodle validates every capability reference and builds one host-neutral App Package. That package can become a local Codex or Claude Code skill, compact context for the embedded assistant, a caller-specific skill for compatible MCP agents, or part of an OpenAI or Claude host package.

Decide whether the product needs a guide

The Noodle workflow skills make this decision during normal MCP server design. You do not need to know the agentGuide property name or explicitly ask your coding agent for it. The agent should inspect the declared capabilities, state whether the product should be guided or intentionally unguided, explain why, and ask only for product decisions it cannot infer from source.

Add a guide when:

• one user workflow crosses multiple tools, resources, or prompts;
• capability order, grounding, clarification, or product-specific boundaries matter;
• representative requests help an agent select the right workflow; or
• you want Noodle to generate an App Package product skill.

A product with a single self-explanatory capability may omit the guide when its description, schema, and safety annotations already explain correct use. Tool count is only a signal. One consequential capability may still need a guide, while several independent and obvious capabilities may not.

Understand the three layers

Updating Noodle guidance must not overwrite your app's source or a modified app product skill. Likewise, the generated app skill does not replace the Noodle workflow that teaches an agent how to edit server.ts.

server.instructions and agentGuide also have different jobs. Keep instructions as a concise live session primer. Use agentGuide for richer product workflows that Noodle can validate, filter, and package. Do not copy the same prose into both.

Author the guide in TypeScript

Keep the guide in the same TypeScript source graph as the server. Each workflow step points to one declared capability by exact kind and name. Do not repeat schemas, connector settings, URLs, credentials, or runtime data in the guide.

import { type AgentGuideSource, server } from '@noodleseed/one';

const supportGuide = {
  description: 'Use Acme Support to investigate and resolve a grounded customer case.',
  useWhen: ['The user asks to review or resolve an Acme Support case.'],
  workflows: [
    {
      id: 'resolve_case',
      title: 'Resolve a customer case',
      steps: [
        { capability: { kind: 'resource', name: 'case_record' } },
        {
          capability: { kind: 'tool', name: 'resolve_case' },
          guidance: 'Use only after grounding the exact case and confirming the requested resolution.',
        },
      ],
    },
  ],
  boundaries: ['Never invent a case identifier or weaken the tool confirmation requirement.'],
  examples: [{ prompt: 'Resolve case CS-104 after I review it.', workflow: 'resolve_case' }],
} as const satisfies AgentGuideSource;

export default server(
  'acme_support',
  { title: 'Acme Support', version: '1.0.0', agentGuide: supportGuide },
  [
    // Declare case_record and resolve_case here. The compiler checks both references above.
  ],
);

The guide cannot make a write safer by assertion. Tool annotations, authorization, confirmation, visibility, and widget boundaries remain authoritative. An unknown capability, wrong capability kind, duplicate workflow ID, invalid example mapping, or credential-shaped value fails compilation.

Follow the local-first journey

1. Validate the source

Validate and test the same server.ts that will be deployed:

noodle validate
noodle test

The compiler combines your product judgment with factual MCP details such as capability names, input and output summaries, and safety annotations. It does not ask you to maintain a second manifest or skill file.

2. Preview and install the generated skill

Preview the exact file and ownership plan before writing anything:

noodle agents setup --json
noodle agents setup --write

The preview is read-only. --write installs the approved product skill under .agents/skills/<app-slug>/ for Codex and .claude/skills/<app-slug>/ for Claude Code, according to the project's configured agent targets. Use --agents all when you intentionally want both targets regardless of that project default.

Each skill root contains SKILL.md and a generated references/mcp-surface.md. The first file teaches the workflow; the reference records the MCP facts it depends on. These files teach an agent how to use the product, but they do not connect that agent to an MCP URL by themselves.

3. Test the behavior locally

Run the server and connect your chosen MCP client to the local URL it prints:

noodle dev

Try at least one clear workflow prompt, one ambiguous prompt that should trigger clarification, and one out-of-scope or unauthorized prompt. Confirm that the agent chooses the expected capabilities in the right order and that the runtime still enforces authentication, confirmation, and tool visibility.

4. Add distribution metadata only for a host package

agentGuide teaches product behavior. The separate distribution option supplies host-neutral listing and review material: summary and description, publisher and support links, legal links, icons, screenshots, and credential-free review scenarios. Listing edits do not change the Runtime Artifact or canonical product skill.

Add distribution only when you are preparing an OpenAI or Claude package. Each positive review scenario should identify the expected MCP tool names; negative scenarios should name no tools. For MCP App screenshots, capture the rendered app response rather than your website, Devtools shell, or surrounding chat. Keep each screenshot's generating prompt as separate metadata.

See the server SDK reference for the option boundary and the Food Ordering example for a complete authored distribution.

5. Deploy and inspect the immutable package

Sign in only when you are ready to use the hosted runtime:

noodle login
noodle deploy

Every guided deployment stores the exact App Package beside its Runtime Artifact. In the Console, open that deployment's Package tab to inspect the generated skill and MCP reference, switch between supported host views, copy an individual file, or download the package. The Console Package view always reads the selected deployment's snapshot. Restarting or rolling back does not silently regenerate historical bytes.

If you want Noodle to retain an immutable target archive after deployment, publish it explicitly:

noodle distributions publish <deployment-id> server.ts \
  --target openai \
  --category Productivity

Hosted publication currently requires an eligible deployment whose access mode is public, which means anonymous access, and refuses to publish when the local package snapshot differs from the selected deployment. It stores the archive; it does not submit it to the external host. The Console and noodle distributions expose the same inspect, download, readiness, review-evidence, release, rollback, deprecation, revocation, and private-grant lifecycle.

Do not weaken an application's authentication or authorization merely to make it distributable. Keep a protected deployment protected and use the local export, or create a separate public deployment only when anonymous access is intentional.

6. Use the guide at runtime

The same deployed guide has two runtime paths.

Embedded assistant. When the server also declares an embedded assistant, Noodle automatically adds a compact guide projection to model context on every turn. Only complete workflows supported by that session's model-visible tools, roles, and scopes are included. If no complete workflow is available, no guide is added. This keeps irrelevant or unauthorized instructions out of context.

The behavior is server-side, so it applies both to the managed renderer and to a custom interface built with the assistant package's public createAssistantClient. There is no renderer prop or browser-side guide field. Raw guide and skill files never enter the browser session. See the embedded assistant guide for session and rendering setup.

Direct skill-aware agent. A compatible agent connected directly to the deployment's tenant MCP URL can discover a caller-specific product skill through the modern draft MCP Skills extension. The projection uses the same customer OAuth boundary and can differ by caller. Legacy MCP clients continue to receive the normal tools, resources, and prompts surface.

Host support for the draft extension is not universal. A direct MCP connection does not mean a marketplace installed or published the product.

7. Regenerate after the product changes

A normal setup refresh does not silently replace an existing app product skill. After changing the guide or MCP surface, preview and explicitly apply regeneration:

noodle agents setup --regenerate-app-skill --json
noodle agents setup --write --regenerate-app-skill
noodle agents doctor --json

If a previously Noodle-owned app-skill file was modified locally, regeneration preserves it and reports the collision. Use --replace-modified-app-skill only after reviewing the exact affected files and approving the loss of those local edits. It cannot claim unrelated files or bypass malformed ownership state.

Prepare an OpenAI plugin submission

After the MCP server has a production URL and server.ts contains both agentGuide and distribution, create the local review kit:

noodle export plugin openai server.ts \
  --state submission \
  --mcp-url https://acme.example.com/mcp \
  --category Productivity \
  --output acme-openai.zip

noodle export does not deploy, upload, submit for review, or publish anything. The outer ZIP is a complete review kit and local package, not a skill upload. Extract it before using either submission artifact:

• submission/<app-slug>-skill.zip is the manual skill-upload artifact. It contains one skill root with <app-slug>/SKILL.md and its reference file. Upload this nested ZIP only when you choose manual skill upload; never upload the outer kit as a skill.
• submission/chatgpt-app-submission.json is a structured review reference for listing copy, tool annotations, and test cases. It carries $schema: "https://developers.openai.com/apps-sdk/schemas/chatgpt-app-submission.v1.json". The current documented portal flow is form-driven and does not make this JSON the primary upload step. If the portal presents an assisted import field, follow its on-screen validation and review every imported value.
• submission/README.md records the generated package-specific instructions.

OpenAI's current documented submission path is:

1. Create a plugin and choose With MCP.
2. Enter the public production MCP URL, authentication details, reviewer credentials when required, content security policy, and domain verification token. Serve the exact challenge token at https://<challenge-base-host>/.well-known/openai-apps-challenge, and make sure reviewer credentials do not require MFA, email confirmation, SMS confirmation, or private-network access.
3. Select Scan Tools, then review the discovered tools, annotations, domains, validation results, and any imported skills.
4. Add the product skill either by uploading the nested single-root skill ZIP or by letting Scan Tools import the static skill exposed by the deployed MCP server.
5. Complete the listing, starter prompts, availability, five positive test cases, and three negative test cases, then submit the reviewed draft.

An MCP-imported skill is a submission-time snapshot, not a live marketplace resource. After deploying a guide change, run Scan Tools again and submit a new reviewed plugin version. The MCP server remains the live source of tools, data, authentication, and actions.

Use --state local instead when testing a registered app inside a local Codex marketplace. The export command reference owns the exact flags. Recheck OpenAI's current plugin construction, MCP skill import, and submission pages before a real submission.

Prepare Claude outputs

Claude has two deliberately separate outputs.

The plugin export is an installable Claude Code repository with Claude's native manifest, MCP configuration, and the generated product skill:

noodle export plugin claude server.ts \
  --mcp-url https://acme.example.com/mcp \
  --output acme-claude.zip

Extract it, run claude plugin validate . --strict, and test it with claude --plugin-dir ..

The connector export is a credential-free worksheet for Anthropic's remote Connectors Directory portal:

noodle export connector claude server.ts \
  --mcp-url https://acme.example.com/mcp \
  --auth oauth-dcr \
  --category Productivity \
  --output acme-anthropic-connector.zip

These archives are not interchangeable. The connector dossier is marked portalUploadable: false; a human still connects the server in Claude.ai, verifies allowed-link ownership and OAuth, supplies test credentials out of band, completes company and data-handling answers, and submits through the portal. A remote connector submission does not install the Claude Code skill.

For an MCP App, Anthropic currently requires three to five PNG screenshots at least 1,000 pixels wide. Crop each image to the rendered MCP App response and provide its prompt separately. Do not include the surrounding Claude conversation, your website, or a decorative product image. Recheck Anthropic's current submission requirements before external review.

What the guide improves

The generated skill gives an agent a product-level map that individual tool schemas cannot provide. It can improve when the agent selects the MCP product, which capability it calls first, how it grounds a write, when it asks for missing information, and when it should stop. This is especially useful for permission-gated products with many related tools.

It does not grant permissions, expose hidden tools, replace tool schemas, bypass confirmation, or guarantee perfect tool calls. Runtime authorization remains authoritative. Distribution metadata is not injected into assistant context, and the embedded assistant receives only the compact workflows that the current caller can actually complete.

For a complete multi-tool guide, see the Food Ordering example. It maps browsing and building an order, summarizing options, and planning pickup or delivery to one guide while preserving app-only tool visibility.