Repository navigation
feat(skills): add formio-uag for agentic forms with the Form.io UAG 2.0 - #113
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdandpackages/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
SKILL.mdtakes a request through PATTERN → FORM → SERVER → APPLICATION → VERIFY, across the UAG's four surfaces:Formio.createChat);@formio/uag-js;uag*form property;@formio/uag-jsin vanilla JS, React and Angular apps;project_set.formio-form-builder's edit lane. Any change touagAnonymousoruagTools, or removinguagAuthoritative, must be named and approved separately at that step.action_createis never used foragentRunTask. Form.io's action catalog does not list that action, soaction_createrejects 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.## Securitysection covering keys, the identity research runs as, the cost of anonymous use, the fact that browser routing is not a security boundary, the sharedJWT_SECRET, and criteria being sent to models as prompts.formio-actionssends "Agent: Run task" to the new skill, andformio-formsends 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.
Not for:handoff.skillListingBudgetFractionorSLASH_COMMAND_TOOL_CHAR_BUDGET).formio-uagputs 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.formio-uagreferences and to the four longest references elsewhere in the library.Tests and docs
packages/skill-tests/src/formio-uag/skill-structure.test.ts.SKILL.mdfiles, andformio-uagis added to the list of skills that must carry a Security section.form_nameandform_data, which are arguments of the UAG's own MCP tools.CLAUDE.md, three example prompts inexamples/agents/, the OpenSpec changeadd-formio-uag-skill, and a minor changeset.Verification
pnpm test: 1,666 skill tests and 1,937 server tests pass.pnpm lintandpnpm formatare clean.Routing eval: eight new prompts were added (six that should route to
formio-uag, two that should not).main)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_KEYon a hosted project stops the UAG loading the project unless the key's endpoint allowlist includes it, andCORSaccepts only a single origin.Not in this PR
/mcp,/authand/.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