paper-narrative

Judge and reshape the story told by an entire paper figure deck. Use when writing or revising a paper to derive a grounded brief from the manuscript and captions, review the full deck as a handling editor, and hand an ordered figure arc to `figure-composer`.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

73%Weight 40%Scale 1-5

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

A dense, well-sequenced control-plane skill with strong validation discipline and an explicit convergence loop. Its main weaknesses are repetition of trust-label and identity caveats across sections and a monolithic single-file structure that inlines implementation-level code.

Suggestions

Consolidate the repeated trust-label and identity caveats (human review, never invent identities, immutable Versions) into the "Required inputs and trust labels" section and reference it once instead of restating in every phase.

Move the detailed `compositionQueue` JavaScript and persistent-map update code to a reference file (e.g. `references/composition-queue.md`), keeping a summary inline to reduce the monolithic body.

Show or reference the `narrative_review_task` generation and the `figure-composer` invocation shape so all steps are equally executable.

Dimension	Reasoning	Score
Conciseness	The body is information-dense and free of generic explanations Claude already knows, but safety caveats repeat across sections ("requires human review" appears in the inputs section, §1, and §2; "never invent an identity"/"immutable Version" restated in §2, §3, and §4) and the prose-to-code ratio could be tightened.	3 / 5
Actionability	Provides mostly executable guidance: an Ajv-validated brief-generation loop with corrective retry, `collectStructuredBatch`, and a complete `compositionQueue` builder with input validation. Minor gaps: `narrative_review_task` generation and the `figure-composer` handoff are described rather than shown.	4 / 5
Workflow Clarity	Four clearly numbered phases (brief → editorial review → composition → re-review) with explicit validation checkpoints (schema validation, `stopReason` check, fail-closed on unpublished Versions, verified composite IDs), an explicit coded convergence condition, and a defined re-review loop for error recovery.	5 / 5
Progressive Disclosure	No bundle files exist and none are referenced (all mentions are to the external `figure-composer` skill), so navigation is unbroken; sections are clearly headed and sequenced. The 17 KB monolithic body inlines detailed queue-building JavaScript that could be split out, which is a minor organization gap.	4 / 5
	Total	16 / 20 Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: third-person, concrete, with an explicit "Use when" clause and clear positioning within the figure workflow. The top-level verb is slightly abstract and a few natural trigger synonyms are missing, keeping specificity and trigger quality just below the top anchors.

Suggestions

Lead with a more concrete top-level action (e.g. "Derive a grounded story brief from a manuscript and captions, review the full figure deck as a handling editor, and hand an ordered figure arc to `figure-composer`") instead of the abstract "Judge and reshape the story".

Add natural trigger variations such as "figures", "revise/reorder paper figures", or file types (.tex, .pdf) to improve trigger-term coverage.

Sharpen the "when" clause to scope to figure-deck revision (e.g. "Use when revising a paper's figures or planning the figure order") to reduce overlap with general paper-writing skills.

Dimension	Reasoning	Score
Specificity	Lists several concrete third-person actions ("derive a grounded brief from the manuscript and captions", "review the full deck as a handling editor", "hand an ordered figure arc to `figure-composer`"), but the top-level action "Judge and reshape the story" is slightly abstract, leaving minor gaps versus the comprehensive anchor.	4 / 5
Completeness	Explicitly answers both what ("Judge and reshape the story told by an entire paper figure deck" with three concrete sub-actions) and when ("Use when writing or revising a paper to derive a grounded brief..."), with concrete trigger phrases present.	5 / 5
Trigger Term Quality	Good natural keyword coverage ("writing or revising a paper", "manuscript", "captions", "figure deck"), but common variations like standalone "figure(s)", "revise figures", and file extensions are missing, short of the synonyms-plus-extensions anchor.	4 / 5
Distinctiveness Conflict Risk	A clear niche (paper-level figure narrative) explicitly positioned upstream of `figure-composer`, with mostly distinct triggers; minor overlap risk with that closely related skill and with the broad "writing a paper" phrase.	4 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: aipoch/open-science
Path: resources/skills/paper-narrative/SKILL.md
Commit: bf35648

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

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.