visual-answer

name	visual-answer
description	Answer code/product questions as visual Plan artifacts using repo, bridge, or GitHub context; use for API specs, UI look, schema models, and architecture.
scope	dev
metadata	{"visibility":"exported"}

Visual Answer

/visual-answer turns a specific code or product question into a published Agent-Native Plan artifact. It is for questions that need a visual, inspectable answer rather than a chat paragraph: API contracts, schema/data models, UI states, component behavior, architecture flows, and code evidence.

When To Use

Use this skill when the user asks:

• "what is the API spec for this?"
• "what does this UI look like?"
• "what is the schema model for x?"
• "draw the flow for this code path"
• "show me the current shape of this component/API/data model"

For history questions about what changed or shipped, search merged PR recaps first with search-pr-recaps, then pull a relevant hit into the conversation with show-visual-plan (it renders that plan or recap's blocks inline). Reach for get-visual-plan only when you need the full bundle/MDX to edit, not to display. Use visual-answer when the current codebase, a local bridge, or GitHub source needs to be inspected to produce a new answer.

Workflow

1. Inspect the real source first. Use the host agent's repo tools, the Plan local bridge, or GitHub/source links. Do not invent endpoints, schema fields, UI states, file names, or behavior.
2. Call get-plan-blocks before authoring. Use the live registry, not memory. If the question asks what components are available, call list-plan-components.
3. Pick the evidence blocks:
   • API shape: openapi-spec plus api-endpoint; use before/after only when comparing historical changes from recaps.
   • UI look: wireframe or a columns before/after pair when comparing a recap.
   • Schema/data model: data-model, optionally with diagram.
   • Code evidence: file-tree, tabs, annotated-code, and diff when the answer depends on implementation details.
4. Publish with the Plan visual-answer action. Include the user's question, repoPath/sourceUrl when known, a concise title/brief, and MDX source under mdx.
5. In Agent-Native chat the published answer renders inline automatically — its blocks appear in the conversation. Add a one-line summary of the evidence plus the deep link; do not paste raw MDX or block source as text. (In terminal or external MCP hosts that cannot render the blocks, return the URL.)

Terminal Handoff

When running from a terminal or coding-agent shell, write visual-answer-source.json:

{
  "question": "What is the billing API shape?",
  "title": "Billing API visual answer",
  "brief": "Shows the request and response contract.",
  "repoPath": "owner/repo",
  "sourceUrl": "https://github.com/owner/repo",
  "mdx": {
    "plan.mdx": "---\ntitle: Billing API visual answer\n---\n\n..."
  }
}

Then publish:

agent-native plan visual-answer publish --question "What is the billing API shape?" --source visual-answer-source.json --repo owner/repo

Use --source-url for a GitHub file/PR/commit/issue URL, --prev-plan-id to refresh an existing answer, and --visibility private for owner-only output. The command writes visual-answer-url.txt.

Don't

• Do not use visual-answer for a plain implementation plan; use visual-plan.
• Do not use it for a PR diff recap; use visual-recap.
• Do not skip code inspection and infer from names alone.
• Do not publish screenshots, secrets, credential-looking values, or private source excerpts beyond what the user has asked to visualize.

Related Skills

• visual-plan
• visual-recap
• delegate-to-agent
• context-awareness