borghei/Claude-Skills / project-management/confluence-expert
confluence-expert
VerifiedDesigns and audits Confluence spaces: page trees, labels, permissions, page ownership and stale content. Use when setting up or restructuring a space, a wiki has gone stale or duplicated, or labels are a mess.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| assets/sample_labels.json | config | 700 B |
| assets/sample_pages.json | config | 1.0 KB |
| assets/sample_space.json | config | 868 B |
| examples/product-team-confluence-space-buildout.md | markdown | 14.6 KB |
| references/confluence-playbook.md | markdown | 12.8 KB |
| references/red-flags.md | markdown | 12.6 KB |
| references/templates.md | markdown | 14.4 KB |
| scripts/content_health_auditor.py | script | 7.9 KB |
| scripts/label_taxonomy_analyzer.py | script | 7.5 KB |
| scripts/space_structure_analyzer.py | script | 7.4 KB |
references/confluence-playbook.md
View on GitHub# Confluence Expert Playbook
> Read this when you need the full detail behind the SKILL.md map — competencies, workflows, macro syntax, page layouts, inline template examples, permissions, governance, decision/handoff protocols, analytics, troubleshooting, and success criteria.
## Core Competencies (detail)
**Space Architecture**
- Design and create space hierarchies
- Organize knowledge by teams, projects, or topics
- Implement documentation taxonomies
- Configure space permissions and visibility
**Content Creation**
- Create structured pages with layouts
- Use macros for dynamic content
- Build templates for consistency
- Implement version control and change tracking
**Collaboration & Governance**
- Facilitate team documentation practices
- Implement review and approval workflows
- Manage content lifecycle
- Establish documentation standards
**Integration & Automation**
- Link Confluence with Jira
- Embed dynamic Jira reports
- Configure page watchers and notifications
- Set up content automation
## Workflows
### Space Creation
1. Determine space type (Team, Project, Knowledge Base, Personal)
2. Create space with clear name and description
3. Set space homepage with overview
4. Configure space permissions:
- View, Edit, Create, Delete
- Admin privileges
5. Create initial page tree structure
6. Add space shortcuts for navigation
7. **HANDOFF TO**: Teams for content population
### Page Architecture
**Best Practices**:
- Use page hierarchy (parent-child relationships)
- Maximum 3 levels deep for navigation
- Consistent naming conventions
- Date-stamp meeting notes
**Recommended Structure**:
```
Space Home
├── Overview & Getting Started
├── Team Information
│ ├── Team Members & Roles
│ ├── Communication Channels
│ └── Working Agreements
├── Projects
│ ├── Project A
│ │ ├── Overview
│ │ ├── Requirements
│ │ └── Meeting Notes
│ └── Project B
├── Processes & Workflows
├── Meeting Notes (Archive)
└── Resources & References
```
### Template Creation
1. Identify repeatable content pattern
2. Create page with structure and placeholders
3. Add instructions in placeholders
4. Format with appropriate macros
5. Save as template
6. Share with space or make global
7. **USE**: References for advanced template patterns
### Documentation Strategy
1. **Assess** current documentation state
2. **Define** documentation goals and audience
3. **Organize** content taxonomy and structure
4. **Create** templates and guidelines
5. **Migrate** existing documentation
6. **Train** teams on best practices
7. **Monitor** usage and adoption
8. **REPORT TO**: Senior PM on documentation health
### Knowledge Base Management
**Article Types**:
- How-to guides
- Troubleshooting docs
- FAQs
- Reference documentation
- Process documentation
**Quality Standards**:
- Clear title and description
- Structured with headings
- Updated date visible
- Owner identified
- Reviewed quarterly
## Essential Macros
### Content Macros
**Info, Note, Warning, Tip**:
```
{info}
Important information here
{info}
```
**Expand**:
```
{expand:title=Click to expand}
Hidden content here
{expand}
```
**Table of Contents**:
```
{toc:maxLevel=3}
```
**Excerpt & Excerpt Include**:
```
{excerpt}
Reusable content
{excerpt}
{excerpt-include:Page Name}
```
### Dynamic Content
**Jira Issues**:
```
{jira:JQL=project = PROJ AND status = "In Progress"}
```
**Jira Chart**:
```
{jirachart:type=pie|jql=project = PROJ|statType=statuses}
```
**Recently Updated**:
```
{recently-updated:spaces=@all|max=10}
```
**Content by Label**:
```
{contentbylabel:label=meeting-notes|maxResults=20}
```
### Collaboration Macros
**Status**:
```
{status:colour=Green|title=Approved}
```
**Task List**:
```
{tasks}
- [ ] Task 1
- [x] Task 2 completed
{tasks}
```
**User Mention**:
```
@username
```
**Date**:
```
{date:format=dd MMM yyyy}
```
## Page Layouts & Formatting
**Two-Column Layout**:
```
{section}
{column:width=50%}
Left content
{column}
{column:width=50%}
Right content
{column}
{section}
```
**Panel**:
```
{panel:title=Panel Title|borderColor=#ccc}
Panel content
{panel}
```
**Code Block**:
```
{code:javascript}
const example = "code here";
{code}
```
## Templates Library
### Meeting Notes Template
```
**Date**: {date}
**Attendees**: @user1, @user2
**Facilitator**: @facilitator
## Agenda
1. Topic 1
2. Topic 2
## Discussion
- Key point 1
- Key point 2
## Decisions
{info}Decision 1{info}
## Action Items
{tasks}
- [ ] Action item 1 (@owner, due date)
- [ ] Action item 2 (@owner, due date)
{tasks}
## Next Steps
- Next meeting date
```
### Project Overview Template
```
{panel:title=Project Quick Facts}
**Status**: {status:colour=Green|title=Active}
**Owner**: @owner
**Start Date**: DD/MM/YYYY
**End Date**: DD/MM/YYYY
**Budget**: $XXX,XXX
{panel}
## Executive Summary
Brief project description
## Objectives
1. Objective 1
2. Objective 2
## Key Stakeholders
| Name | Role | Responsibility |
|------|------|----------------|
| @user | PM | Overall delivery |
## Milestones
{jira:project=PROJ AND type=Epic}
## Risks & Issues
| Risk | Impact | Mitigation |
|------|--------|-----------|
| Risk 1 | High | Action plan |
## Resources
- [Design Docs](#)
- [Technical Specs](#)
```
### Decision Log Template
```
**Decision ID**: PROJ-DEC-001
**Date**: {date}
**Status**: {status:colour=Green|title=Approved}
**Decision Maker**: @decisionmaker
## Context
Background and problem statement
## Options Considered
1. Option A
- Pros:
- Cons:
2. Option B
- Pros:
- Cons:
## Decision
Chosen option and rationale
## Consequences
Expected outcomes and impacts
## Next Steps
- [ ] Action 1
- [ ] Action 2
```
### Sprint Retrospective Template
```
**Sprint**: Sprint XX
**Date**: {date}
**Team**: Team Name
## What Went Well
{info}
- Positive item 1
- Positive item 2
{info}
## What Didn't Go Well
{warning}
- Challenge 1
- Challenge 2
{warning}
## Action Items
{tasks}
- [ ] Improvement 1 (@owner)
- [ ] Improvement 2 (@owner)
{tasks}
## Metrics
**Velocity**: XX points
**Completed Stories**: X/X
**Bugs Found**: X
```
## Space Permissions
### Permission Levels
- **View**: Read-only access
- **Edit**: Modify existing pages
- **Create**: Add new pages
- **Delete**: Remove pages
- **Admin**: Full space control
### Permission Schemes
**Public Space**:
- All users: View
- Team members: Edit, Create
- Space admins: Admin
**Team Space**:
- Team members: View, Edit, Create
- Team leads: Admin
- Others: No access
**Project Space**:
- Stakeholders: View
- Project team: Edit, Create
- PM: Admin
## Content Governance
**Review Cycles**:
- Critical docs: Monthly
- Standard docs: Quarterly
- Archive docs: Annually
**Archiving Strategy**:
- Move outdated content to Archive space
- Label with "archived" and date
- Maintain for 2 years, then delete
- Keep audit trail
**Content Quality Checklist**:
- [ ] Clear, descriptive title
- [ ] Owner/author identified
- [ ] Last updated date visible
- [ ] Appropriate labels applied
- [ ] Links functional
- [ ] Formatting consistent
- [ ] No sensitive data exposed
## Decision Framework
**When to Escalate to Atlassian Admin**:
- Need org-wide template
- Require cross-space permissions
- Blueprint configuration
- Global automation rules
- Space export/import
**When to Collaborate with Jira Expert**:
- Embed Jira queries and charts
- Link pages to Jira issues
- Create Jira-based reports
- Sync documentation with tickets
**When to Support Scrum Master**:
- Sprint documentation templates
- Retrospective pages
- Team working agreements
- Process documentation
**When to Support Senior PM**:
- Executive report pages
- Portfolio documentation
- Stakeholder communication
- Strategic planning docs
## Handoff Protocols
**FROM Senior PM**:
- Documentation requirements
- Space structure needs
- Template requirements
- Knowledge management strategy
**TO Senior PM**:
- Documentation coverage reports
- Content usage analytics
- Knowledge gaps identified
- Template adoption metrics
**FROM Scrum Master**:
- Sprint ceremony templates
- Team documentation needs
- Meeting notes structure
- Retrospective format
**TO Scrum Master**:
- Configured templates
- Space for team docs
- Training on best practices
- Documentation guidelines
**WITH Jira Expert**:
- Jira-Confluence linking
- Embedded Jira reports
- Issue-to-page connections
- Cross-tool workflow
## Best Practices
**Writing Style**:
- Use active voice
- Write scannable content (headings, bullets, short paragraphs)
- Include visuals and diagrams
- Provide examples
- Keep language simple and clear
**Organization**:
- Consistent naming conventions
- Meaningful labels
- Logical page hierarchy
- Related pages linked
- Clear navigation
**Maintenance**:
- Regular content audits
- Remove duplication
- Update outdated information
- Archive obsolete content
- Monitor page analytics
## Analytics & Metrics
**Usage Metrics**:
- Page views per space
- Most visited pages
- Search queries
- Contributor activity
- Orphaned pages
**Health Indicators**:
- Pages without recent updates
- Pages without owners
- Duplicate content
- Broken links
- Empty spaces
## Atlassian MCP Integration
**Primary Tool**: Atlassian Rovo MCP Server (Atlassian's official remote MCP server for Cloud; endpoint `https://mcp.atlassian.com/v2/mcp`). Tool names below are from Atlassian's [supported tools](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/supported-tools/) list as of September 2026 -- re-check it, the list changes.
**Key Operations** (Confluence tools):
- Create and manage spaces -- `createConfluenceSpace`, `listConfluenceSpaces`, `getConfluenceSpace`
- Create and update pages (and other content types) -- `createConfluenceContent`, `updateConfluenceContent`
- Manage page hierarchies -- `moveConfluenceContent`, `copyConfluenceContent`, `archiveConfluenceContent`
- Read templates -- `listConfluenceTemplates`, `getConfluenceTemplate`
- Configure page permissions and restrictions -- `addConfluenceContentPermissions`, `setConfluenceContentRestrictionState`
- Search content with CQL -- `searchConfluence`
- Extract documentation for analysis -- `getConfluenceContent`, `exportConfluenceContent`, `getContentFormatGuide` (body format rules)
**Integration Points**:
- Create documentation for Senior PM projects
- Support Scrum Master with ceremony templates
- Link to Jira issues for Jira Expert
- Provide templates for Template Creator
## Troubleshooting
| Problem | Likely Cause | Resolution |
|---------|-------------|------------|
| Users cannot find existing documentation | Poor space/page hierarchy, missing labels, or unclear page titles | Restructure to max 3 levels deep; enforce descriptive naming conventions; add labels to all pages and use `contentbylabel` macro for discovery |
| Confluence search returns irrelevant results | Page titles are generic, content lacks keywords, or spaces have too many orphaned pages | Use specific, descriptive titles; add excerpt macros for search snippets; audit and remove orphaned pages quarterly |
| Pages become stale with outdated information | No content ownership model, no review cadence, or no visible "last updated" date | Assign a page owner to every active page; set quarterly review reminders; add `{date}` macro to show last update prominently |
| Space permissions are too permissive or too restrictive | Ad-hoc permission changes without a governance model; individual permissions used instead of groups | Reset to group-based permissions; define 3-4 standard permission schemes; audit permissions quarterly |
| Jira macros embedded in pages show errors or no data | JQL references deleted projects, or the viewer lacks Jira permissions for the referenced project | Verify JQL validity; ensure Confluence viewers also have Jira browse permissions for referenced projects |
| Content duplication across multiple spaces | No single source of truth policy; teams copy content instead of linking | Implement excerpt-include pattern for shared content; establish content ownership map; use cross-space linking instead of copying |
| Page tree becomes too deep (>5 levels) creating navigation fatigue | Organic growth without architectural review; no archiving strategy | Flatten hierarchy to max 3 levels; archive completed project pages; use labels and search instead of deep nesting |
## Success Criteria
- 90%+ of active pages have a designated owner and a review date within the past 6 months
- Orphaned pages (no parent, no links, no views in 90 days) represent less than 5% of total content
- New team members can find onboarding documentation within 3 clicks from the space homepage
- Content duplication rate stays below 10% (measured by duplicate title or excerpt analysis)
- All spaces follow the standardized page architecture template (overview, team info, projects, processes, resources)
- Confluence adoption measured by monthly active editors exceeds 60% of licensed users
- Knowledge base articles resolve 40%+ of common questions without escalation to a person
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |