sync-docs

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

Quality

63%

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

63%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 concrete, executable sync runbook with a clear sequenced workflow and verification checkpoints, scoring well on actionability and workflow clarity. It loses points on conciseness due to repetition and long inline sync lists, and on progressive disclosure because everything is monolithically inlined with no bundle files to offload detail.

Suggestions

De-duplicate the undocumented-variable diff/comm commands: define the canonical command once in 'Quick Commands' and reference it from Steps 2 and 5 instead of repeating it.

Move the per-feature sync-surface lists (Tailscale, Cloudflare, Cilium, registry mirror, migration, SELinux) into a references/ file (e.g. SYNC_SURFACES.md) and link to it one level deep, shrinking the inline SKILL.md body.

Make the verification feedback loop explicit in Step 7 (e.g. 'If a comparison reports drift, fix the surface and re-run the comparison until clean') to reach the validate-fix-retry standard.

Dimension	Reasoning	Score
Conciseness	The body is operational and assumes Claude's competence (no padding about what Terraform or variables are), but it runs ~300 lines with repeated diff/comm commands across steps and several long inline sync-surface lists that could be tightened, fitting 'mostly efficient but could be tightened' rather than a 4.	3 / 5
Actionability	It provides copy-paste-ready executable commands (rg, sed, comm, terraform-docs, uv run) plus concrete format templates for llms.md and kube.tf.example, with only minor gaps such as the '<name>' placeholder and a couple of prose-only steps like 'Understand its usage', matching 'mostly executable guidance with minor gaps'.	4 / 5
Workflow Clarity	A 7-step workflow with a dot graph, per-step detail, a dedicated Step 7 'Verify Consistency' with concrete validators, and an 8-item verification checklist provides clear sequencing and checkpoints; it falls short of 5 because the validate-fix-retry feedback loop is less explicit than the error-recovery anchor, and 'Common Sync Issues' covers recovery only loosely.	4 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent), so all content lives inline in SKILL.md; the body is well-sectioned but the long per-feature sync-surface lists (Tailscale, Cilium, registry, migration, SELinux) are content that could live in one-level-deep reference files, matching 'some structure but content that should be separate is inline'.	3 / 5
	Total	14 / 20 Passed

Description

62%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 third-person, has an explicit 'Use when' trigger, and names concrete target files, giving it solid completeness and distinctiveness. It is held back by a single generic action verb and limited trigger phrasing, leaving specificity and trigger-term coverage at mid-range.

Suggestions

Replace the generic 'ensures ... are in sync' with concrete actions, e.g. 'Extracts variables from variables.tf and propagates them into docs/llms.md, kube.tf.example, and README'.

Broaden the trigger with natural variations, e.g. 'Use when variables.tf changes, when adding or renaming a variable, or when documentation is out of sync with the Terraform module.'

Tie the 'when' clause to a concrete change event (variable added/renamed/removed) rather than the generic 'documentation needs updating'.

Dimension	Reasoning	Score
Specificity	Names the domain and four concrete target files (variables.tf, docs/llms.md, kube.tf.example, README), but the action itself is a single generic verb ('ensures ... are in sync') rather than multiple distinct concrete actions, fitting the '1-2 concrete actions' anchor rather than the comprehensive 5.	3 / 5
Completeness	It explicitly answers both 'what' (ensures the four files are in sync) and 'when' ('Use when documentation needs updating'), but the 'when' clause names only one trigger condition and could be more specific (e.g. when variables change), so it sits at 'both present, when could be more specific' rather than a 5.	4 / 5
Trigger Term Quality	'Use when documentation needs updating' is a natural phrase users would say, and file names add specificity, but only one trigger phrasing is offered with no synonyms or common variations, matching the 'some relevant keywords but missing variations' anchor.	3 / 5
Distinctiveness Conflict Risk	The named Terraform-specific files (variables.tf, kube.tf.example) carve a clear niche unlikely to overlap with non-Terraform skills, with only minor overlap risk against other docs/maintenance skills, matching the 'mostly distinct' anchor rather than the fully-distinct 5.	4 / 5
	Total	14 / 20 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: 5 missing, 1 deeper-than-1-level	Warning

	Total	15 / 16 Passed

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

Reviewed: 1 day 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.