figure-reference-checker
Use figure reference checker for academic writing workflows that need structured execution, explicit assumptions, and clear output boundaries.
36
33%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./scientific-skills/Academic Writing/figure-reference-checker/SKILL.mdQuality
Discovery
40%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 fails to explain what the skill actually does—it names itself ('figure reference checker') but never describes concrete actions like detecting missing figure references, validating numbering sequences, or checking cross-reference consistency. The 'when' clause uses abstract process language ('structured execution, explicit assumptions, clear output boundaries') rather than practical trigger scenarios. Overall, it reads more like a meta-description of a methodology than a functional skill description.
Suggestions
Add concrete actions the skill performs, e.g., 'Checks that all figures in academic manuscripts are properly referenced in the text, detects orphaned figure labels, and validates sequential numbering.'
Replace the abstract 'when' clause with practical triggers, e.g., 'Use when reviewing a paper or manuscript for missing or broken figure references, or when preparing a document for submission.'
Include natural trigger terms users would say, such as 'figure numbers', 'cross-references', 'missing figures', 'manuscript review', 'LaTeX', '.tex files'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description does not list any concrete actions. 'Figure reference checker' names a tool but doesn't describe what it does (e.g., detect missing references, find broken figure links, validate numbering). 'Structured execution, explicit assumptions, and clear output boundaries' is abstract fluff. | 1 / 3 |
Completeness | It has a 'Use when' clause ('for academic writing workflows that need structured execution...'), but the 'what' is essentially missing—there's no description of what the skill actually does. The 'when' clause is also vague and process-oriented rather than task-oriented. | 2 / 3 |
Trigger Term Quality | It includes 'figure reference checker' and 'academic writing' which are somewhat relevant keywords a user might use, but misses natural variations like 'figure numbers', 'cross-references', 'LaTeX', 'manuscript', 'citation', or specific file types. | 2 / 3 |
Distinctiveness Conflict Risk | 'Figure reference checker' is somewhat distinctive as a niche, but the vague framing around 'academic writing workflows' and 'structured execution' could overlap with other academic writing or document checking skills. The lack of concrete actions makes it harder to distinguish. | 2 / 3 |
Total | 7 / 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 heavily padded with boilerplate, repetitive sections, and circular internal references that waste tokens without adding value. While it does provide some concrete commands and a parameter table, the core task—checking figure reference consistency—is barely explained in terms of actual behavior, expected inputs/outputs, or examples. The document reads more like a generic skill template that was minimally customized than a purposeful guide for Claude.
Suggestions
Remove all circular self-references ('See ## Features above') and consolidate duplicated content (py_compile appears 3 times, script path appears 5+ times) into a single concise section.
Strip boilerplate sections that don't add task-specific value (Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria) or move them to a separate reference file.
Add a concrete example showing sample input (a manuscript snippet with figure references) and expected output (the checker's report identifying orphaned references or inconsistencies).
Replace the generic workflow steps with task-specific steps, e.g., '1. Parse manuscript for \\ref{fig:*} patterns, 2. Extract figure labels from \\label{fig:*}, 3. Report mismatches' with explicit validation of the parse step.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose and repetitive. Multiple sections reference each other circularly ('See ## Features above', 'See ## Prerequisites above', 'See ## Usage above'). The same information (e.g., py_compile command, script path) is repeated across Quick Check, Audit-Ready Commands, Example Usage, and Implementation Details. Boilerplate sections like Risk Assessment, Security Checklist, Lifecycle Status, and Evaluation Criteria add significant token cost with minimal actionable value for Claude. | 1 / 3 |
Actionability | There are some concrete commands (python scripts/main.py --manuscript paper.docx) and a parameters table, which is helpful. However, much of the content is abstract process description ('validate the request, choose the packaged workflow, and produce a bounded deliverable') rather than executable guidance. The actual features (detect orphaned references, check label consistency) lack implementation details or examples of what output looks like. | 2 / 3 |
Workflow Clarity | The Workflow section provides a numbered sequence and the Error Handling section describes fallback behavior, which is good. However, the workflow steps are generic process management steps ('Confirm the user objective') rather than task-specific figure-reference-checking steps. There are no validation checkpoints specific to the actual operation (e.g., verifying the manuscript was parsed correctly, checking output completeness). The run plan in Example Usage is slightly more concrete but still lacks validation gates. | 2 / 3 |
Progressive Disclosure | The document contains circular self-references ('See ## Features above for related details' placed before the Features section appears, 'See ## Prerequisites above' before Prerequisites). References to bundle files (references/audit-reference.md, scripts/main.py) cannot be verified as no bundle files are provided. The content is a monolithic wall of boilerplate sections that could be dramatically condensed, with no meaningful hierarchical organization. | 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 | |
- Repository
- aipoch/medical-research-skills
- Commit
73f6514
- 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.