CtrlK
BlogDocsLog inGet started
Tessl Logo

reference-style-sync

One-click synchronization and standardization of reference formats in literature management tools, intelligently fixing metadata errors.

32

Quality

16%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./scientific-skills/Academic Writing/reference-style-sync/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

17%

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 uses marketing-style language ('one-click', 'intelligently fixing') rather than concrete capability descriptions. It lacks a 'Use when...' clause entirely, and fails to include natural trigger terms that users would actually say when needing this skill. The domain is somewhat identifiable but not sharply defined.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'Zotero', 'Mendeley', 'BibTeX', '.bib files', 'citations', 'bibliography', 'reference list', 'citation formatting'.

Replace vague marketing language with specific actions, e.g., 'Normalizes citation styles (APA, MLA, Chicago), corrects DOIs and author names, deduplicates references in BibTeX/RIS files'.

Remove first-person-adjacent fluff like 'one-click' and 'intelligently' and instead describe concrete capabilities in third person (e.g., 'Synchronizes and standardizes reference entries across bibliography files').

DimensionReasoningScore

Specificity

Names the domain (literature management/reference formats) and some actions (synchronization, standardization, fixing metadata errors), but these are somewhat vague — 'one-click synchronization' and 'intelligently fixing' are more marketing language than concrete capability descriptions. It doesn't list specific actions like 'update DOIs, correct author names, normalize journal abbreviations'.

2 / 3

Completeness

Describes a vague 'what' but completely lacks a 'when' clause. There is no 'Use when...' or equivalent explicit trigger guidance, which per the rubric should cap completeness at 2, and the 'what' itself is weak enough to warrant a 1.

1 / 3

Trigger Term Quality

Lacks natural keywords users would actually say. Terms like 'literature management tools' and 'reference formats' are generic. Missing specific trigger terms like 'Zotero', 'Mendeley', 'BibTeX', 'citations', 'bibliography', '.bib files', 'DOI', or 'citation style'.

1 / 3

Distinctiveness Conflict Risk

The reference/literature management domain is somewhat specific, but 'metadata errors' and 'synchronization' are broad enough to overlap with other data management or file synchronization skills. Without naming specific tools or file formats, it's not clearly distinct.

2 / 3

Total

6

/

12

Passed

Implementation

14%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill suffers from severe bloat and repetition, with generic boilerplate sections (risk assessment, security checklist, lifecycle status, response template, evaluation criteria) that add no task-specific value. The useful domain content—repair rules, format examples, CLI parameters—is buried among redundant and circular sections. The workflow lacks specific validation checkpoints critical for batch bibliographic data modification.

Suggestions

Remove all generic boilerplate sections (Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria, Response Template, Output Requirements, Input Validation) and circular references ('See ## Features above') to reduce token count by ~60%.

Consolidate the three competing workflow descriptions into a single, concrete workflow with explicit validation steps: e.g., 'Run --check-only first, review report, then run with --fix-metadata, verify output entry count matches input.'

Move detailed repair rules and parameter tables to a separate reference file and link to it from a concise overview section.

Integrate the backup recommendation as step 1 of the workflow rather than burying it in Notes, since batch processing bibliographic data is a destructive operation.

DimensionReasoningScore

Conciseness

Extremely verbose and repetitive. Multiple sections reference each other circularly ('See ## Features above', 'See ## Prerequisites above', 'See ## Usage above'). The same description is repeated verbatim in multiple places. Boilerplate sections like 'Risk Assessment', 'Security Checklist', 'Lifecycle Status', 'Evaluation Criteria', and 'Response Template' add significant token bloat without providing actionable value. The skill explains basic concepts Claude already knows and includes generic workflow instructions that aren't specific to reference syncing.

1 / 3

Actionability

The skill provides concrete CLI examples and a Python API example with specific flags and parameters, plus before/after repair examples showing transformations. However, much of the code uses `python` comment syntax for what are plain text examples (not executable), and the core script `scripts/main.py` is referenced but never shown—it's unclear if it actually exists or works. The generic workflow steps (confirm inputs, validate scope, etc.) are abstract rather than concrete.

2 / 3

Workflow Clarity

There are multiple competing workflow sections ('Example Usage' run plan, 'Implementation Details', 'Workflow' section) that are all generic and vague. None provide specific validation checkpoints for the reference sync task. For a tool that batch-modifies bibliographic data (a potentially destructive operation), there are no explicit validation steps like 'verify output entry count matches input' or 'diff before/after'. The backup recommendation is buried in Notes rather than integrated into the workflow.

1 / 3

Progressive Disclosure

The document is a monolithic wall of text with 20+ sections, many of which are boilerplate or redundant. Circular references ('See ## Features above') add confusion rather than navigation. The single external reference (references/audit-reference.md) is vaguely described. Content that should be in separate files (repair rules, parameter tables, security checklists) is all inline, while the actual useful content is diluted by generic template sections.

1 / 3

Total

5

/

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
aipoch/medical-research-skills
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.