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 |
scripts/space_structure_analyzer.py
View on GitHub#!/usr/bin/env python3
"""Space Structure Analyzer - Analyze Confluence space architecture against best practices.
Evaluates page hierarchy depth, naming consistency, and structural patterns
to recommend improvements for navigation and discoverability.
Usage:
python space_structure_analyzer.py --space space.json
python space_structure_analyzer.py --space space.json --json
python space_structure_analyzer.py --example
"""
import argparse
import json
import sys
from collections import Counter
def load_data(path: str) -> dict:
with open(path, "r") as f:
return json.load(f)
def analyze_structure(data: dict) -> dict:
space_name = data.get("space", "Unknown")
pages = data.get("pages", [])
# Build hierarchy
page_map = {p.get("id"): p for p in pages}
children = {}
root_pages = []
for p in pages:
parent_id = p.get("parent_id")
if parent_id:
if parent_id not in children:
children[parent_id] = []
children[parent_id].append(p["id"])
else:
root_pages.append(p["id"])
# Calculate depths
def get_depth(page_id, depth=0):
max_depth = depth
for child_id in children.get(page_id, []):
child_depth = get_depth(child_id, depth + 1)
max_depth = max(max_depth, child_depth)
return max_depth
max_depth = 0
depth_distribution = Counter()
for page in pages:
page_id = page.get("id")
# Calculate this page's depth
depth = 0
current = page
while current.get("parent_id") and current["parent_id"] in page_map:
depth += 1
current = page_map[current["parent_id"]]
depth_distribution[depth] += 1
max_depth = max(max_depth, depth)
# Root page analysis
recommended_roots = ["Overview", "Team Information", "Projects", "Processes", "Meeting Notes", "Resources"]
# Naming analysis
titles = [p.get("title", "") for p in pages]
short_titles = [t for t in titles if len(t) < 5]
long_titles = [t for t in titles if len(t) > 60]
duplicate_titles = [t for t, count in Counter(titles).items() if count > 1]
# Score
score = 100
issues = []
recs = []
if max_depth > 5:
issues.append(f"Page hierarchy too deep ({max_depth} levels). Recommended max: 3-4 levels.")
recs.append("Flatten deep hierarchies. Use labels and search instead of deep nesting.")
score -= 20
elif max_depth > 3:
issues.append(f"Page hierarchy is {max_depth} levels deep. Consider flattening to 3.")
score -= 10
if len(root_pages) > 10:
issues.append(f"Too many root pages ({len(root_pages)}). Creates cluttered navigation.")
recs.append("Consolidate root pages into 5-7 top-level categories.")
score -= 15
elif len(root_pages) < 3:
issues.append(f"Only {len(root_pages)} root page(s). Consider adding standard sections.")
score -= 5
if short_titles:
issues.append(f"{len(short_titles)} page(s) with very short titles (<5 chars).")
recs.append("Use descriptive page titles. Short titles are hard to find in search.")
score -= 5
if duplicate_titles:
issues.append(f"{len(duplicate_titles)} duplicate title(s): {', '.join(duplicate_titles[:3])}")
recs.append("Rename duplicate pages to be unique and descriptive.")
score -= 10
# Wide pages (too many children)
wide_pages = []
for page_id, child_list in children.items():
if len(child_list) > 15:
page = page_map.get(page_id, {})
wide_pages.append({"title": page.get("title", "Unknown"), "children": len(child_list)})
if wide_pages:
issues.append(f"{len(wide_pages)} page(s) with >15 children. Creates scrolling navigation.")
recs.append("Group child pages under subcategories. Target 5-10 children per page.")
score -= 10
score = max(0, score)
if score >= 80:
rating = "Well Structured"
elif score >= 60:
rating = "Needs Improvement"
else:
rating = "Poorly Structured"
return {
"space": space_name,
"total_pages": len(pages),
"score": score,
"rating": rating,
"max_depth": max_depth,
"root_pages": len(root_pages),
"depth_distribution": dict(depth_distribution),
"naming": {
"short_titles": len(short_titles),
"long_titles": len(long_titles),
"duplicates": duplicate_titles,
},
"wide_pages": wide_pages,
"issues": issues,
"recommendations": recs,
}
def print_report(result: dict) -> None:
print(f"\nSpace Structure Analysis: {result['space']}")
print(f"Pages: {result['total_pages']}")
print("=" * 55)
print(f"Score: {result['score']}/100 ({result['rating']})")
print(f"Max Depth: {result['max_depth']} | Root Pages: {result['root_pages']}")
print(f"\nDepth Distribution:")
for depth in sorted(result["depth_distribution"].keys()):
count = result["depth_distribution"][depth]
bar = "#" * min(count, 40)
print(f" Level {depth}: {count:>4} pages {bar}")
if result["naming"]["duplicates"]:
print(f"\nDuplicate Titles: {', '.join(result['naming']['duplicates'])}")
if result["wide_pages"]:
print(f"\nWide Pages (>15 children):")
for wp in result["wide_pages"]:
print(f" - {wp['title']}: {wp['children']} children")
if result["issues"]:
print(f"\nIssues:")
for issue in result["issues"]:
print(f" ! {issue}")
if result["recommendations"]:
print(f"\nRecommendations:")
for i, r in enumerate(result["recommendations"], 1):
print(f" {i}. {r}")
print()
def print_example() -> None:
example = {
"space": "Engineering Team",
"pages": [
{"id": "1", "title": "Overview", "parent_id": None},
{"id": "2", "title": "Team Members", "parent_id": "1"},
{"id": "3", "title": "Projects", "parent_id": None},
{"id": "4", "title": "Project Alpha", "parent_id": "3"},
{"id": "5", "title": "Design Docs", "parent_id": "4"},
{"id": "6", "title": "API Spec", "parent_id": "5"},
{"id": "7", "title": "v2 Changes", "parent_id": "6"},
{"id": "8", "title": "Meeting Notes", "parent_id": None},
{"id": "9", "title": "test", "parent_id": None},
{"id": "10", "title": "test", "parent_id": None},
],
}
print(json.dumps(example, indent=2))
def main():
parser = argparse.ArgumentParser(description="Analyze Confluence space structure.")
parser.add_argument("--space", type=str, help="Path to space structure JSON file")
parser.add_argument("--json", action="store_true", help="Output as JSON")
parser.add_argument("--example", action="store_true", help="Print example and exit")
args = parser.parse_args()
if args.example:
print_example()
return
if not args.space:
parser.error("--space is required")
data = load_data(args.space)
result = analyze_structure(data)
if args.json:
print(json.dumps(result, indent=2))
else:
print_report(result)
if __name__ == "__main__":
try:
main()
except (OSError, ValueError, KeyError, TypeError, AttributeError, IndexError) as exc:
print(f"error: bad input ({type(exc).__name__}): {exc}", file=sys.stderr)
sys.exit(2)
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: 471k | 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: 471k | 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: 471k | 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 |