CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

sync-docs

Scans all authoritative documents (constitution, context, glossary, requirements) and all derivative documents (architecture decisions, architecture overview, MVP architecture spec, vision, implementation heuristics) to add missing citations, replace stale duplicate facts with pointers, and correct contradictions. Use this skill whenever a document has been written or revised in the current phase, whenever you suspect a constraint in one document is not reflected in another, or whenever an agent reading multiple documents has flagged a conflict. Safe to re-run — applying it a second time produces the same result as the first.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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.

A well-crafted, self-contained instruction skill: concrete citation formats, explicit decision rules with edge-case handling, an ordered check sequence, and a final verification checklist with developer-facing flagging requirements. Its only weaknesses are minor — a trimmable rationale paragraph and reference data (the tier tables) inlined in a body slightly over the self-contained size threshold.

DimensionReasoningScore

Conciseness

The body is mostly efficient — compact tables for the document tiers, terse numbered checks, a citation format block, and a checklist — but the motivational paragraph ("A document set without citations drifts: the same constraint gets restated in multiple places, and when the source changes, the restatements don't...") explains why the task matters rather than how to do it and could be trimmed. Not a 5 because this rationale paragraph is a minor instance of over-explanation; not a 3 because nothing is padded and no concepts Claude already knows are re-taught.

4 / 5

Actionability

As an instruction-only skill the guidance is fully executable: exact citation formats to copy ("(see docs/constitution.md, Principle N)", "(see docs/architecture/decisions/[file].md, [section])"), exact file paths per document, and concrete decision rules with edge-case handling ("if the statement is a close paraphrase rather than an exact match, verify the intent before citing", "retain it in the most specific document... and replace the duplicate with a pointer").

5 / 5

Workflow Clarity

The workflow is clearly sequenced — "Read all existing documents from both tiers. For each derivative document, apply these checks in order" with four ordered checks — and this batch operation over multiple documents has explicit validation: the "Before finishing, verify:" checklist, plus error-recovery guidance ("flag it to the developer rather than guessing", "Do not silently correct — the developer needs to know") and a stop condition for missing constitution/glossary. The destructive/batch cap does not apply because validation is present.

5 / 5

Progressive Disclosure

The skill is self-contained with well-organized sections, two scannable tables, and no inlined bulk content that belongs in separate files, and the fallback section handles absent documents cleanly. It scores 4 rather than 5 because at ~90 lines it exceeds the under-50-line self-contained threshold, and the document-tier tables are the kind of reference data that could be offloaded to a bundle file if the document set grows.

4 / 5

Total

18

/

20

Passed

Description

92%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.

A strong description: third-person voice, concrete and comprehensive about what it does, explicit about when to use it with three natural trigger conditions, and clearly distinguishable from generic documentation skills. The only weakness is minor: it could include a few more synonyms (cross-reference, consistency, drift) users might naturally say.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — "add missing citations, replace stale duplicate facts with pointers, and correct contradictions" — and enumerates the exact document types in both tiers ("constitution, context, glossary, requirements"; "architecture decisions, architecture overview, MVP architecture spec, vision, implementation heuristics"), giving comprehensive coverage rather than minor gaps.

5 / 5

Completeness

It explicitly answers both questions: the "what" is concrete ("Scans all authoritative documents... to add missing citations, replace stale duplicate facts with pointers, and correct contradictions") and the "when" gives three concrete trigger conditions. Not a 4 because the when-clause is fully explicit with multiple specific triggers, matching the anchor-5 example pattern.

5 / 5

Trigger Term Quality

Natural trigger phrases are present ("whenever a document has been written or revised", "whenever you suspect a constraint in one document is not reflected in another", "flagged a conflict") plus keywords like citations, contradictions, and stale facts. A few natural synonyms users might say — e.g. "cross-reference", "consistency", "documentation drift" — are absent, so it falls just short of comprehensive.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — citation/consistency syncing across a specific project document set (constitution, glossary, requirements, architecture decisions) — with trigger conditions distinct from generic documentation skills, so conflict risk is minimal.

5 / 5

Total

19

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

Simonvm9114/flag-feedback

Path

.claude/skills/sync-docs/SKILL.md

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.