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

86%

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

Quality

Content

85%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-structured, actionable instruction skill with a clear sequenced workflow, explicit fallback conditions, and a closing verification checklist. Its main weakness is a somewhat long rationale paragraph that pads the otherwise lean body.

Suggestions

Tighten the opening rationale paragraph ("A document set without citations drifts...") to one or two sentences to improve token efficiency without losing the motivation.

Add brief guidance on how to locate the matching constitution principle when a restatement is a close paraphrase, to reduce ambiguity in check 1.

Dimension	Reasoning	Score
Conciseness	The body is largely efficient and assumes Claude's competence, but the opening rationale paragraph ('A document set without citations drifts...') explains a general principle at some length that could be trimmed without losing actionable value.	4 / 5
Actionability	Concrete, specific guidance is given — exact citation formats, ordering rules ('retain it in the most specific document'), and a fallback policy — but it is instruction rather than executable code, with minor gaps in edge-case handling (e.g. how to locate a matching principle).	4 / 5
Workflow Clarity	A clear sequenced workflow ('Read all existing documents... apply these checks in order') with explicit fallback/stop conditions for missing required files and a final output-quality checklist with feedback to the developer on corrections.	5 / 5
Progressive Disclosure	For a self-contained instruction skill under 50 lines with no bundle files, the body is well organized into clearly headed sections (Document Tiers, Checks, Fallback, Citation Format, Output Quality Check) requiring no external references.	5 / 5
	Total	18 / 20 Passed

Description

87%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, well-scoped description that clearly states both what it does and when to use it with concrete trigger phrases. It is specific and distinct; the only minor weakness is reliance on project-specific document names rather than broadly natural synonyms in its trigger terms.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — 'add missing citations', 'replace stale duplicate facts with pointers', and 'correct contradictions' — applied across a clearly enumerated document set, though the actions are conceptual rather than mechanically distinct, leaving minor coverage gaps versus the comprehensive anchor.	4 / 5
Completeness	It explicitly answers what ('Scans all authoritative... and all derivative... to add missing citations, replace stale duplicate facts with pointers, and correct contradictions') and when ('Use this skill whenever...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural triggers like 'whenever a document has been written or revised' and 'whenever an agent reading multiple documents has flagged a conflict' map well to user/agent speech, but it relies on several project-specific document names rather than broadly natural synonyms.	4 / 5
Distinctiveness Conflict Risk	The niche is narrow and specific to citation/consistency maintenance of a tiered document set, with triggers tied to document revision and inter-document conflicts, giving minimal overlap with other skills.	5 / 5
	Total	18 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: Simonvm9114/flag-feedback
Path: .claude/skills/sync-docs/SKILL.md
Commit: c5bcbb3

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.