[frontegg-david]

Fixes #1126.

Stacks on #1140.

What and why

load_skill used one loaded-skill schema in two places of its output schema: skill (for skillId) and skills[].skill (for skillIds). tools/list wrote that object out in full both times, with no $ref. Every Skilled OpenAPI server sent the same 866 bytes twice. (It was 812 bytes in 1.11.1-rc.1; this stack's asksForConfirmation marker added 54.)

The fix takes the issue's first option, define once and reference, because it doesn't change what load_skill returns:

• The loaded-skill schema is registered with an id: .meta({ id: 'LoadedSkill' }). zod's toJSONSchema then writes it once, under $defs.LoadedSkill, and both places point to it with { "$ref": "#/$defs/LoadedSkill" }.
• The change is in the plugin only. The SDK already lists an output schema whose parts are $defs references, and it already has tests for that. Passing reused: 'ref' in the SDK instead would change the listed schema of every tool that reuses a sub-schema.
• zod 4.6 doesn't throw when an id is registered twice, so loading the plugin twice in one process (CJS and ESM, or a test that resets modules) is safe.
• The second option, one result shape for both inputs, isn't needed. It would change the result skillId callers get.

What reads the listed schema, and how it handles $defs / $ref:

• The MCP client (Client from the upstream SDK, through @frontmcp/protocol) compiles each outputSchema with Ajv and checks structuredContent on every callTool. Ajv resolves the local $ref, and it rejects a nested skill that breaks the definition.
• Elicitation wraps the schema in oneOf. extendOutputSchemaForElicitation already keeps $defs at the root, where #/$defs/... resolves.
• The undeclaredKeys: 'keep' policy walks the whole schema, $defs included.
• The answer budget's check (z.fromJSONSchema) resolves the reference too.
• The 'description' output-schema mode renders skill as object, as it did before.
• Whole-schema copies keep $defs with the rest: a lazy app's placeholder tools (built from the build manifest), codecall's describe and getTool, and the skills HTTP pages.
• Readers that ignore output schemas: the generated CLI keeps only inputSchema from tools/list, and the webmcp bridge copies only inputSchema.

Scenarios covered:

• the listed schema describes the skill once;
• it is smaller than before;
• skillId and skillIds answers validate, with and without elicitation;
• a skill that breaks the referenced definition is refused.

User-facing change

• What changed: In tools/list, load_skill's outputSchema describes a loaded skill once, under $defs.LoadedSkill. properties.skill and properties.skills.items.properties.skill are now { "$ref": "#/$defs/LoadedSkill" }. What load_skill returns doesn't change.
• Before → after (bytes of JSON, with the issue's one-skill bundle):
  • load_skill's outputSchema: 2,118 → 1,337 (−781, −37%);
  • load_skill in tools/list: 3,725 → 2,944;
  • the whole tools/list: 9,723 → 8,942 (−8%).
  • The size doesn't depend on the bundle.
  • A client whose validator can't resolve a local $ref in an outputSchema would now fail to check load_skill's answers. The MCP TypeScript SDK's client resolves it, and $defs / $ref are core keywords of JSON Schema 2020-12, the dialect MCP assumes.
• frontmcp.dev pages affected (if known): reference/plugins/skilled-openapi, if it shows load_skill's listed schema.
• Skills catalog entries updated: none. No catalog entry shows load_skill's schema. The plugin README's load_skill row now says the skill is described once, under $defs.

Tests

Added load-skill.output-schema.spec.ts (8 tests). It connects the MCP client to a two-skill server over the in-memory transport and reads load_skill from tools/list:

• skill and skills[].skill are the same $ref, $defs holds only LoadedSkill, and the action object is written once;
• the schema is under 2,118 bytes and within a 1,337-byte budget;
• with and without elicitation: { enabled: true }:
  • the skillId and skillIds answers pass the client's own check on callTool;
  • AjvJsonSchemaValidator from @frontmcp/protocol finds them valid;
  • a skill under skills[] with no instructions is refused, which shows the reference is followed.

The two schema tests fail on the old schema. The validation tests pass on both.

Run:

• nx run-many -t build -p sdk,plugin-skilled-openapi,testing: passed.
• nx test plugin-skilled-openapi: 54 suites, 852 tests passed.
• nx test skills: 3 suites, 249 tests passed.
• nx test demo-e2e-skilled-openapi: 11 suites, 99 tests passed.
• nx run plugin-skilled-openapi:typecheck and tsc --noEmit -p plugins/plugin-skilled-openapi/tsconfig.lib.json: passed.
• prettier and eslint on the changed files: clean.

Not run, since nothing they cover changed:

• nx test sdk and the bundle-size e2e: the SDK is unchanged;
• demo-e2e-cli-exec: the generated CLI doesn't read output schemas.

[coderabbitai]

Warning

Review limit reached

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Next included review available in 28 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: agentfront/frontmcp
• Branch: fix/cli-skilled-messages
• File: .coderabbit.yaml
• Commit: f9aa965
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Essentials
• Run ID: f3da7257-4bca-4f31-aa38-3b99551350cb

Commits

Reviewing files that changed from the base of the PR and between f9aa965 and 0c74867.

Files selected for processing: 3

• plugins/plugin-skilled-openapi/README.md
• plugins/plugin-skilled-openapi/src/__tests__/load-skill.output-schema.spec.ts
• plugins/plugin-skilled-openapi/src/tools/load-skill.schema.ts

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[github-actions]

Performance Test Results

Status: ✅ All tests passed

Summary

Project	Tests	Passed	Warnings	Failed	Leaks
✅ demo-e2e-agents	4	4	0	0	0
✅ demo-e2e-cache	11	11	0	0	0
✅ demo-e2e-codecall	4	4	0	0	0
✅ demo-e2e-config	4	4	0	0	0
✅ demo-e2e-direct	3	3	0	0	0
✅ demo-e2e-elicitation	1	1	0	0	0
✅ demo-e2e-errors	4	4	0	0	0
✅ demo-e2e-hooks	3	3	0	0	0
✅ demo-e2e-multiapp	4	4	0	0	0
✅ demo-e2e-notifications	3	3	0	0	0
✅ demo-e2e-openapi	2	2	0	0	0
✅ demo-e2e-providers	4	4	0	0	0
✅ demo-e2e-public	4	4	0	0	0
✅ demo-e2e-redis	15	15	0	0	0
✅ demo-e2e-remember	4	4	0	0	0
✅ demo-e2e-remote	5	5	0	0	0
✅ demo-e2e-serverless	2	2	0	0	0
✅ demo-e2e-skills	15	15	0	0	0
✅ demo-e2e-standalone	2	2	0	0	0
✅ demo-e2e-transport-recreation	3	3	0	0	0
✅ demo-e2e-ui	4	4	0	0	0

Total: 101 tests across 21 projects

📊 View full report in workflow run

---

Generated at: 2026-11-05T17:52:51.940Z
Commit: e9651606

[github-actions]

Cherry-picked with its stack

This PR is part of stack #1121. Its cherry-pick to main is made as one PR for the whole stack when the stack's top PR, #1142, merges.

If #1142 does not merge, run the Cherry-pick to main workflow by hand with stack: 1121.