---
name: confluence-librarian
description: Publish and update prepared pages and document artifacts in Confluence without losing structure or traceability. Use whenever a user asks to publish, create, update, translate, or synchronize Markdown, HTML, or another readable document to Confluence, including hierarchical child pages under a parent catalog. Require explicit confirmation before irreversible publication and preserve headings, tables, links, statuses, IDs, and intentional gaps.
---

# Confluence Librarian

Move a prepared page or document into Confluence while preserving its meaning,
structure, traceability, and lifecycle state. This skill owns publication
mechanics; the calling skill or user owns the source content and domain rules.

## When to use this skill

Use this skill when:

- a user asks to publish or update a prepared page or document in Confluence;
- another skill has completed any artifact, such as a PRD, DR/SRS, RFC, runbook,
  meeting note, guide, decision record, or operational page, and the user
  confirms publication;
- a user asks to translate or synchronize an existing document into a
  Confluence page;

Do not invent missing domain decisions. Do not rewrite the source content's
meaning merely to make publication easier.

## Input contract

Accept the following from the calling skill or user:

| Input            | Required    | Description                                                      |
| ---------------- | ----------- | ---------------------------------------------------------------- |
| Source document  | Yes         | Path or content of the prepared page/document artifact           |
| Operation        | Yes         | Create a new page or update an existing page                     |
| Title            | Yes         | Page title, inferred only when unambiguous                       |
| Language         | Yes         | Visible page language; preserve machine-facing IDs               |
| Space           | Yes         | Target Confluence space, inferred only when safe                 |
| Parent page     | When needed | Parent page for hierarchical content such as a Use Case          |
| Existing page ID | For updates | Page ID or URL when updating an existing page                    |

If the source document is not available, ask the user to provide it. Do not
claim to have published content that was not read.

## Workflow

1. **Confirm publication.** Before creating or updating a page, obtain an
   explicit affirmative answer. If the user only asks to write a document,
   stop after the local artifact and do not start publication questions.
2. **Resolve destination.** Ask for the target space, parent page when the
   document belongs in an existing page hierarchy, title, language, and
   operation when they cannot be inferred safely. For updates, resolve the
   existing page ID and fetch the current page before replacing it.
3. **Read and validate the source.** Preserve the complete heading hierarchy,
   tables, lists, links, code blocks, stable HTML-comment IDs, table IDs,
   statuses, `N/A` reasons, open questions, and source references. Identify
   unsupported constructs before writing. Treat markdown soft-wraps as
   presentation-only formatting: when the source is wrapped for readability,
   collapse soft-wrapped lines before comparing or publishing content so they do
   not become accidental paragraphs, bullets, or content changes.
4. **Prepare the representation.** Convert the source into the format
   supported by the authenticated Confluence integration. Translate only
   human-facing prose, headings, labels, and values when requested. Keep
   stable IDs, machine-facing status values, entity IDs, URLs, API operation
   names, and code unchanged. Ignore markdown soft-wraps in the source; do not
   reproduce them as hard line breaks or blank paragraphs in Confluence.
5. **Show the irreversible action.** State the operation, page title, space,
   parent, language, and source path before creating or updating the page.
6. **Publish through the authenticated integration.** Use the available
   Confluence tool or API. For updates, preserve the current page's relevant
   metadata and replace only the requested content.
7. **Verify the result.** Retrieve or inspect the returned page identifier and
   URL. Confirm that the operation succeeded and report the page URL. If the
   integration reports an error, surface it rather than returning a
   success-shaped response.
8. **Preserve lifecycle state.** Publication alone must not change a source
   document's status such as `draft` or `review`. Change lifecycle state only
   when the user explicitly requests it and the domain skill permits it.
## Confirmation protocol

Use this question when a prepared document is ready but publication has not
been confirmed:

> Do you want me to create or update the Confluence page for this document?

After an affirmative answer, ask only for destination details that are not
already known. Do not ask for language, space, or parent before publication
confirmation unless the user explicitly asks to plan the publication.

Before the write, summarize:

```text
Operation: create/update
Title: <page title>
Space: <space>
Parent: <parent or none>
Language: <language>
Source: <document path or artifact>
```

## Structure and traceability rules

- Preserve every stable ID exactly. IDs are never translated or renumbered.
- Preserve every source section, including conditional sections marked
  `N/A — <reason>`.
- Preserve links to PRDs, RFCs, ADRs, Figma, Service Blueprints, APIs, events,
  data contracts, reviews, dashboards, and Jira.
- Preserve visible status values and do not infer approval from publication.
- Keep detailed source content in the page; do not replace it with a summary
  unless the user explicitly requests a summary.
- Treat the Confluence page title as separate from the body. When the source
  starts with a Markdown H1 whose text exactly matches the page title, omit
  that H1 from the published body to avoid displaying the title twice. Keep
  later H1 headings and a leading H1 with different text unchanged.
- For updates, fetch the existing page first when the operation could overwrite
  comments, local IDs, links, or page metadata.
- Use the authenticated integration's native document representation when
  available. Never store credentials in the skill or generated document.
- Ignore markdown soft-wraps in the source. Wrapped lines are formatting-only
  and must be normalized before import; they must not become new paragraphs,
  bullets, or hard breaks in Confluence.
- Markdown front matter is not native Confluence metadata. When publishing a
  Markdown document, render its front-matter values as a Confluence metadata
  table, and verify that stable IDs and lifecycle status remain visible after
  conversion.

## Translation rules

When a language is requested:

- translate human-facing text, headings, table labels, and explanatory prose;
- preserve stable English IDs, code, endpoint names, URLs, status enum values,
  metric identifiers, and document references;
- keep the hierarchy and field order unchanged;
- do not translate content that the source marks as machine-facing.

## Failure handling

- If authentication or permissions are unavailable, report the concrete
  failure and return publication-ready content instead of claiming success.
- If the destination is ambiguous, ask for the missing destination detail.
- If the source cannot be parsed or contains unsupported structure, identify the
  affected section and ask how to proceed; do not silently flatten it.
- If an update target cannot be resolved, do not create a duplicate page as a
  fallback.