Issue and comment Markdown

Use this skill when generating or changing Markdown published to issues, comments, or reviews, especially in actions/setup/js/. Build a Report tree first; render only the complete document. Do not assemble Markdown using interpolation, concatenation, body +=, or arrays of Markdown strings joined with newlines. Parsing an assembled string afterward is not a tree-first refactor.

Find publication paths

Search production .cjs files for issues.create, issues.update, createComment, updateComment, createReview, createReplyForReviewComment, and GraphQL body variables. Trace each body back through shared helpers, fallback comments, retries, staged previews, and append/prepend/replace-island updates. Exclude test fixtures, HTTP payload assembly, and step-summary-only output. Jira ADF text is not Markdown: preserve its literal entities, Unicode, and paragraphs instead of routing it through the Markdown parser or renderer.

Use the existing tree

actions/setup/js/report_ast.cjs defines Report, ReportBlock, and ReportInline. Use JSDoc annotations so npm run typecheck verifies node kinds:

/** @type {import("./report_ast.cjs").Report} */
const report = {
  type: "report",
  title: "Workflow result",
  children: [
    {
      type: "paragraph",
      agentTainted: false,
      children: [
        { type: "text", value: "Created related issue: ", agentTainted: false },
        { type: "issue_reference", number: String(issue.number), agentTainted: false },
      ],
    },
    { type: "code_block", language: "text", value: diagnostic, agentTainted: true },
  ],
};

Use heading, paragraph, list, table, details, quote, alert, separator, code_block, and typed inline nodes instead of Markdown punctuation. GitHub [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] map to alert nodes with the matching kind; the renderer emits their markers. Keep alerts separate rather than nesting them inside another alert, which GitHub does not support. Preserve supported <sub> formatting in details summaries. Use xml_marker, json_marker, expiration, and closing_reference for machine metadata and closing links. Preserve xml_marker.compact for identifiers whose exact spelling is used by cleanup. Use review_marker for the durable, URI-encoded review caller reference; keep the authoritative marker last. Dynamic labels, paths, errors, and identifiers belong in text/code nodes; link destinations belong in link.url.

Import existing agent/user Markdown with parseReportMarkdown, specifying agentTainted: true, the correct allowedMentions, and the existing heading and metadata policy. Parse configured templates before scalar substitution using context; use typed inline/block slots for inserted nodes. Never interpolate untrusted values into a template before parsing it. A literal code fence in imported content must not swallow attribution or adjacent generated blocks.

For managed comment memory, set code_block.language to gh-aw-comment-memory:<id> and fenceLength: 6; rendering lengthens the fence past embedded backticks. Do not construct or slice fences by hand.

Compose shared attribution

Use the typed variants instead of rendering a helper and reparsing its output:

Keep custom templates and their scalar context separate until composition. Headers and footers may jointly open/close <details>; use buildIssueBodyReport to parse these wrappers together around body slots. Allocate unique slot names against both source text and previously allocated slots, and reject wrappers that swallow slots inside code fences. Internal framework notes carried between handlers use non-JSON-forgeable Symbols such as COMMENT_PREAMBLE and ISSUE_BODY_SUFFIX, never agent-settable flags.

Preserve publication contracts

Framework-authored nodes use agentTainted: false; agent-owned descendants retain their taint even inside framework wrappers. Keep required footer diagnostics, metadata, and policy text protected during size fitting. Do not mark an entire agent body trusted to keep it from being shortened.

For attributed safe-output issues and comments, use buildIssueBodyReport in issue_body.cjs; it accepts Markdown or typed body blocks and retains configured wrappers, attribution, expiration, and execution provenance. Comment callers set the appropriate itemType and workflowIdMarker: false. Pass the original workflow runUrl when the target repository differs from the execution repository. Fallback issues must import the original agent body and compose recovery nodes, not reparse an already assembled or rendered PR/discussion description.

For other issue producers, pass a typed report to renderIssueParameters/createReportIssue in issue_report.cjs, preserving the existing authentication and retry boundary. buildIssueReport accepts typed blocks as well as imported Markdown. For comments, render the complete tree with renderSizedReport from report_size.cjs and pass its body to the existing API. Do not render fragments and concatenate or reparse them. Keep one logical render boundary, including metadata and trusted footers in its size budget. renderSizedReport trims trailing whitespace automatically and measures the publication body against the exact maxLength. Do not trim its result or reserve an extra character for a terminal newline. Low-level renderReport retains its terminal newline for Markdown serialization. Never truncate rendered Markdown or trusted policy text to fit.

Validate the migration

Preserve footer on/off behavior, marker identity and order, mention/link limits, expiration, cross-repository attribution, structured state recovery, managed memory extraction, review fallbacks, and append/prepend/island semantics. Assert tree shape as well as rendered output. Cover hostile backticks and HTML delimiters, Unicode, escaped table cells, and the exact publication size limit. Update formatting expectations only for intentional canonical rendering, not to hide lost content or metadata.

Run the matching Vitest suites from actions/setup/js, npm run typecheck, and the repository JavaScript formatting/lint gates. Follow the developer skill for final repository validation and publication.