sync-docs

Use when documentation needs updating - ensures variables.tf, docs/llms.md, kube.tf.example, and README are in sync

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/sync-docs/SKILL.md

Quality

Content

77%Weight 40%Scale 1-3

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

The body is highly actionable with a well-sequenced, validated workflow and concrete commands throughout. Its main weaknesses are verbosity from duplicated/repeated content and a monolithic structure that does not progressively disclose the large per-feature sync lists into separate reference files.

Suggestions

De-duplicate the workflow: keep either the dot graph or the numbered Step 1-7 list, not both, and factor the repeated 'gemini --model gemini-3.1-pro-preview -p' into a single documented alias or note.

Split the long per-feature 'keep these surfaces in sync' lists (Tailscale, Cilium, registry mirror, migration, SELinux) into a references file (e.g. SURFACES.md) and link to it one level deep, improving progressive disclosure.

Tighten the 'Documentation Files' table and section-organization table by collapsing low-value rows so the overview stays scannable.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and avoids explaining concepts Claude already knows, but the dot graph duplicates the numbered Step 1-7 list, the gemini model string is repeated verbatim across many commands, and the long per-feature sync surface lists could be tightened, fitting the 'mostly efficient but could be tightened' anchor.	2 / 3
Actionability	Provides fully executable, copy-paste-ready commands (gemini invocations, terraform-docs, uv run scripts, rg/diff one-liners, terraform fmt) plus concrete format templates for docs/llms.md and kube.tf.example, matching the 'fully executable code/commands; copy-paste ready' anchor.	3 / 3
Workflow Clarity	A clear seven-step sequence is paired with an explicit Step 7 verification, a verification checklist, a final consistency-check command, and a 'Common Sync Issues' error-recovery section, satisfying the 'clear sequence with explicit validation steps; feedback loops; checklists' anchor.	3 / 3
Progressive Disclosure	The skill is a single ~280-line monolithic file with no bundle references, and large blocks (per-feature sync surface lists, the dot graph, format specs) that could live in separate reference files are inline, matching 'some structure but content that should be separate is inline'.	2 / 3
	Total	10 / 12 Passed

Description

67%Weight 40%Scale 1-3

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 clearly states both purpose and an explicit 'Use when' trigger, and ties the skill to specific repo files. It is held back by a single generic action verb and a trigger clause that lacks keyword variations, leaving it modestly distinguishable from other documentation skills.

Suggestions

Replace the single verb 'ensures ... are in sync' with multiple concrete actions (e.g. 'extract variables from variables.tf, regenerate docs/llms.md, update kube.tf.example, and refresh README') to lift specificity.

Broaden trigger-term coverage with natural variations users actually say, e.g. 'Use when variables change, docs are out of date, or you need to sync/regenerate documentation'.

Tie the trigger to the niche to reduce conflict risk, e.g. 'Use when kube-hetzner documentation needs updating after a variables.tf change'.

Dimension	Reasoning	Score
Specificity	Names concrete targets ("variables.tf, docs/llms.md, kube.tf.example, and README") but describes a single generic action ("ensures ... are in sync") rather than listing multiple distinct concrete actions, matching the 'names domain and some actions, but not comprehensive' anchor.	2 / 3
Completeness	Explicitly answers both what ("ensures variables.tf, docs/llms.md, kube.tf.example, and README are in sync") and when ("Use when documentation needs updating"), satisfying the 'clearly answers both what AND when with explicit triggers' anchor.	3 / 3
Trigger Term Quality	Includes a natural trigger phrase ("Use when documentation needs updating") and terms like "sync"/"in sync", but offers limited variation coverage (no "update docs", "regenerate docs", "keep docs consistent"), fitting the 'some relevant keywords but missing common variations' anchor.	2 / 3
Distinctiveness Conflict Risk	The named Terraform files carve a clear niche for the 'what', but the trigger clause ("documentation needs updating") is generic and could overlap with other documentation skills, matching 'somewhat specific but could still overlap with similar skills'.	2 / 3
	Total	9 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 3 missing	Warning

	Total	15 / 16 Passed

Repository: mysticaltech/terraform-hcloud-kube-hetzner
Path: .claude/skills/sync-docs/SKILL.md
Commit: a8b696d

Reviewed: 11 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.