Marcos Silva
148 lines
7.0 KiB
Markdown
148 lines
7.0 KiB
Markdown
---
|
|
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 |
|