intent-identification

name	intent-identification
description	Clarify ambiguous requests and produce a reusable structured intent contract for downstream skills or deterministic executors. Use when the user's goal is not specific enough to execute safely, or when a downstream skill requires a normalized understanding of objective, constraints, and success criteria before acting.

Intent Identification

Overview

Use this skill when execution is premature because the user's intent is still fuzzy.

This skill is intentionally generic. It does not belong to YouTube, product research, coding, writing, or any single domain. Its only job is to turn a vague request into a reusable structured intent contract that other skills can consume.

This skill is appropriate when:

• the request can be interpreted in multiple ways
• the effort difference between interpretations is meaningful
• a downstream executor needs explicit constraints before acting
• you need to separate intent clarification from domain-specific execution

Prerequisites

Before using this skill, confirm that intent clarification is actually needed:

• the user request is still meaningfully ambiguous, underspecified, or risky to route directly
• there is no more specific executor that can already act safely with the current information
• you are prepared to ask only the minimum blocker questions needed for safe handoff

If the request is already specific enough to execute safely, skip this skill and move straight to the downstream executor.

Hard gate

Hard gate

• Do not execute domain-specific actions while using this skill.
• Do not produce hidden execution parameters.
• Do not guess missing intent details just to keep moving.
• If the contract is not ready, return status: NEEDS_CLARIFICATION and keep asking.

Core workflow

1. Understand the current request and context.
2. Ask one clarifying question at a time.
3. Focus on the minimum fields needed to safely route or execute later.
4. When useful, propose 2-3 interpretations or approaches with tradeoffs and recommendation.
5. Once intent is clear enough, summarize it and ask for confirmation.
6. Output a reusable intent_contract_v1.

Questioning rules

• Ask one question per message.
• Prefer multiple-choice when possible.
• Focus on:
  • objective
  • target subject
  • target audience or consumer
  • desired deliverable
  • success criteria
  • constraints
  • must-include and must-exclude terms
• If the user has already been specific enough, do not drag them through unnecessary questions.

Outputs

The output of this skill is always a reusable contract, not a side effect. Return exactly one structured result in one of two states:

• status: READY when downstream execution can proceed safely
• status: NEEDS_CLARIFICATION when blocker questions still remain

The contract should be explicit enough for downstream skills to reuse without hidden assumptions or extra inferred parameters.

Output contract

Output contract

Return one of these two shapes.

Ready for downstream execution

{
  "contractVersion": "intent_contract_v1",
  "status": "READY",
  "intent": {
    "objective": "Find YouTube URLs that represent the target audience's routines and product-adjacent language",
    "targetSubject": "pilates",
    "targetAudience": "young women interested in lifestyle-led pilates identity",
    "deliverable": "a filtered list of long-form YouTube video URLs",
    "successCriteria": "returned videos should be high-signal, long-form, and useful for downstream transcript mining",
    "explorationAngles": [
      "day in the life",
      "vlog",
      "routine"
    ],
    "constraints": {
      "language": "en",
      "minDurationSeconds": 1200,
      "precisionMode": "precision-first",
      "resultLimit": 12
    },
    "mustInclude": [
      "pilates"
    ],
    "mustExclude": [
      "shorts",
      "clips"
    ]
  },
  "openQuestions": []
}

Not ready yet

{
  "contractVersion": "intent_contract_v1",
  "status": "NEEDS_CLARIFICATION",
  "intent": {
    "objective": "Find relevant YouTube content",
    "targetSubject": "pilates",
    "targetAudience": "",
    "deliverable": "YouTube URLs",
    "successCriteria": "",
    "explorationAngles": [],
    "constraints": {},
    "mustInclude": [],
    "mustExclude": []
  },
  "openQuestions": [
    "Which audience should these videos represent?",
    "Do you want daily-life vlogs, routines, podcasts, tutorials, or something else?",
    "What counts as a long-enough video for this task?"
  ]
}

Field definitions

• objective: what the user is trying to accomplish
• targetSubject: the entity, domain, topic, or object of interest
• targetAudience: the intended people, persona, or consumer group
• deliverable: what downstream execution should produce
• successCriteria: how to judge whether the result is good enough
• explorationAngles: optional angles, modalities, or patterns to explore
• constraints: a generic bag of explicit limitations or preferences
• mustInclude: terms or conditions that must appear downstream
• mustExclude: terms or conditions that must not appear downstream
• openQuestions: unresolved blockers preventing safe downstream execution

Genericity rule

This skill must stay domain-agnostic.

• It may prepare intent for a YouTube search skill.
• It may prepare intent for a writing skill.
• It may prepare intent for a research or sourcing skill.
• It must not leak domain-specific output formats into the contract unless the user explicitly needs them.

For example, this skill can output explorationAngles, but it should not output finalQueries for a YouTube search executor.

Behavior summary

• Clarify first.
• Normalize second.
• Execute nothing.
• Hand off a contract, not a guess.

Script

• scripts/validate_intent_contract.js: validates and normalizes intent_contract_v1 JSON for reuse by downstream scripts.