faq-generator

Generates FAQ lists from complex medical policies or protocols. Trigger when user provides medical documents, policies, or protocols and requests FAQ generation, patient education materials, or simplified explanations.

Quality

62%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Academic Writing/faq-generator/SKILL.md

Quality

Content

35%

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

The content has a solid executable core (CLI script, parameters, output schema) but is undermined by pervasive generic boilerplate, an off-topic scope statement, empty cross-references, and a broken example path. Tightening the prose and removing template filler would materially improve it.

Suggestions

Remove the off-topic and boilerplate sections (the "academic writing" bullet, empty "See ## Features/## Workflow above" pointers, and verbatim description restatements) to raise conciseness.

Fix the Example Usage path and provide a real copy-paste-ready invocation with sample input/output so the guidance is fully actionable.

Add an explicit output-validation feedback loop (generate → verify FAQ accuracy/coverage against the source → fix → re-run) to the Workflow, and either populate references/guidelines.md with substantive guidance or drop the reference if it adds no value.

Dimension	Reasoning	Score
Conciseness	The body is padded with off-topic and generic boilerplate (e.g. "academic writing tasks that require explicit assumptions, bounded scope", empty pointers like "See `## Features` above", and verbatim restatements of the description), which crowds the context with material Claude does not need.	1 / 3
Actionability	It provides concrete, executable elements (the `scripts/main.py` CLI, a Parameters table, and an Output Format JSON), but the Example Usage path is broken and the surrounding run-plan is abstract rather than copy-paste ready, leaving the guidance incomplete.	2 / 3
Workflow Clarity	A sequenced five-step Workflow with a stop-early validation checkpoint exists, but there is no validate→fix→retry feedback loop on output correctness for a script-execution skill, and the checkpoints remain largely implicit.	2 / 3
Progressive Disclosure	Real bundle files are referenced ("references/", "scripts/main.py") and the body is sectioned, but large amounts of generic inline content that should be externalized remain in SKILL.md and the reference file is only a 5-line stub, with weak (bare-text, non-link) signaling.	2 / 3
	Total	7 / 12 Passed

Description

90%

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 well-formed: third-person voice, explicit what-and-when structure, and natural trigger terms scoped to a clear niche. Its only weakness is specificity, naming a single core action rather than a breadth of concrete operations.

Dimension	Reasoning	Score
Specificity	Names the medical-policy/protocol domain and one concrete action ("Generates FAQ lists") but does not enumerate multiple distinct concrete actions, matching the "names domain and some actions" anchor rather than the comprehensive level.	2 / 3
Completeness	Explicitly states what it does ("Generates FAQ lists from complex medical policies or protocols") and when to use it ("Trigger when user provides medical documents...") with an explicit trigger clause, satisfying both what and when.	3 / 3
Trigger Term Quality	Covers natural phrasing a user would actually say — "medical documents", "policies", "protocols", "FAQ generation", "patient education materials", "simplified explanations" — giving good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	The medical-policy FAQ-generation niche with patient-education/simplification triggers is specific and unlikely to fire for unrelated skills.	3 / 3
	Total	11 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Commit: 7cc5680

Reviewed: 3 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.