Skip to content

feat(skills): add formio-uag for agentic forms with the Form.io UAG 2.0 - #113

Merged
travist merged 6 commits into
mainfrom
add-formio-uag-skill
Oct 30, 2026
Merged

travist merged 6 commits into
mainfrom
add-formio-uag-skill

Conversation

@travist

@travist travist commented Oct 28, 2026

Copy link
Copy Markdown
Member

Summary

Adds formio-uag, a skill that teaches a coding agent to build agentic forms with the Form.io Universal Agent Gateway (UAG) 2.0. It ships alongside the UAG 2.0 release. The skill was written from the UAG 2.0 developer docs (formio/uag, demo/content/developers), MIGRATING-2.0.md and packages/uag-js. Because the plugin now has thirteen skills, this PR also brings the library back near Claude Code's skill-listing budget.

The new skill

  • Five steps. SKILL.md takes a request through PATTERN → FORM → SERVER → APPLICATION → VERIFY, across the UAG's four surfaces:
    • conversation forms over the UAG's MCP endpoint;
    • the chat widget (Formio.createChat);
    • Agentic Formflow: the Agent API, plus Agent Input in @formio/uag-js;
    • agentic workflows with the "Agent: Run task" action.
  • Ten reference files:
    • patterns and licensing;
    • tasks;
    • every uag* form property;
    • Run task workflows and agent roles;
    • the Agent API (HTTP);
    • @formio/uag-js in vanilla JS, React and Angular apps;
    • the chat widget;
    • MCP clients (Claude Desktop, claude.ai, custom);
    • deployment;
    • troubleshooting.
  • Rules for build-time work:
    • The UAG URL is a third value. The user supplies it, and it is never recorded with project_set.
    • Form writes go through formio-form-builder's edit lane. Any change to uagAnonymous or uagTools, or removing uagAuthoritative, must be named and approved separately at that step.
    • action_create is never used for agentRunTask. Form.io's action catalog does not list that action, so action_create rejects it. The skill names the four routes that do work: a first-build template, a portal stage connected to the UAG, a UAG module template, or Form.io's action API run by the user.
  • A ## Security section covering keys, the identity research runs as, the cost of anonymous use, the fact that browser routing is not a security boundary, the shared JWT_SECRET, and criteria being sent to models as prompts.
  • Handoffs: formio-actions sends "Agent: Run task" to the new skill, and formio-form sends agent-filled forms and chats.

Keeping descriptions within the skill-listing budget

Claude Code lists the descriptions of all installed skills within 1% of the context window, about 8,000 characters at 200k tokens. Above that, it drops the descriptions of the skills used least, and those descriptions are what routing relies on.

  • Every description is shorter. The 13 top-level skills went from 12,902 to 9,225 characters combined; all 17 went from 16,551 to 11,600. Every trigger phrase a test or spec requires is kept, and so is every Not for: handoff.
  • A new test caps the combined total at 9,600 characters. I confirmed it fails at 9,000. Both READMEs now explain how to raise the budget (skillListingBudgetFraction or SLASH_COMMAND_TOOL_CHAR_BUDGET).
  • formio-uag puts its surface and reference tables first. After compaction Claude Code keeps only the first 5,000 tokens of a skill, and those tables plus the Security section now fall inside that window.
  • Contents lists were added to the formio-uag references and to the four longest references elsewhere in the library.

Tests and docs

  • New test file: packages/skill-tests/src/formio-uag/skill-structure.test.ts.
  • Library counts now expect 17 SKILL.md files, and formio-uag is added to the list of skills that must carry a Security section.
  • Updated fixtures:
    • The description snapshot was re-taken.
    • The tool-reference scanner now ignores form_name and form_data, which are arguments of the UAG's own MCP tools.
  • Docs: manifests, both READMEs, CLAUDE.md, three example prompts in examples/agents/, the OpenSpec change add-formio-uag-skill, and a minor changeset.

Verification

  • pnpm test: 1,666 skill tests and 1,937 server tests pass. pnpm lint and pnpm format are clean.

  • Routing eval: eight new prompts were added (six that should route to formio-uag, two that should not).

    Run Result
    Base (main) 33/33
    New skill added, before shortening 41/41
    After shortening, three runs (two Sonnet, one Opus) 41/41 each

    No prompt that passed on the base fails now.

  • Accuracy review: an independent review checked the skill against the UAG source. It found seven issues, none high severity, and all are fixed. Examples: setting LICENSE_KEY on a hosted project stops the UAG loading the project unless the key's endpoint allowlist includes it, and CORS accepts only a single origin.

Not in this PR

  • Bodies over the recommended size. Eight other skill bodies are still above the recommended ~5,000 tokens. Each one carries about 1,300 tokens of shared setup-check text that the tests require to be identical in every skill, so reducing it means changing those tests.
  • A UAG docs gap. The UAG docs' production checklist says to expose only /mcp, /auth and /.well-known. That would block the chat widget and Agent Input. The skill notes this; the UAG docs should probably note it too.

🤖 Generated with Claude Code

travist and others added 6 commits October 28, 2026 18:35
Add a skill that teaches an agent to implement agentic forms with the
Form.io Universal Agent Gateway (UAG) 2.0, authored from the UAG 2.0
developer documentation, and keep the library within Claude Code's
skill-listing budget now that it has thirteen skills.

formio-uag
- SKILL.md routes a request through PATTERN -> FORM -> SERVER ->
  APPLICATION -> VERIFY over the UAG's four surfaces: conversation forms
  over its MCP endpoint, the chat widget (Formio.createChat), Agentic
  Formflow (the Agent API and Agent Input in @formio/uag-js), and agentic
  workflows with the "Agent: Run task" action.
- Ten references: patterns and licensing, tasks, form properties (every
  uag* property), workflows, the Agent API, @formio/uag-js (vanilla,
  React, Angular), the chat widget, MCP clients, deployment,
  troubleshooting.
- Build-time rules: the UAG URL is a third value the user supplies and
  project_set never records; form writes go through formio-form-builder's
  edit lane, with uagAnonymous, uagTools and removed uagAuthoritative
  named at its gate; action_create is never used for agentRunTask, which
  it refuses because Form.io's catalog does not list it.
- A Security section for keys, research identity, anonymous cost, browser
  routing, the shared JWT_SECRET and criteria as prompts.
- formio-actions and formio-form hand UAG work to the new skill.

Listing budget
- Shorten every description (top-level total 12,902 -> 9,225 characters),
  keeping every pinned trigger phrase and Not for handoff. Claude Code
  lists descriptions within 1% of the context window and drops the
  least-used ones beyond it.
- description-budget.test.ts caps the combined top-level total at 9,600
  (revert-checked); the READMEs explain how to raise the budget.
- formio-uag leads with its surface and reference tables so they and the
  Security section fall within the 5,000 tokens kept after compaction.
- Contents lists on the formio-uag references and the four longest
  library references.

Tests and evals
- New packages/skill-tests/src/formio-uag/skill-structure.test.ts; library
  counts move to seventeen SKILL.md files; formio-uag joins the
  Security-section list; the description snapshot is re-taken; the
  tool-reference scanner treats form_name / form_data (the UAG's own MCP
  arguments) as look-alikes.
- Eight routing-eval prompts. Base 33/33; change 41/41; shortened
  descriptions 41/41 in three runs (two Sonnet, one Opus).
- Accuracy review against the UAG sources; its seven findings are fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- State that self-hosted Enterprise needs a UAG-inclusive license even
  for MCP and the chat widget (SKILL.md table, Stance, uag-js.md).
- Teach formio-form-builder's edit lane to apply a prepared change from
  formio-uag as given and confirm each named setting separately.
- Limit the template route for agentRunTask to a not-yet-imported
  template; list the action API in Step 3.
- Name x-token with a project API key for the action API on Enterprise
  and the hosted service.
- Reconcile the ctx.text rule with the uagChatNotice example.
- Make the agent-api SSE reader null-safe and fail on a stream that
  ends without a result.
- Type the React chat sample with createChat/ChatForm, keep the latest
  onSaved in a ref, and catch a rejected createChat.
- Drop the dead token cache in the mcp-clients sample.
- Reuse shared skillsRoot/descriptionOf helpers in the uag structure
  test and scan every fence of browser-facing references for keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…self

formio-uag now owns the first-build route for agentic forms: it runs
formio-resource-planner, adds the uag tag, tasks and agentRunTask
actions to the unimported template.json (and the matching Actions lines
in template.md) behind its own approval gate, then hands the pair to
formio-application, which already takes an approved pair straight to
import. The orchestrator and planner stay unaware of the UAG; a test
asserts their SKILL.md files never name it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Until 2.0.0 is released, UAG 2.0 ships as 2.0.0-rc.N under npm's `rc`
dist-tag while `latest` still names 1.x for @formio/uag, @formio/uag-claude
and the formio/uag image. The skill wrote unpinned images, bare npm
installs and `@formio/uag-js@2` CDN URLs, which resolve to 1.x or 404
because a semver range never matches a prerelease.

patterns-and-licensing.md gains a Versions section: resolve each package
from `npm view <pkg> dist-tags`, use a stable 2.x `latest` when there is
one, otherwise the `rc` version, and pin it exactly everywhere. Samples
now write {uagVersion}, {uagJsVersion} and {engineVersion}, and tests
reject any unpinned UAG package, image or CDN range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ying and embedding it

Corrects what did not match the UAG: a multiple select with static values is a
decision field; agent engines are told each field's validation, and a task
run leaves out an answer the form refuses; the uag* switches take JSON
booleans; `uag` on Columns and Tables flags their inputs; persona and
agent_provide_data are gone; every Agent API error is { requestId, error, code };
OAuth errors and the /mcp 401 follow the OAuth RFCs; client_credentials
returns no refresh token, and a sign-in ends with its Form.io login;
JWT_EXPIRE_TIME defaults to 60 minutes and MAX_BODY_SIZE to 16mb; CORS takes
several origins; keys are refused from browsers on the agent operations only;
the hosted-service exemption, uag-eval's license and the chat's templates
(keyed by the current framework, not bootstrap5) as they really are.

Adds what a team needs to run the UAG in its own environment: a full
Enterprise stack and an .env.example, health checks on /status, a reverse
proxy (forwarded headers, unbuffered event streams, timeouts, body sizes),
a Kubernetes Deployment and Service, embedding in an Express server (the
--no-node-snapshot check, mounting under a path, route order, one Form.io
server package), several instances, licensing (seats, offline licenses, the
grace period), and the startup warnings and errors to look for.

Requires @formio/uag 2.0.0-rc.4 or later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@travist
travist merged commit a714871 into main Oct 30, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant