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/label_taxonomy_analyzer.py
View on GitHub#!/usr/bin/env python3
"""Label Taxonomy Analyzer - Analyze Confluence label usage and recommend taxonomy.
Reads label data across pages and identifies inconsistencies, unused labels,
and suggests a standardized taxonomy.
Usage:
python label_taxonomy_analyzer.py --labels labels.json
python label_taxonomy_analyzer.py --labels labels.json --json
python label_taxonomy_analyzer.py --example
"""
import argparse
import json
import re
import sys
from collections import Counter
def load_data(path: str) -> dict:
with open(path, "r") as f:
return json.load(f)
def analyze_labels(data: dict) -> dict:
space = data.get("space", "Unknown")
pages = data.get("pages", [])
all_labels = []
pages_with_labels = 0
pages_without_labels = 0
label_page_map = {}
for page in pages:
labels = page.get("labels", [])
if labels:
pages_with_labels += 1
else:
pages_without_labels += 1
for label in labels:
all_labels.append(label)
if label not in label_page_map:
label_page_map[label] = []
label_page_map[label].append(page.get("title", "Unknown"))
label_counts = Counter(all_labels)
total_unique = len(label_counts)
total_uses = len(all_labels)
coverage_pct = round(pages_with_labels / len(pages) * 100, 1) if pages else 0
# Identify issues
issues = []
# Inconsistent casing
lower_map = {}
for label in label_counts:
key = label.lower()
if key not in lower_map:
lower_map[key] = []
lower_map[key].append(label)
case_conflicts = {k: v for k, v in lower_map.items() if len(v) > 1}
if case_conflicts:
for key, variants in case_conflicts.items():
issues.append({
"type": "case_conflict",
"description": f"Case variants: {', '.join(variants)}",
"suggestion": f"Standardize to: {key}",
})
# Inconsistent separators
separator_issues = []
for label in label_counts:
if " " in label:
separator_issues.append(label)
elif "_" in label and "-" in str(label_counts):
separator_issues.append(label)
if separator_issues:
issues.append({
"type": "separator_inconsistency",
"description": f"Labels with spaces (use hyphens instead): {', '.join(separator_issues[:5])}",
"suggestion": "Use lowercase-hyphen-separated labels consistently.",
})
# Rarely used labels (only 1 page)
rare_labels = [l for l, c in label_counts.items() if c == 1]
# Very popular labels (might be too broad)
popular_labels = [(l, c) for l, c in label_counts.most_common(5)]
# Label categories (heuristic grouping)
categories = {
"status": [], "type": [], "team": [], "project": [], "other": [],
}
status_words = {"draft", "review", "approved", "archived", "deprecated", "active", "done", "wip"}
type_words = {"guide", "how-to", "faq", "reference", "process", "template", "meeting", "retro", "sprint"}
team_words = {"engineering", "product", "design", "marketing", "sales", "support", "hr", "finance"}
for label in label_counts:
lower = label.lower().replace("-", " ").replace("_", " ")
words = set(lower.split())
if words & status_words:
categories["status"].append(label)
elif words & type_words:
categories["type"].append(label)
elif words & team_words:
categories["team"].append(label)
else:
categories["other"].append(label)
# Recommendations
recs = []
if coverage_pct < 70:
recs.append(f"Label coverage is {coverage_pct:.0f}% (target: 90%+). Add labels to {pages_without_labels} unlabeled pages.")
if case_conflicts:
recs.append(f"Fix {len(case_conflicts)} label case conflict(s). Standardize to lowercase-hyphen format.")
if len(rare_labels) > total_unique * 0.5:
recs.append(f"{len(rare_labels)} labels used only once. Consolidate into a curated taxonomy of 20-30 standard labels.")
if separator_issues:
recs.append("Replace spaces and underscores in labels with hyphens for consistency.")
return {
"space": space,
"total_pages": len(pages),
"pages_with_labels": pages_with_labels,
"pages_without_labels": pages_without_labels,
"coverage_pct": coverage_pct,
"total_unique_labels": total_unique,
"total_label_uses": total_uses,
"top_labels": [{"label": l, "count": c} for l, c in label_counts.most_common(10)],
"rare_labels": rare_labels[:20],
"case_conflicts": {k: v for k, v in list(case_conflicts.items())[:5]},
"categories": {k: v for k, v in categories.items() if v},
"issues": issues,
"recommendations": recs,
}
def print_report(result: dict) -> None:
print(f"\nLabel Taxonomy Analysis: {result['space']}")
print(f"Pages: {result['total_pages']} | Unique Labels: {result['total_unique_labels']}")
print("=" * 55)
print(f"Coverage: {result['coverage_pct']:.0f}% ({result['pages_with_labels']} labeled / {result['pages_without_labels']} unlabeled)")
print(f"\nTop Labels:")
for tl in result["top_labels"]:
bar = "#" * min(tl["count"], 30)
print(f" {tl['label']:<25} {tl['count']:>4} {bar}")
if result["case_conflicts"]:
print(f"\nCase Conflicts:")
for key, variants in result["case_conflicts"].items():
print(f" '{key}': {', '.join(variants)}")
if result["categories"]:
print(f"\nLabel Categories:")
for cat, labels in result["categories"].items():
print(f" {cat.title()}: {', '.join(labels[:5])}")
if result["rare_labels"]:
print(f"\nRarely Used Labels (1 page): {', '.join(result['rare_labels'][:10])}")
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": [
{"title": "Onboarding Guide", "labels": ["onboarding", "guide", "engineering"]},
{"title": "API Reference", "labels": ["api", "reference", "Engineering"]},
{"title": "Sprint 23 Retro", "labels": ["sprint", "retro"]},
{"title": "Old Design Doc", "labels": ["design doc"]},
{"title": "Quick Notes", "labels": []},
{"title": "Architecture Overview", "labels": ["architecture", "reference"]},
],
}
print(json.dumps(example, indent=2))
def main():
parser = argparse.ArgumentParser(description="Analyze Confluence label taxonomy.")
parser.add_argument("--labels", type=str, help="Path to label data 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.labels:
parser.error("--labels is required")
data = load_data(args.labels)
result = analyze_labels(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 |