publish-to-confluence
Publish any markdown file from the vault to Confluence with format conversion and approval gate
40
40%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/publish-to-confluence/SKILL.mdQuality
Discovery
40%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear and distinctive niche—publishing markdown to Confluence—but lacks an explicit 'Use when...' clause, which is critical for Claude to know when to select this skill. The specificity of actions is moderate; it mentions format conversion and approval gate but doesn't elaborate on concrete capabilities.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to publish or sync markdown notes to Confluence, or mentions Atlassian wiki publishing.'
Include additional natural trigger terms such as 'Atlassian', 'wiki', '.md files', 'sync to Confluence', or 'deploy documentation'.
Expand the concrete actions listed, e.g., 'Converts markdown headings, tables, and code blocks to Confluence format, handles image attachments, and prompts for user approval before publishing.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (markdown to Confluence publishing) and mentions some actions (format conversion, approval gate), but doesn't list multiple concrete actions in detail—e.g., what kind of format conversion, what the approval gate entails, or other specific capabilities. | 2 / 3 |
Completeness | It describes what the skill does (publish markdown to Confluence with format conversion and approval gate) but has no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric caps completeness at 2, and the 'what' itself is only moderately detailed, placing this closer to 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'markdown', 'Confluence', 'publish', and 'vault', which are natural terms a user might say. However, it misses common variations like 'wiki', 'Atlassian', 'deploy', 'sync', 'upload', or '.md files'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'markdown from vault', 'Confluence', 'format conversion', and 'approval gate' creates a very specific niche that is unlikely to conflict with other skills. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill has excellent workflow clarity with a well-sequenced six-phase process and a critical approval gate before publishing. However, it is significantly over-verbose, explaining concepts Claude already knows (HTTP status codes, basic markdown-to-HTML mappings, REST API patterns) and embedding all reference material inline rather than splitting it into supporting files. The actionability is moderate—templates and placeholders are provided but lack truly executable examples.
Suggestions
Extract the markdown-to-Confluence conversion table and API payload templates into a separate reference file (e.g., CONFLUENCE-FORMAT.md) and link to it from the main skill.
Remove explanations of standard HTTP error codes and REST patterns—Claude already knows these. Replace with a compact table of Confluence-specific error handling only.
Cut the 'Agent Mode Awareness' section and other boilerplate that adds no Confluence-specific value, reducing the skill to under 100 lines.
Provide at least one fully executable WebFetch example with realistic (non-placeholder) structure so Claude can pattern-match against it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~200+ lines. It over-explains many things Claude already knows (markdown-to-HTML conversion rules, REST API patterns, HTTP status code meanings). The conversion table, while useful as a quick reference, is padded with obvious mappings. The fallback and error handling sections describe standard behaviors Claude would naturally handle. | 1 / 3 |
Actionability | The skill provides concrete API endpoints, JSON payloads, and conversion rules, which is good. However, much of it is pseudo-structured rather than truly executable—the code blocks contain placeholder templates (e.g., `[CUSTOMIZE: your-confluence-url]`) and descriptive text rather than actual runnable code. The WebFetch usage is described but not shown as executable commands. | 2 / 3 |
Workflow Clarity | The six-phase workflow is clearly sequenced with explicit validation checkpoints. Phase 4 is a critical approval gate before any destructive/publishing action. The re-publishing flow handles version conflicts, and Phase 6 includes confirmation and vault metadata updates. Error recovery is addressed with fallback behaviors (saving XHTML locally, retry with backoff). | 3 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to supporting files. The conversion table, error handling details, and API payload examples could all be split into separate reference files. There are no bundle files, yet the content is far too long to be inline—everything is crammed into a single document with no navigation structure. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- huytieu/COG-second-brain
- Commit
034af4c
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.