Claude Confluence Skill: 10 Docs Workflows (2026)
Ten real documentation workflows on the Confluence skill for Claude — meeting notes to pages, wiki Q&A with CQL citations, stale-doc audits, ADRs, release notes, runbook patches, comment triage, label cleanup, space maps, and onboarding packs — each as one prompt with the exact output it produces.
Already know what skills are? Skip to the cookbook. First time? Read the explainer then come back. Need the install? It’s on the /skills/confluence page.
On this page · 18 sections▾
- What this skill does
- The cookbook
- Install + README
- 01 · Turn raw meeting notes into a polished Confluence page
- 02 · Ask your wiki a question and get a cited answer
- 03 · Audit a space for stale documentation
- 04 · File an Architecture Decision Record in the right place
- 05 · Draft release notes from git history into Confluence
- 06 · Keep a runbook current without rewriting it
- 07 · Triage every open comment on a doc before review
- 08 · Fix a label taxonomy that grew without adult supervision
- 09 · Generate a living index page for a space
- 10 · Compile a new-hire onboarding pack from three spaces
- Skill vs MCP server
- Gotchas
- Pairs well with
- FAQ
- Sources
What this skill actually does
Sixty seconds of context before the cookbook — what the confluence skill is, what Claude can do once it loads, and the one thing it deliberately refuses to handle.
What this skill actually does
“Use Atlassian MCP server to interact with Confluence (pages, spaces, search, comments).”
— disusered, the skill author · /skills/confluence
What Claude returns
The skill is a reference layer over the Atlassian MCP server (@xuandev/atlassian-mcp), which exposes 13 Confluence tools: list spaces, create/get/update/delete pages, list child pages, get ancestors, CQL search, create/list comments, add/remove/list labels, and user search. Claude reads credentials from ~/.atlassian-mcp.json (domain, email, apiToken), writes page bodies in Confluence storage format (XHTML), and increments version numbers on updates so page history survives.
What it does NOT do
It does not touch Jira — the skill explicitly defers issues, JQL, and sprints to Atlassian's acli or a Jira-specific skill.
How you trigger it
create a Confluence page from these meeting notessearch Confluence for our deployment runbookupdate the API docs page in the ENG spaceCost when idle
~60 tokens at idle (name + description in the system prompt). The full tool reference loads only when a Confluence task triggers it.
The interesting part: this skill is documentation for an MCP server. The Atlassian MCP server gives Claude 13 Confluence tools; the skill gives Claude the judgment to use them — that page bodies are storage format (XHTML with <ac:structured-macro> elements, not Markdown), that updates need the current version number first, that CQL is the search language and what its operators look like. Tools without a playbook produce trial-and-error; this pairing is what makes Confluence automation reliable instead of lucky.
One phrasing note, because the search queries show people use both: this is a Confluence agent skill in the portable SKILL.md format — the same file installs into Claude Code, Codex, Copilot, or Antigravity from the panel below. Nothing in the cookbook is Claude-exclusive; the reference travels with whatever agent loads it.
The cookbook
Each entry below is a workflow you could run today against a real Confluence Cloud site. They go in the order I’d teach them: publish first (the meeting-notes page everyone needs), then read (CQL search and audits), then the maintenance loops — runbook patches, comment triage, label hygiene — that keep a wiki alive. Every entry pairs with one or two skills or MCP servers from mcp.directory; for the wider landscape, see the best knowledge-base MCP servers.
The leverage point across all ten is CQL — Confluence Query Language, the SQL-ish search syntax Atlassian documents for Cloud. Fields like space, title, label, lastmodified, and contributor combine with operators (~ for contains, =, ranges) and date functions like now("-180d"). Every read-side recipe here is one good CQL query plus Claude’s synthesis on top. Learn five fields and the wiki stops being a place where pages go to disappear.
Install + README
If the skill isn’t on your machine yet, here’s the one-liner — the panel covers Claude Code, Codex, Copilot, and Antigravity. Two real setup steps after install: create an Atlassian API token at id.atlassian.com and write ~/.atlassian-mcp.json with your domain, email, and token (then chmod 600 it).
One-line install · by disusered
Open skill pageInstall
mkdir -p .claude/skills/confluence && curl -L -o skill.zip "https://mcp.directory/api/skills/download/417" && unzip -o skill.zip -d .claude/skills/confluence && rm skill.zipInstalls to .claude/skills/confluence
The config file the skill expects, verbatim from its README:
// ~/.atlassian-mcp.json (chmod 600)
{
"domain": "your-domain.atlassian.net",
"email": "[email protected]",
"apiToken": "your-api-token-here"
}The same credentials also work as environment variables (ATLASSIAN_DOMAIN, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN) or CLI flags if you’d rather not keep a file around — the MCP server checks flags first, then env, then the file. The README below is the skill’s full reference, collapsed so you can skim past it.
Turn raw meeting notes into a polished Confluence page
Paste the messy transcript, get a structured page in the right space with decisions, owners, and action items separated. The skill handles the storage-format conversion you'd otherwise fight by hand.
ForAnyone who runs meetings and owes the team a write-up before lunch.
The prompt
Use the confluence skill. Here are my raw notes from today's platform sync: [paste notes]. Create a page in the ENG space titled "Platform Sync — 2026-06-12" under the parent page "Team Syncs". Structure it as: Attendees, Decisions (one line each, bolded), Action items (a table with Owner / Item / Due), and Open questions. Convert everything to Confluence storage format yourself — don't paste raw Markdown. Give me the page URL when done.What slides.md looks like
<h2>Decisions</h2>
<ul>
<li><strong>Adopt pgbouncer in transaction mode</strong>
— rollout next sprint</li>
</ul>
<h2>Action items</h2>
<table><tbody>
<tr><th>Owner</th><th>Item</th><th>Due</th></tr>
<tr><td>Priya</td><td>Draft pgbouncer config</td>
<td>2026-06-19</td></tr>
</tbody></table>One-line tweak
Add "and label the page meeting-notes" — one label now makes use case 3's audit query work later.
Ask your wiki a question and get a cited answer
Knowledge-base Q&A against your real Confluence, not Claude's training data. A CQL search finds candidate pages, Claude reads them, and the answer cites page titles and links.
ForEngineers whose question starts with 'I know we documented this somewhere...'
The prompt
Use the confluence skill. Question: what is our process for rotating production database credentials? Search Confluence with CQL — try `type=page and text ~ "credential rotation"` and a space-scoped variant for the INFRA space. Read the top matches and answer from page content only. Cite each claim with the page title and link. If two pages disagree, say which was modified more recently and flag the conflict.What slides.md looks like
CQL: type=page and space=INFRA
and text ~ "credential rotation"
3 results:
1. "Runbook: DB credential rotation" (modified 2026-04-02)
2. "Security review Q1" (modified 2026-01-15)
Answer: Rotation is quarterly via Vault's database
secrets engine; the runbook owns the canonical steps.
Conflict: "Security review Q1" still says monthly —
the runbook is newer. Flagging for cleanup.One-line tweak
End with "post the conflict as a comment on the older page" — the skill's comment tool turns the finding into a fix request.
Audit a space for stale documentation
One CQL query surfaces every page nobody has touched in six months. Claude groups them by subtree, guesses which are dead versus dormant, and drafts the cleanup plan.
ForThe person who inherited a 400-page space and a vague mandate to 'clean it up'.
The prompt
Use the confluence skill. Audit the DOCS space for staleness. Run a CQL search like `space = DOCS and type = page and lastmodified < now("-180d")` and list every hit with title, last-modified date, and creator. Then group the results by parent page (use the ancestors tool) and propose one of three actions per group: archive, update, or keep-as-is with a reason. Output a table I can paste into a cleanup ticket. Don't delete anything.What slides.md looks like
CQL: space = DOCS and type = page
and lastmodified < now("-180d")
→ 37 pages
| Subtree | Pages | Proposal |
|--------------------|-------|----------|
| /Legacy API v1 | 12 | archive — v1 sunset 2025 |
| /Onboarding | 6 | update — links 404 |
| /Architecture/ADRs | 9 | keep — ADRs are immutable|One-line tweak
Swap the date math for `contributor = currentUser()` to audit only the pages you personally own.
File an Architecture Decision Record in the right place
ADRs only work when they live in one predictable tree with one predictable format. The skill creates the page under your ADR parent, numbered correctly, in the house template.
ForTeams that agreed to write ADRs and stopped after ADR-0003.
The prompt
Use the confluence skill. We decided today to move session storage from Redis to Postgres (reason: one fewer stateful service; accepted trade-off: ~2ms added latency at p99). List the child pages of "Architecture Decision Records" in the ENG space to find the next ADR number, then create "ADR-NNNN: Move session storage to Postgres" as a child page. Sections: Status (Accepted), Context, Decision, Consequences. Keep it under 300 words — ADRs are records, not essays.What slides.md looks like
Children of "Architecture Decision Records":
ADR-0007: Adopt trunk-based development
ADR-0008: Standardize on OpenTelemetry
→ next number: ADR-0009
Created: "ADR-0009: Move session storage to Postgres"
parent: Architecture Decision Records (ENG)
status: Accepted · 287 wordsOne-line tweak
Add "label it adr and decision-2026" so the ADR index in use case 9 can build itself from a label query.
Draft release notes from git history into Confluence
Claude reads the commit log locally, writes human release notes, and publishes them as a child page of your release-notes tree — one prompt from git log to shipped page.
ForWhoever drew the short straw on release communications this sprint.
The prompt
Use the confluence skill. Run `git log v2.40.0..HEAD --oneline --no-merges` in this repo first. Turn the commits into release notes for v2.41.0 with three sections: New, Improved, Fixed — written for users, not engineers (no commit hashes, no internal ticket IDs). Then create the page "Release notes — v2.41.0" as a child of "Release Notes" in the PRODUCT space. Show me the draft before you publish it.What slides.md looks like
$ git log v2.40.0..HEAD --oneline --no-merges
a41f2c9 feat: bulk export API for workspaces
8d03e11 fix: webhook retries dropped on 429
...
## New
- Export entire workspaces in one API call.
## Fixed
- Webhooks now retry correctly when rate-limited.
→ page created under PRODUCT / Release NotesOne-line tweak
Point it at your CHANGELOG.md instead of git log when commit messages aren't fit for public consumption.
Keep a runbook current without rewriting it
Surgical updates to an existing page: fetch it, patch the two sections that changed, push the new version. The skill handles Confluence's version-number dance so history stays intact.
ForOn-call engineers who fixed the runbook's gap at 3 a.m. and want it captured by 9.
The prompt
Use the confluence skill. Get the page "Runbook: payment-service incidents" from the INFRA space. Two things changed: the escalation contact is now the #payments-oncall Slack channel (not a person), and step 4 should mention that the service needs a manual cache flush after restart (`redis-cli -n 2 FLUSHDB`). Update only those sections, keep everything else byte-identical, and increment the version with the comment "post-incident update 2026-06-12". Show me a before/after diff of the changed sections first.What slides.md looks like
Fetched page id 84213792, version 17
- Escalate to: Dana K. (payments lead)
+ Escalate to: #payments-oncall (Slack)
4. Restart the service via deploy pipeline
+ then flush the request cache:
+ redis-cli -n 2 FLUSHDB
→ updated to version 18 ("post-incident update")One-line tweak
Chain it: "also add a comment tagging the page owner" so the change gets human review without blocking on it.
Triage every open comment on a doc before review
A heavily-commented spec is a to-do list in disguise. Claude lists all comments and replies, clusters them into themes, and tells you which three actually block sign-off.
ForSpec authors staring at 23 unresolved comments the night before the review meeting.
The prompt
Use the confluence skill. List all comments (including replies) on the page "RFC: multi-region failover" in the ENG space. Cluster them into themes, and for each theme tell me: how many comments, who raised them, and whether it's blocking (questions the design) or non-blocking (wording, typos, scope-for-later). Give me the three comments I must resolve before tomorrow's review, with the commenter's exact words quoted.What slides.md looks like
23 comments → 4 themes
1. Failover RTO claims (5 comments) — BLOCKING
"where does the 30s number come from?" — mwhitman
2. Cost of standby region (4) — BLOCKING
3. Wording/typos (9) — non-blocking
4. Out-of-scope asks (5) — defer, reply with link
Resolve first: #1, #2, and amara's question on
DNS TTLs (buried in a reply thread, easy to miss).One-line tweak
Add "draft a reply to each blocking comment for my approval" — the skill can post them once you've edited.
Fix a label taxonomy that grew without adult supervision
Labels make CQL useful — until you have runbook, run-book, and runbooks. Claude inventories labels across a space, proposes a canonical set, and applies the merge page by page.
ForWhoever decided labels were the answer and now faces 60 near-duplicates.
The prompt
Use the confluence skill. In the INFRA space, search for pages labeled with any of: runbook, run-book, runbooks, playbook. List each page with its current labels. Propose a canonical label (runbook) and show me the migration plan: which label to add and which to remove per page. After I approve, apply it — add the canonical label and remove the variants. Don't touch any other labels on those pages.What slides.md looks like
Label inventory (INFRA):
runbook: 14 pages run-book: 3
runbooks: 5 playbook: 7
Plan: canonical = "runbook"
19 pages: +runbook, remove variant
"playbook" pages: 4 are runbooks, 3 are
process docs → only relabel the 4
Applied: 23 pages updated, 0 other labels touchedOne-line tweak
Run the same prompt with team names instead of doc types — owner labels rot even faster than topic labels.
Generate a living index page for a space
Spaces outgrow their sidebar. Claude walks the page tree, groups content by subtree and label, and writes a curated index page with one-line descriptions — the map the space never had.
ForSpace admins tired of answering 'where is the page about X' in DMs.
The prompt
Use the confluence skill. Build an index for the ENG space. Walk the page tree: list the children of the space homepage, then each subtree one level down. For each section, write a one-line description of what lives there (read a page or two if the title is ambiguous). Create or update a page titled "ENG space map" at the top level: a table of Section / What's in it / Start here (link to the best entry page). Note any orphaned pages that have no parent.What slides.md looks like
Page tree (ENG): 6 top-level sections, 142 pages
| Section | What's in it | Start here |
|--------------|-----------------------|------------|
| Architecture | ADRs + system diagrams| ADR index |
| Runbooks | 14 incident runbooks | On-call 101|
| Team Syncs | meeting notes archive | (latest) |
Orphans found: 3 pages with no parent —
listed at the bottom for re-homing.One-line tweak
Schedule it: re-running the identical prompt monthly keeps the map honest with zero extra effort.
Compile a new-hire onboarding pack from three spaces
Onboarding docs are scattered by definition — setup in ENG, process in PEOPLE, product context in PRODUCT. One prompt searches across spaces and assembles a sequenced reading list as a page.
ForManagers with a new engineer starting Monday and bookmarks from 2024.
The prompt
Use the confluence skill. A backend engineer joins my team Monday. Search across the ENG, PEOPLE, and PRODUCT spaces with CQL (try `label = "onboarding"` first, then `title ~ "onboarding" or title ~ "getting started"`). Read the top hits and build a page "Onboarding — backend, June 2026" in the ENG space: a week-one reading list in order (link + one line on why it matters + time estimate), then a 'do these by Friday' checklist. Flag anything that looks outdated — last modified before 2025 — instead of including it silently.What slides.md looks like
CQL pass 1: label = "onboarding" → 11 pages
CQL pass 2: title ~ "getting started" → 6 more
Week one (in order):
1. Dev environment setup (ENG) — 45 min
why: nothing else works until this does
2. How we deploy (ENG) — 20 min
...
⚠ Flagged: "Laptop setup 2023" — last modified
2023-11-02, contradicts page #1. Excluded.One-line tweak
Swap the role: the same prompt with "designer" pulls a different reading list from the same three spaces.
Skill vs MCP server: the honest decision
The contrarian case first, because it’s reasonable: why install a skill that documents an MCP server when Atlassian ships an official remote MCP server with OAuth? If the tools are self-describing, the argument goes, the playbook is dead weight. In practice the tools are self-describing and the data format is not — nothing in a tool schema tells Claude that page bodies are XHTML storage format or that updates race without a version fetch. Three options exist, and they’re genuinely different.
This skill + @xuandev/atlassian-mcp is the local, API-token route. You hold the credentials, nothing proxies through a third party, and the skill’s reference keeps Claude from fumbling storage format and version numbers. It’s the right default for Claude Code on your own machine — and because SKILL.md is a portable format, the same reference works from Codex too.
The atlassian-confluence MCP server is read-focused: list spaces, retrieve pages, search with CQL, with content converted to Markdown on the way out. If your workflows stop at “search and summarize” (use case 2 without the write-back), it’s the lighter install — no storage-format knowledge needed because nothing writes.
Atlassian’s official remote MCP server trades token auth for OAuth and runs as a managed proxy — Atlassian’s page describes it as operating “within the permissions of the signed-in user” and states it “does not store or cache your Jira or Confluence content.” Pick it when security review prefers OAuth scopes over long-lived API tokens, or when non-developers need the same access from Claude Desktop. My take: the skill route wins for developer automation because the playbook travels with the tools; the official server wins the moment a compliance checklist enters the room. For the Jira half of the suite, see our Jira MCP complete guide.
Gotchas (the five that bite)
All five come from the skill’s own troubleshooting section and the Confluence REST API’s sharp edges. You’ll hit at least two in your first week.
Storage format is not Markdown
Confluence page bodies are XHTML 'storage format' — tables are <table><tbody>, macros are <ac:structured-macro>. Markdown pasted raw renders as literal text. The skill tells Claude to convert before every create or update; if a page comes out as one giant plaintext block, the conversion step was skipped.
Updates require the current version number
The update flow is fetch → modify → push with version + 1. Pushing with a stale version fails (or worse, races a colleague's edit). Use case 6's fetch-first pattern isn't optional ceremony — it's how Confluence's optimistic locking works.
Auth failures have four boring causes
Per the skill's troubleshooting list: ~/.atlassian-mcp.json missing or malformed, an expired API token, an email that doesn't match the Atlassian account, or a domain missing the .atlassian.net suffix. Check those four before debugging anything else. And chmod 600 the file — it holds a live credential.
Permissions are yours, not Claude's
Every operation runs as your account. If Claude can't find a page, check whether YOU can see it in the web UI first — page restrictions and space permissions apply unchanged. Space keys are also case-sensitive in CQL: space = eng and space = ENG are different queries.
Atlassian Cloud rate limits bulk loops
The audits in use cases 3 and 8 can touch dozens of pages. Atlassian Cloud throttles bursty API traffic, so ask Claude to batch deliberately and report progress rather than firing every update at once. Deletes are recoverable (pages go to trash), but a half-applied label migration is annoying to unwind.
Pairs well with
Curated from the cookbook’s actual integrations: the writing skills that draft what Confluence stores (doc-coauthoring, docs-write, adr-documentation), the Jira-side skills for when wiki work spawns tickets (jira-cli, jira-expert), and the MCP servers the longer use cases lean on. If you’re mapping the whole wiki-tooling space, start with the best knowledge-base MCP servers for 2026.
Related skills
Related MCP servers
Two posts that compose well with this cookbook: the Jira MCP complete guide covers the issue-tracking half of the Atlassian suite this skill deliberately leaves alone, and the best knowledge-base MCP servers for 2026 maps Confluence against Notion, Obsidian, and the rest of the wiki field.
Frequently asked questions
What does the Confluence skill for Claude actually do?
It teaches Claude how to drive the Atlassian MCP server's 13 Confluence tools well: which tool to reach for, how CQL queries are shaped, that page bodies must be Confluence storage format (not Markdown), and that updates need a version increment. The skill itself is a reference document — the MCP server (@xuandev/atlassian-mcp) does the API calls. Together they cover pages, spaces, CQL search, comments, labels, and page hierarchies.
Confluence skill vs Confluence MCP server — which do I need?
Both, usually. The MCP server provides the raw tools; the skill provides the playbook — without it, Claude rediscovers storage format and version numbers by trial and error. If you only need read access (search and summarize), the atlassian-confluence MCP server alone is enough since it converts pages to Markdown. If you want OAuth instead of API tokens, Atlassian's official remote MCP server (jira-confluence) is the managed alternative.
Is there a Confluence agent skill, and does it work with Codex?
Yes — this is that agent skill, and the install panel on the skill page has tabs for Claude Code, Codex, Copilot, and Antigravity. The SKILL.md format is portable: any agent that loads skills can use the same Confluence reference. The MCP server it drives is also client-agnostic, so a Codex Confluence MCP setup uses the identical @xuandev/atlassian-mcp config.
Does the Confluence skill handle Jira too?
Deliberately not. The skill's own description says "NOT for Jira — use acli for Jira." The underlying MCP package does ship 38 Jira tools alongside the 13 Confluence ones, but this skill scopes itself to wiki work: pages, spaces, CQL, comments, labels. For the Jira side, see our Jira MCP guide — the two compose well in one session.
What credentials does it need, and is that safe?
An Atlassian API token (created at id.atlassian.com), your account email, and your site domain, stored in ~/.atlassian-mcp.json with chmod 600. Every operation runs as you — the MCP server respects Confluence permissions, so Claude can only see and edit what your account can. The trade-off versus OAuth: tokens are simpler but broader; rotate them like any credential.
Can Claude write Confluence pages in Markdown?
No — and this is the gotcha that justifies the skill. Confluence pages use storage format: XHTML with Confluence-specific elements like <ac:structured-macro>. Markdown pasted in raw renders as literal text. The skill's reference tells Claude to convert before creating or updating, which is exactly the step ad-hoc MCP usage gets wrong on the first try.
What's an AI documentation workflow actually worth here?
The wins are the workflows where Confluence is the bottleneck, not the writing: converting notes to structured pages (use case 1), CQL-grounded answers with citations (2), staleness audits across hundreds of pages (3), and surgical runbook updates that preserve history (6). The pattern: Claude does the reading and formatting, Confluence stays the system of record, and you approve before anything publishes.
Sources
Primary
- disusered/dotfiles-universal — the repo the confluence SKILL.md ships in
- xuanxt/atlassian-mcp — the MCP server the skill drives (@xuandev/atlassian-mcp, 13 Confluence + 38 Jira tools)
- Atlassian — Advanced searching using CQL (fields, operators, date functions)
- Atlassian — Confluence Cloud REST API reference
- Atlassian — official Remote MCP Server (OAuth, permissions, no content caching)
- Atlassian — API token creation
Internal