Feedback on your confluence-skill skill

[RichardHightower]

I took a look at your confluence skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 89/100, solidly in B territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Progressive Disclosure Architecture (27/30) — the skill is nicely layered with a concise SKILL.md backed by six focused reference files. The weakest spot is Utility (18/20), where some feedback loops and validation checkpoints could be tighter.

What's Working Well

• Token efficiency is chef's kiss. Your SKILL.md is just 192 lines with zero fluff. The Quick Decision Matrix delivers instant value — users know exactly which tool to reach for.
• Reference architecture is clean. Six one-level-deep references (2,700+ lines total) means details aren't nested or buried. Users can jump straight to what they need without following a chain of links.
• Trigger phrases cover the bases. "Download Confluence pages", "upload to Confluence", "convert Wiki Markup", "sync markdown" — Claude will find this skill when it needs to.
• Real problem-solving power. MCP size limits, image handling, format conversion, CI/CD integration — you're filling gaps that matter.

The Big One: mark_tool_guide.md is oversized

At 847 lines, this single reference file is doing too much. It's covering installation, config, CI/CD, best practices, troubleshooting, and command reference all in one chunk. This hurts discoverability and makes it harder for users to find what they need.

Fix: Split into three focused files:

• mark_quick_start.md — Essential usage (install, basic workflow)
• mark_cicd.md — CI/CD integration examples
• mark_reference.md — Commands and troubleshooting

This keeps each reference under 300 lines and lets users jump straight to what matters. Should bump you +1 on Writing Style (conciseness).

Other Things Worth Fixing

1. Upload workflow needs a verification step. Step 3 uploads pages but doesn't mention how to verify success. Add: "Step 4: Verify upload success by checking the page in Confluence or use --dry-run first." Small but important for utility feedback loops.

2. Scripts table lacks parameter docs. Your Utility Scripts section lists 5 scripts with one-line purposes but no parameter quick-reference. Link to docstrings or add a parameter column so users know what flags are available.

3. Some reference files could compress. Conversion_guide.md is dense in places — could trim verbose explanations without losing clarity.

Quick Wins

• Split mark_tool_guide.md into three smaller references (+1 Writing Style)
• Add verification step to upload workflow (+1 Utility)
• Document script parameters in the utilities section (+1 Ease of Use)

These three changes alone could push you toward 92-93/100.

---

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.