Shared Flow Skills
==================

Skills in this section are **cross-cutting** — they are available to every
agent created by ubFlow. Each ``FLSK_`` links to the ``FLSP_`` it supports
via ``:supports:``.

.. flowskill:: Render a need ID as a linked source reference
   :id: FLSK_UBFLOW_001
   :status: draft
   :tags: ubflow
   :supports: FLSP_UBFLOW_001; FLSP_UBFLOW_002
   :linked_tool: FLTL_UBCODE_MCP

   When referencing a need ID in any output:

   1. Ensure the full ID is available (never abbreviate or shorten it).
   2. Check whether ``get_data_for_single_need`` has already been called for
      this ID during the session. If so, use the cached result.
   3. If not yet fetched, call:
      ``get_data_for_single_need(need_id=<ID>)``
   4. Extract ``origin.path`` (absolute file path) and ``origin.line``
      (1-based integer line number) from the result.
   5. Derive the workspace-relative path::

         rel_path = os.path.relpath(origin["path"], repo_root)

   6. Render the ID as inline code followed by a parenthesised source link::

         `<FULL_ID>` ([source](<rel_path>#L<origin.line>))

      Example: ``\`FLIN_UBFLOW_001\` ([source](docs/shared/flow_instructions.rst#L10))``,
      which renders as: ``FLIN_UBFLOW_001`` (source)

      **Rationale**: VS Code Copilot chat overrides the display text of
      workspace-file Markdown links with the file path, regardless of what
      the author specifies. Keeping the ID as plain inline code and placing
      the clickable link separately guarantees the ID is always readable.

   7. If the MCP call fails or the ``origin`` field is absent, print the
      full ID as inline code without a link. Never silently omit the reference.