netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
107e429fb9015e9f80d1a683786f727a8ea2e561
ai-for-dummies/submitted-skills/Marcos Silva/skills/confluence-page/SKILL.md
T
Marcos Silva 76d83c9cf9 feat: review Gustavo and Marcos submitted skills
2026-09-04 09:11:53 -03:00

7.0 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink