CtrlK
BlogDocsLog inGet started
Tessl Logo

doc-sync-all

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

1.03x
Quality

47%

Does it follow best practices?

Impact

93%

1.03x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.github/skills/doc-sync-all/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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'.

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
0xrabbidfly/eric-cartman
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.