generate_skill_assessment
Generate AI-powered skill assessment multiple-choice questions. Supply skill, proficiency level, and work context to obtain structurally validated questions with a signed assessment token.
Instructions
Generate a skill-proficiency assessment (MCQs) for a learner.
You provide a skill, target proficiency, number of questions, and the work item the learner is preparing for. Unfold returns the questions with multiple-choice options, a signed assessment_token, and a proficiency band map. The learner answers in your UI; then call score_skill_assessment with the token and answers.
Questions are AI-generated and validated (structural + semantic) before being returned. The assessment_token is HMAC-signed and tamper-proof; it contains the answer key AND per-question facet labels (since v0.7.0) so scoring is stateless and deterministic, and score returns per-facet aggregation without you doing any client-side joins.
CHAINING:
work_item_context is the strongest grounding signal: questions get anchored to it instead of being generic textbook items. Pass title + description whenever you have them.
The same work_item_context flows through to score_skill_assessment's suggested_goal_seed, then into create_goal. Keep it consistent across the chain.
TYPED ERRORS (branch on error_code):
"models_not_configured" / "provider_unauthorized" / "provider_quota_exceeded" / "provider_unavailable" / "provider_request_invalid": LLM provider issues. Some include settings_url and switch_to_unfold_ai CTA.
"validation_failed": generation produced output the validator rejected after retry budget. Retry with a different request_id, or reduce num_questions.
"idempotency_conflict": same request_id was used with a different request body; pick a new request_id.
Requires the "assessment:generate" scope on your org API key.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| skill | Yes | Skill to assess (e.g. 'Python', 'SQL', 'Project Management') | |
| language | No | ISO language code (default 'en') | |
| request_id | Yes | Client-supplied idempotency key. Same request_id returns the same assessment. | |
| num_questions | Yes | Number of MCQs to generate (3-20) | |
| difficulty_mix | No | Difficulty distribution as {easy, medium, hard} floats summing to 1.0. Defaults to {easy: 0.2, medium: 0.5, hard: 0.3} | |
| band_thresholds | No | Custom proficiency band ranges. Defaults: beginner [0,10], low [11,50], medium [51,85], high [86,100] | |
| work_item_context | Yes | The work item context to anchor question relevance. Flows through scoring into create_goal; keep it consistent across the chain. | |
| target_proficiency | Yes | Proficiency band the learner should reach |