---
name: confluence-page
description: Create or update a Confluence page on BASS from a local storage-format draft, using mcp-atlassian. Use when scaffolding a new page in AVP or BASS, mirroring a doc into a space, or updating an existing page by id or by space+title.
---

# Confluence Page

Draft a page in storage format locally, lint it, then post or update it via
`mcp-atlassian`. The skill never edits a page in place without a draft file on
disk and a pre-flight pass.

Canonical source: [BASS Confluence](https://bass.netcracker.com). When the
skill and a BASS page disagree, BASS wins and this skill gets updated.

## Hard rules

- **Storage format, not wiki markdown.** Confluence Cloud expects the
  `body.storage` representation. Wiki markup only renders correctly when the
  page's renderer is configured for it; do not assume.
- **No secrets, tokens, customer PII, or session cookies** in any body.
  `references/secrets.md` lists the patterns to scrub.
- **Title is unique within the parent** — verify with `confluence_search` or
  `confluence_get_page(spaceKey, title)` before creating.
- **PlantUML goes through the `{plantuml}` macro** at body root, never inside
  an info panel or a code block — see `diagram-plantuml` skill.
- **Attachments go through the attachments API**, not as base64 in the body.
  See `references/attachments.md`.
- **One page per draft file.** Don't stuff multiple pages into one storage file;
  split before posting.

## Workflow: new page

1. Pick a template from `templates/` and copy it to a scratch file under
   `~/Netcracker/Projects/NDO/knowledge/confluence/drafts/<SPACE>/<slug>.xml`
   (`<SPACE>` is the space key, e.g. `AVP`, `BASS`).
2. Decide the parent. Default parent is the space home for top-level pages.
   Use `confluence_search` to find the parent id when nesting.
3. Fill the body. Storage format uses standard XHTML; the only macros that
   survive the round trip are listed in `references/macros.md`.
4. Run `scripts/dry-run-publish.sh <draft>` — it lints the body, runs the
   `unslop` pass, and verifies every `{plantuml}` block parses.
5. `mcp__atlassian.confluence_create_page(spaceKey, title, storageFilePath,
   parentId?)` to post. The MCP tool reads the file directly; never paste the
   body into the call.
6. Capture the new page id in `~/Netcracker/Projects/NDO/knowledge/confluence/_index.md`
   so it appears in the local mirror index.

## Workflow: update existing page

1. Resolve the page id. `confluence_get_page(spaceKey, title)` if you know the
   title, otherwise `confluence_search(cql="title=\"…\"")`.
2. Fetch the current storage body with `confluence_get_page_content(pageId)`
   and save it next to your draft under
   `confluence/drafts/<SPACE>/<slug>.from-server.xml`. This is your safety net.
3. Diff your draft against the server copy. If a section was renamed upstream
   but is still wanted locally, carry the change forward; if it was deleted,
   drop it.
4. Run `scripts/dry-run-publish.sh <draft>`.
5. `mcp__atlassian.confluence_update_page_from_file(pageId, storageFilePath,
   title?, minorEdit=true, versionMessage="…")`. Default `minorEdit` to true;
   only set false for content rewrites.
6. If the diff touched more than the section you set out to change, stop and
   re-pull the page before posting.

## Workflow: mirror a markdown file into Confluence

1. Run the page-reviewer skill first. Mirrors must not introduce slop into a
   governed space.
2. Convert headings from `#`/`## `###` to `h1`/`h2`/`h3`. Strip any leading
   front-matter — the storage body must not contain `---` fences.
3. Strip any path that leaks the local mirror root
   (`/home/masi1023/Netcracker/Projects/NDO/knowledge/...`). Use the public
   BASS URL instead.
4. Convert `[[wikilinks]]` to plain text or proper Confluence links; the wiki
   linker only resolves inside BASS.
5. Convert fenced code blocks to `<ac:structured-macro
   ac:name="code"><ac:parameter ac:name="language">…</ac:parameter><ac:plain-text-body><![CDATA[ … ]]></ac:plain-text-body></ac:structured-macro>`.
6. Run the dry-run script.

## Body format cheatsheet

The MCP server expects a UTF-8 file containing a fragment of storage XHTML.
Common elements:

| You want | Storage format |
|----------|----------------|
| Heading | `<h2>…</h2>` |
| Paragraph | `<p>…</p>` |
| Bold / italic | `<strong>…</strong>` / `<em>…</em>` |
| List | `<ul><li>…</li></ul>` / `<ol><li>…</li></ol>` |
| Table | `<table><tbody><tr><th>…</th><td>…</td></tr></tbody></table>` |
| Info panel | `<ac:structured-macro ac:name="info"><ac:rich-text-body>…</ac:rich-text-body></ac:structured-macro>` |
| Code block | `<ac:structured-macro ac:name="code" ac:name="language">…</ac:structured-macro>` |
| PlantUML | `<ac:structured-macro ac:name="plantuml"><ac:plain-text-body><![CDATA[@startuml … @enduml]]></ac:plain-text-body></ac:structured-macro>` |
| Link | `<a href="https://…">label</a>` |
| Page link | `<ac:link><ri:page ri:content-title="…"/></ac:link>` |

Full macro catalog: [references/macros.md](references/macros.md).

## Picking the parent page

- Top-level page under the space home: omit `parentId` (MCP defaults to the
  space home) or pass the space home id explicitly.
- Nested under a hub or domain page: find the parent id with
  `confluence_search(cql="space=AVP AND title~\"Hub\"")` and pick by hand.
- Moving a page later is a separate API call; do not "fix" the parent by
  deleting and recreating — that loses history, watchers, and reactions.

## Picking the space

| Content kind | Space |
|--------------|-------|
| NDO product docs | `AVP` |
| Internal team / governance / how-to | `BASS` |
| Customer-facing release notes | check with the page owner |
| Personal scratch | do **not** post to BASS / AVP; keep in `~/Netcracker/Projects/NDO/knowledge/` |

If unsure, ask before posting.

## MCP availability

`mcp-atlassian` is listed in the
[BASS Cursor MCPs approval page](https://bass.netcracker.com/display/~seby0316/Cursor+-+MCPs+approval+status)
as *Not approved* by default — that page was last synced 2026-06-11; check the
current status before relying on it. The skill assumes the MCP server is wired
into the active Claude / Cursor client. Run `scripts/check-mcp-atlassian.sh`
to detect it and get an install hint if missing.

## Safety

- **Read-only on `~/Netcracker/Projects/NDO/knowledge/confluence/<SPACE>/`.**
  Mirrors are snapshots. Never edit them in place — re-pull instead.
- **Drafts live under `confluence/drafts/`** and are the only files this
  skill writes to by default.
- **No page deletion** through this skill. Deletes are not undoable and lose
  history. If a page must go, ask in the page's comments first.
- **Never paste body content into the API call** — pass a file path so the
  body stays reviewable in git.

## Related

| Skill | Role |
|-------|------|
| `page-reviewer` | Mandatory pre-post gate; runs before any create/update |
| `unslop` | Removes AI phrasing so the page reads as Netcracker voice |
| `diagram-plantuml` | Owns the `{plantuml}` macro and the diagram macro catalog |
| `confluence-to-slides` (existing) | Pulls a finished page into a slide deck |