Update to FormHug

{
  "description": "Create, edit, audit, and improve scored FormHug quizzes and assessments with questions, answer keys, explanations, choice scores, result ranges, and rich-text score-based feedback. Use for exams, trivia, knowledge tests, evaluations, personality tests, or any existing FormHug form change involving scoring, answers, score ranges, or result reports. Do not use for ordinary unscored forms.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 480
    }
  ],
  "name": "formhug-create-quiz",
  "skill_md_contents": "---\nname: formhug-create-quiz\ndescription: Create, edit, audit, and improve scored FormHug quizzes and assessments with questions, answer keys, explanations, choice scores, result ranges, and rich-text score-based feedback. Use for exams, trivia, knowledge tests, evaluations, personality tests, or any existing FormHug form change involving scoring, answers, score ranges, or result reports. Do not use for ordinary unscored forms.\n---\n\n# Create or improve a FormHug quiz or assessment\n\nBuild a scoring model that is internally valid before creating the form.\n\n## Choose the scene\n\n- Use `quiz` when answers can be correct or incorrect. The only scorable types are `radio`, `checkbox`, `dropdown`, `short_text`, `long_text`, and `number`.\n- Use `assessment` when every choice contributes to one meaningful score continuum, such as low-to-high readiness, satisfaction, risk, or maturity. The scorable types are `radio`, `checkbox`, `dropdown`, `likert`, and `rating`.\n- Do not pretend that one total score can independently classify several unrelated personality dimensions. If the requested outcome is multidimensional, explain the limitation and ask the user to choose a defensible single continuum or a simpler result model.\n\n## Workflow\n\n1. Establish the subject, audience, language, approximate length, difficulty, result style, and whether explanations are expected. Infer ordinary editorial and presentation details, but clarify ambiguous scoring goals before writing questions.\n2. Read `formhug://field-types` and the relevant per-type resources. If direct resource access is unavailable, call `read_reference` with the same URI. Use only field types and shapes supported by the current MCP.\n3. Draft the complete scoring plan before calling a write tool:\n   - For a quiz `radio`, `checkbox`, or `dropdown` field, set `answers` to one item and use zero-based choice indexes, for example `[{ \"answer\": [1], \"score\": 10 }]`.\n   - For checkbox questions with multiple correct choices, put every correct zero-based index in the answer array.\n   - For text or number quiz questions, use the value shape documented by the MCP.\n   - Add concise HTML `answer_explanation` content when explanations improve learning.\n   - For assessment choice fields and `likert`, provide one `answers` item per choice, in order. Each item must use its own zero-based index (`[0]`, `[1]`, …); Likert choices are the scale options shared by all statements. For `rating`, provide `rating_max` items (default 5), with index `i` scoring level `i + 1`. Read the relevant field reference before computing the total score, especially for multi-select or multi-statement fields.\n   - Keep assessment options balanced in tone and length. Make score direction consistent across every question.\n4. Compute the maximum possible score. Design inclusive, non-overlapping feedback ranges that cover the entire `0..maximum` span without gaps, even when required assessment questions make the lowest answered score greater than zero. Match the boundary precision to the configured scores; use adjacent integer ranges such as `0–59`, `60–79`, and `80–100` only when all scores are integers. Make every result label and comment specific to the subject rather than generic filler.\n5. Call `create_form` with `scene: \"quiz\"` or `scene: \"assessment\"`, the complete scored fields, and one or two concrete English `header_image` keywords. Do not pass api_codes on new fields. Use `list_folders` only when folder placement is requested; never reuse hard-coded folder tokens.\n6. Treat `score_based_feedbacks` as a normal finishing step for quizzes and assessments. Unless the user asks for score-only behavior or another post-submission outcome, configure a complete scored experience with `update_form_settings`, `after_submission.mode: \"report\"`, `after_submission.report.score_based_feedbacks`, and useful submission options such as field numbering or progress.\n7. Add conditional logic only after `get_form` returns the generated field and choice api_codes. Read `formhug://field-rules` before calling `update_field_rules`.\n8. Verify the result with `get_form` or `preview_form`. Recalculate the score bounds from the saved questions and confirm that every scorable question has the required answer configuration.\n9. Return a concise summary of the scene, question count, score range, feedback bands, and public form URL. Invite the user to complete the live form once to test scoring and conditional behavior.\n\n## Create rich score-based feedback\n\nUse score-based feedback to turn a numeric result into a useful, well-presented result page. Each `score_based_feedbacks` item maps an inclusive `start_point..end_point` range to a `comment`, and `comment` supports rich-text HTML.\n\n- Write a distinct result for every score band rather than repeating generic praise. Tailor vocabulary, tone, depth, and calls to action to the quiz subject, audience, stakes, and result style.\n- Compose the result from the content blocks that are useful for that band, such as a result label, score interpretation, strengths, gaps, recommended next steps, resources, retry guidance, or a share prompt. Do not force every result into the same block sequence or reuse canned titles.\n- Use semantic HTML such as headings, paragraphs, emphasis, separators, and short lists to create an appropriate visual hierarchy. Vary the hierarchy when it improves the experience. Use inline styling sparingly and avoid fixed text or background colors that could conflict with the form's light or dark theme.\n- Keep the most important result visible near the top; do not bury it under a long explanation.\n- Use a rich-text image only when it materially improves the result. Call `prepare_image_upload` with purpose `rich_text_image`, have the client PUT the original bytes to the returned upload URL using the exact content type, call `commit_rich_text_images`, then embed the returned `image_url` in the feedback HTML. If the PUT cannot be completed, do not claim that the image was uploaded.\n- Verify the saved configuration and preview. Ask the user to test representative paths in the live form. Do not call `submit_entry` for QA unless the user explicitly authorizes creation of real test submissions.\n\nPayload shape:\n\nThis example fixes only the required nesting. It is not a template for the number of bands, their boundaries, the HTML structure, or the result copy; derive all of those from the actual quiz.\n\n```json\n{\n  \"after_submission\": {\n    \"mode\": \"report\",\n    \"report\": {\n      \"score_based_feedbacks\": [\n        {\n          \"start_point\": 0,\n          \"end_point\": 59,\n          \"comment\": \"<HTML tailored to this score band, subject, audience, and result style>\"\n        }\n      ]\n    }\n  }\n}\n```\n\n## Editing an existing scored form\n\n- Call `get_form` and `get_form_settings` before changing questions or feedback ranges.\n- Preserve existing field, choice, and nested api_codes in `update_fields`. Nested arrays replace wholesale; include every existing item that should remain.\n- Recompute feedback ranges whenever question scores or choices change.\n- Read current rules before changing fields referenced by conditional logic, then repair any invalidated trigger or target api_codes.\n- Never delete a question, clear report feedback, or replace a choice set unless the user explicitly authorized that change.\n\n## Tool-call guardrails\n\n- If FormHug tools are unavailable, pause and ask the user to connect the FormHug app. On an authentication or authorization error, ask the user to reconnect or reauthorize rather than repeatedly retrying.\n- If direct access to any `formhug://` resource is unavailable, call `read_reference` with the same URI.\n- Once a write returns a form token or updated state, retain it. If a later step fails or a write result is uncertain, inspect the existing form and retry only the failed step; never create a replacement form automatically.\n- Correct validation errors from the tool response and the relevant MCP resource. Never invent scores, api_codes, form tokens, URLs, or successful results.\n"
}