mastering-confluence

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

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 92/100, solid A territory. This is based on Anthropic's agent skill best practices. Your strongest area is Spec Compliance (15/15) — the YAML frontmatter is clean and your trigger phrases cover a ton of Confluence workflows. Weakest spot is Utility (18/20), mostly because some feedback loops and constraint documentation could be tighter.

What's Working Well

• Spec compliance is chef's kiss — Your SKILL.md frontmatter is pristine: valid YAML, correct naming conventions, and those trigger phrases (upload, download, convert, sync, search, CQL) are doing real work for discoverability. Someone searching for "convert Markdown to Wiki Markup" will find this.

• PDA architecture is excellent — You kept SKILL.md lean at ~220 lines, then split the deep stuff into 10 focused reference files (wiki_markup_guide.md, cql_reference.md, troubleshooting_guide.md, etc.). That's the right move for token economy. Layered structure scored 9/10 for exactly this reason.

• Practical problem-solving — You're directly addressing a real MCP pain point: the API size limits on uploads and downloads. Providing the mark CLI workaround, script templates, and dry-run verification steps means people can actually use this, not just read about it.

• Command examples are substantial — The conversion matrices, checklist format, and grep-friendly structure in upload/download guides show you thought about how people actually use these tools.

The Big One

Your reference files over 100 lines lack table of contents. Specifically, cql_reference.md is 135 lines but jumps straight to "## Basic Syntax" without navigation anchors. When someone's looking for "how to filter by label" or "date range queries," they're doing Ctrl+F instead of jumping to a section.

Fix: Add a ## Contents section at the top of cql_reference.md and any reference over 100 lines. Takes 5 minutes, +1 point. Example:

## Contents
- [Basic Syntax](#basic-syntax)
- [Field References](#field-references)
- [Operators](#operators)
- [Examples](#examples)

Same applies to conversion_guide.md if it's borderline.

Other Things Worth Fixing

1. Trim conversion_guide.md examples — The sample testing document section (around lines 660-720) is doing heavy lifting with full multi-section examples. You could trim to a single focused example or reference a separate examples file. Reclaims some token budget without losing clarity. -1 point writing style penalty here.

2. Metadata description length — You've got solid triggers but the description could be tighter. Current is doing good work, but if you're submitting elsewhere, "Convert between Markdown and Wiki Markup, upload/download pages, embed Mermaid diagrams, search with CQL" is punchier than the current form.

3. Workflow step numbering — Most checklists are numbered, but some guides use narrative flow instead of explicit steps. Standardize on numbered steps (1, 2, 3) throughout for consistency. Makes it easier to reference "Step 4" in support.

Quick Wins

• Add TOC to reference files >100 lines (+1 point) — cql_reference.md at minimum
• Trim verbose examples in conversion_guide.md — reclaim tokens, cleaner examples
• Standardize step numbering across all workflow guides — consistency win
• Consider metadata tightening — punch up the description for other platforms

You're already at production-ready territory. These fixes push you from A to A+ without major rework.

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.