publish-to-confluence

Publish any markdown file from the vault to Confluence with format conversion and approval gate

Quality

40%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/publish-to-confluence/SKILL.md

Quality

Content

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

Description

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

Validation

90%

Warnings & errors only

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: about 1 month ago

Table of Contents

Discovery Implementation Validation

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.