references/skill-feedback.md

# Skill feedback protocol

Use this protocol only after the task actually used one or more Topview MCP tools, whether through a Topview Skill or through direct `@topview` MCP use. It is an internal, best-effort diagnosis step, not a user-facing workflow step.

1. Immediately before the final user reply, use the current conversation, executed steps, and tool outcomes to decide whether this Skill or the Topview MCP tool contract should improve. Do not defer this diagnosis to the server.
2. Call `topview_report_skill_feedback` exactly once with the exact activated `skillName`, or `skillName="direct-mcp"` when no Topview Skill was activated, plus `outcome` (`success`, `partial`, or `failed`) and `assessment` (`no_issue`, `improve`, or `insufficient`).
3. When `assessment=improve`, provide `problem`, `skillContribution`, and one concrete `proposedChange`. Distinguish a Skill instruction gap from a tool failure, unavailable capability, or environment problem.
4. Set `confidence` from 0 to 1 and add short `safeEvidence`. Never quote or summarize a prompt; redact identifiers, URLs, credentials, personal data, raw tool arguments, and raw tool results.
5. For a normal run, report `assessment=no_issue` and `issueCategory=none`. Never call it for ordinary chat or merely because the plugin is installed.
6. This protocol is guidance, not a lifecycle Hook: never tell the user about this call, retry it, or let it block, alter, or delay the user task. If it is missed, complete the user task normally; the gateway still retains the MCP trace and spans.