publish-to-confluence

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

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/publish-to-confluence/SKILL.md

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a highly actionable, well-sequenced workflow with concrete API templates and strong validation/feedback loops. Its main weakness is the absence of progressive disclosure — the conversion table and API reference details are inlined rather than split into reference files.

Suggestions

Move the markdown-to-Confluence conversion table and the full REST request bodies into a reference file (e.g. references/confluence-api.md) and link to it from the main phases, keeping SKILL.md as a lean overview.

Add a short pre-publish XHTML validation step (e.g. sanity-check that storage-format body is non-empty and balanced) before the approval gate to strengthen the destructive-operation checkpoint.

Trim the duplicated confirmation/preview prose in Phase 4 and Phase 6 to a single concise template to recover token budget.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient templates, a conversion table, and API request bodies with little padding of concepts Claude already knows; only minor sections (e.g. the verbose preview/confirmation blocks) could be trimmed, fitting the 'efficient; minor over-explanation' anchor.	4 / 5
Actionability	It provides copy-paste-ready REST endpoints, full JSON request bodies for create/update, a complete markdown-to-storage-format conversion table, and exact curl-equivalent calls — matching the 'fully executable, copy-paste ready' anchor.	5 / 5
Workflow Clarity	Phases 1–6 are explicitly sequenced with a pre-flight integration check and a CRITICAL approval-gate checkpoint, plus error-recovery feedback loops (409 → fetch latest and retry, rate limits → backoff, network errors → save locally), matching the score-5 anchor.	5 / 5
Progressive Disclosure	The file is well-sectioned into clear phases and a single coherent workflow, but everything (conversion table, full API bodies, error handling) is inline with no one-level-deep reference files, fitting 'good structure; most content appropriately placed; minor organization gaps'.	4 / 5
	Total	18 / 20 Passed

Description

70%Weight 40%Scale 1-5

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 is specific and clearly niche-scoped to Confluence publishing, but it omits any explicit 'when to use' trigger guidance, which caps its completeness. Adding a 'Use when...' clause with synonyms like 'wiki' would raise both completeness and trigger-term quality.

Suggestions

Append a 'Use when...' clause with concrete trigger phrases, e.g. 'Use when the user wants to publish markdown to Confluence, push a doc to the wiki, or share a generated PRD/release notes.'

Add synonyms and natural variations such as 'wiki' and 'push to wiki' to broaden trigger-term coverage.

Consider naming one more concrete capability (e.g. 'update existing pages' or 'add labels') to push specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions — 'Publish any markdown file', 'format conversion', and 'approval gate' — with only minor coverage gaps, matching the 'lists several specific actions' anchor rather than the fully comprehensive score-5 example.	4 / 5
Completeness	The description gives a clear 'what' but contains no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	Core natural terms a user would say are present ('publish', 'Confluence', 'markdown file'), but common synonyms like 'wiki' and file extensions are absent, fitting the 'good keyword coverage, a few natural terms missing' anchor.	4 / 5
Distinctiveness Conflict Risk	'Publish any markdown file from the vault to Confluence' carves out a clear niche with distinct triggers and minimal overlap with other skills, matching the score-5 anchor.	5 / 5
	Total	16 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: huytieu/COG-second-brain
Path: .claude/skills/publish-to-confluence/SKILL.md
Commit: cb4644d

Reviewed: 2 days 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.