Product agent guides

Tool, resource, and prompt descriptions explain individual capabilities. An optional agentGuide adds the product judgment that an agent needs to combine those capabilities into useful workflows. You author that judgment once in TypeScript. Noodle validates every capability reference and generates the host-neutral App Package used for local Codex and Claude Code product skills.

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.

Three different 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.

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.

Preview and install locally

Validate the TypeScript first, then review the file and ownership plan before writing anything:

noodle validate
noodle test
noodle agents setup --json
noodle agents setup --write

The first three commands are read-only with respect to agent files. --write installs the approved product skill under .agents/skills/ for Codex and .claude/skills/ for Claude Code, alongside the Noodle workflow skills. This local flow needs no Noodle Cloud account.

Export an OpenAI package

After the MCP server has a testable URL, use noodle export plugin openai. Choose submission to prepare a public-directory candidate, or local after copying the app's technical ID from ChatGPT developer mode. The export command writes only a local archive; it does not deploy, register, upload, submit for review, or publish the app.

For --state submission, the output ZIP is a review kit, not the file to drop into the portal. Extract it, then upload submission/chatgpt-app-submission.json to the Codex-assisted import field and the nested submission/<app-slug>-skill.zip to With MCP → Skills. The nested ZIP contains one skill root. Do not That root preserves the canonical <app-slug>/SKILL.md directory instead of flattening SKILL.md to the ZIP root. Do not upload the outer kit as a skill. In distribution.review.scenarios, give each positive case the exact expected MCP tool names through tools; omit tools for negative cases.

The export command reference owns the exact flags. Reverify OpenAI's current plugin package and submission requirements before a real submission.

Export for Claude

Claude has two deliberately separate outputs. The plugin export is an installable Claude Code repository:

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

Validate its extracted directory with claude plugin validate . --strict, then test it with claude --plugin-dir .. The archive contains Claude's native manifest and MCP configuration plus the same generated product skill.

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

noodle export connector claude \
  --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 verifies allowed-link ownership and OAuth, supplies test credentials out of band, completes company and data-handling answers, and submits through Anthropic's portal.

For an MCP App, author three to five PNG screenshots at least 1,000 pixels wide. Each distribution screenshot also needs the separate prompt that produces that exact state. Capture only the rendered MCP App response—not your website, Devtools shell, the surrounding Claude conversation, or a decorative product photo. Reverify Anthropic's current submission requirements before external review.

Update and regenerate safely

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.

Deployment and history

When a guided server is deployed, Noodle stores the exact App Package beside that deployment's Runtime Artifact. The Console Package view reads the selected deployment's snapshot. Restarting or rolling back does not regenerate it, so historical deployments retain their original product-skill bytes even after newer source is deployed.

Use the guide at runtime

Once deployed, the same guide can help agents without another authoring field or browser option. The embedded assistant automatically adds only complete workflows supported by the current session's surface, roles, scopes, and model-visible tools. The guide remains on the server; browser clients receive neither the raw skill files nor a new configuration requirement.

A direct skill-aware agent connected to the tenant MCP URL can discover a caller-specific projection through the modern draft MCP Skills extension. It reuses the deployment's customer OAuth boundary, and different callers can receive different workflow content and digests. This preview does not mean every MCP host supports the draft extension, and it does not submit or publish anything to a marketplace.

For a complete multi-tool example, see Acme Tasks. It maps its review, capture, prioritization, and completion flows to one guide while preserving write confirmation and app-only tool visibility.