Use figure reference checker for academic writing workflows that need structured execution, explicit assumptions, and clear output boundaries.
39
24%
Does it follow best practices?
Impact
Pending
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
22%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 is too vague and process-oriented, failing to specify what the skill concretely does (e.g., detect broken figure references, validate numbering consistency) or when it should be triggered. The phrases 'structured execution, explicit assumptions, and clear output boundaries' read as abstract methodology descriptors rather than actionable capability descriptions. It needs substantial revision to be useful for skill selection.
Suggestions
Replace abstract process language with concrete actions, e.g., 'Checks that all figure references in academic manuscripts match existing figures, detects broken cross-references, and flags missing or duplicate figure numbers.'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about figure references, cross-references, figure numbering, or validating references in LaTeX/Word manuscripts.'
Remove vague qualifiers like 'structured execution, explicit assumptions, and clear output boundaries' which describe process qualities rather than skill capabilities.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description does not list any concrete actions. 'Figure reference checker' names a tool but 'structured execution, explicit assumptions, and clear output boundaries' are abstract process descriptors, not specific capabilities like 'validates figure numbering' or 'detects missing cross-references'. | 1 / 3 |
Completeness | The 'what' is extremely weak—there is no explanation of what the skill actually does beyond its name. The 'when' clause ('for academic writing workflows that need structured execution...') is vague and process-oriented rather than providing explicit triggers. It fails to clearly answer either question. | 1 / 3 |
Trigger Term Quality | 'Figure reference checker' and 'academic writing' are relevant keywords a user might use, but common variations like 'cross-references', 'figure numbers', 'LaTeX', 'manuscript', or 'citation' are missing, limiting discoverability. | 2 / 3 |
Distinctiveness Conflict Risk | 'Figure reference checker' is a somewhat specific niche, but the vague qualifiers ('structured execution, explicit assumptions, clear output boundaries') could overlap with any academic writing or quality-checking skill. Without concrete actions, it's hard to distinguish from general academic proofreading skills. | 2 / 3 |
Total | 6 / 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 content, and circular internal references that waste tokens without adding value. While it provides some concrete commands and a parameter table, the actual domain-specific guidance for figure reference checking is minimal — most content is generic process management scaffolding. The organization is poor, with related sections scattered and multiple sections referencing each other in confusing ways.
Suggestions
Remove all circular cross-references ('See ## Features above for related details') and consolidate related content into a single, well-ordered flow: purpose → usage → workflow → error handling.
Cut boilerplate sections (Risk Assessment, Security Checklist, Lifecycle Status, Evaluation Criteria, Response Template) that don't help Claude execute the task — these consume tokens without adding actionable guidance.
Add specific examples of figure reference checker output (e.g., what an orphaned reference report looks like, what figure-label inconsistency output contains) so Claude knows what to expect and can validate results.
Deduplicate the repeated script paths and validation commands — the py_compile check and scripts/main.py path appear in at least 4 different sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose and repetitive. Multiple sections reference each other circularly (e.g., 'See `## Features` above for related details' when Features is defined below). The same information (script path, validation commands, workflow steps) is repeated across multiple sections. 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, py_compile check) and a parameter table, but the actual figure-checking logic is entirely delegated to the script with no explanation of what it does internally. The workflow steps are generic process management instructions rather than specific guidance for figure reference checking. Much of the content is procedural boilerplate rather than task-specific executable guidance. | 2 / 3 |
Workflow Clarity | There is a numbered workflow with steps and error handling guidance, but validation checkpoints are weak — the only validation is py_compile (syntax check), not output validation. The workflow steps are generic ('Confirm the user objective', 'Validate that the request matches documented scope') rather than specific to figure reference checking. No feedback loop for verifying the checker's output correctness. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with many sections that repeat information. Circular cross-references ('See ## Features above') point to sections that are defined later in the same file, creating confusion. The single external reference (references/audit-reference.md) is mentioned but the skill itself contains excessive inline content that should either be trimmed or properly split. The organization is poor with related content scattered across non-adjacent sections (e.g., Parameters, Usage, and Features are separated by Workflow). | 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 | |
8277276
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.