Comprehensive documentation synchronization - scan local git changes and propagate updates to ALL design docs, task lists, specs, diagrams, and planning artifacts. Use when finishing a feature, after merging, or when design docs are out of date.
64
47%
Does it follow best practices?
Impact
93%
1.03xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/doc-sync-all/SKILL.mdQuality
Discovery
67%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 does a good job of answering both 'what' and 'when' with explicit trigger scenarios, which is its strongest aspect. However, the specific actions could be more concrete (e.g., what does 'propagate updates' actually entail?), and the trigger terms could cover more natural user phrasings. The description is reasonably distinctive but could overlap with general documentation or project management skills.
Suggestions
Add more concrete action verbs describing what the synchronization actually does, e.g., 'updates status fields in task lists, revises architecture diagrams, marks completed items in specs'.
Expand trigger terms with common user phrasings like 'sync docs', 'update documentation', 'docs are stale', 'keep docs in sync with code', 'README update'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (documentation synchronization) and some actions ('scan local git changes', 'propagate updates'), but the list of targets ('design docs, task lists, specs, diagrams, and planning artifacts') is more of a category enumeration than specific concrete actions like 'update sequence diagrams' or 'reconcile task completion status'. | 2 / 3 |
Completeness | Clearly answers both 'what' (scan git changes and propagate updates to design docs, task lists, specs, diagrams, planning artifacts) and 'when' (when finishing a feature, after merging, or when design docs are out of date) with explicit trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes some natural terms like 'design docs', 'task lists', 'specs', 'out of date', 'merging', and 'finishing a feature', but misses common variations users might say such as 'sync docs', 'update documentation', 'docs are stale', 'README', or 'changelog'. The phrase 'documentation synchronization' is somewhat formal. | 2 / 3 |
Distinctiveness Conflict Risk | The concept of syncing documentation after code changes is fairly specific, but terms like 'design docs', 'planning artifacts', and 'specs' could overlap with skills focused on documentation generation, project planning, or general doc editing. The git-change-driven aspect helps but isn't strongly differentiated. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is comprehensive in scope but suffers from significant verbosity—it explains many things Claude already knows (file categorization, what git commands do, generic project structures) and packs everything into a single monolithic file. The workflow is reasonably sequenced but lacks robust validation/feedback loops for what is essentially a batch document editing operation. The actionability is moderate: concrete git commands are provided but the core sync logic relies on procedural descriptions rather than executable patterns.
Suggestions
Cut the document inventory (Phase 2) and file detection patterns sections drastically—these are project-specific and should be discovered dynamically rather than enumerated generically. This alone would save ~80 lines.
Remove explanations of what git commands do and what design documents are—Claude knows these. Focus only on the non-obvious sync rules and decision logic.
Add explicit feedback loops to Phase 4: after applying updates, validate cross-references programmatically, and if validation fails, specify how to fix and retry before proceeding.
Split detailed per-document sync rules (Phase 3) into a separate reference file and keep only a summary table in the main SKILL.md to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Explains obvious concepts Claude already knows (what git status does, what design docs are, how to categorize file changes). The document inventory section is essentially a generic project structure listing that adds little actionable value. Many sections describe things Claude can infer rather than providing unique, non-obvious guidance. | 1 / 3 |
Actionability | Provides concrete bash commands for git analysis and specific sync rules with tables mapping change types to documents. However, much of the guidance is procedural description rather than executable steps—the 'validation pattern' is pseudocode, the 'change manifest' is a template rather than executable logic, and the tool usage in Step 4 is vague ('use appropriate tools'). The skill tells Claude what to do conceptually but lacks the precision needed for fully autonomous execution. | 2 / 3 |
Workflow Clarity | The 5-phase structure provides clear sequencing, and Phase 4 includes a verification step. However, the verification step is shallow ('re-read modified files to confirm changes') without explicit feedback loops for error recovery. For a skill involving potentially destructive batch edits across many documents, the lack of a validate-fix-retry loop and no rollback guidance caps this at 2. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no bundle files to offload detail into. The document inventory, file detection patterns, sync rules for 7+ document types, and sample invocations are all inline. Content like the glob patterns, the full document inventory tree, and the detailed per-document sync rules could easily be split into referenced files. With no bundle provided and everything crammed into one file, this is poorly structured for progressive disclosure. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
17bd06f
Table of Contents
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.