ai-for-dummies/public/submitted-skills/Marcos Silva/skills/confluence-page/SKILL.md

name, description

name	description
confluence-page	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. 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 #/## ###toh1/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.

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 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