semantic-scholar-database

Access the Semantic Scholar Graph API to search papers and retrieve paper/author/citation data when you need literature discovery or citation graph exploration.

Quality

74%

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

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Evidence Insight/semantic-scholar-database/SKILL.md

Quality

Content

63%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.

The body is well-sectioned with a complete, concrete usage example covering all four client operations and explicit parameter contracts. Its weaknesses are triple redundancy across When to Use/Key Features/Implementation Details, an orphaned references/api_docs.md whose endpoint details are duplicated inline, and a search example that mishandles the API's response envelope.

Suggestions

Collapse "When to Use", "Key Features", and "Implementation Details" into a single section that describes each operation exactly once.

Link references/api_docs.md from the body (e.g., under a "References" heading) instead of duplicating the base URL and endpoint list inline, and surface the concrete rate limits (100 requests per 5 minutes unauthenticated) it documents.

Unwrap the {"data": [...]} response envelope in scripts/client.py (or fix the example) so the search loop runs against the actual response shape, and add brief guidance on handling 429 rate-limit errors.

Dimension	Reasoning	Score
Conciseness	"When to Use", "Key Features", and "Implementation Details" each restate the same four operations (search, paper details, author details, citations/references) three times over, and hedging comments like "The exact keys depend on the fields requested by the client implementation" add tokens without actionable content. Not a 2 because it never explains concepts Claude already knows; not a 4 because the cross-section duplication is more than minor.	3 / 5
Actionability	A complete, syntactically runnable example imports from scripts.client and exercises all four operations with real identifiers and concrete parameters ("method="citations"\|"references""). Not a 5: search_papers and get_citations return the raw response envelope ({"total", "data"} objects per the actual API), so iterating `results` in the example's search loop would crash — the hedge comment does not fix this; more than pseudocode, so not a 3.	4 / 5
Workflow Clarity	The numbered example sequence (1-4) plus explicit parameter contracts ("method: must be either "citations" or "references"") give a clear sequence; these are read-only operations, so the destructive/batch cap does not apply. Minor validation gaps keep it at 4: despite noting "the API may enforce stricter rate limiting", there is no error-handling or 429-retry guidance.	4 / 5
Progressive Disclosure	Scored against the actual bundle: the body references scripts/client.py (a real file) but never mentions references/api_docs.md, which exists in the bundle — the reference file is orphaned while its content (base URL, endpoint list) is duplicated inline in "Implementation Details". Not a 2 because sections are well-organized and no large content block is inlined; not a 4 because the one reference file is not signaled at all.	3 / 5
	Total	14 / 20 Passed

Description

73%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.

The description names a specific API and several concrete capabilities with an explicit when-clause, making it distinct and reasonably complete. Its weaknesses are the second-person trigger phrasing (penalized by the rubric) and trigger coverage limited to literature discovery and citation graph exploration rather than the full operation set.

Suggestions

Use third-person or imperative trigger phrasing instead of "when you need", e.g. "Use when searching academic papers, building a literature review, or exploring citation networks."

Enumerate the concrete actions more distinctly, e.g. "Search papers, fetch paper and author details, and traverse citations and references via the Semantic Scholar Graph API."

Dimension	Reasoning	Score
Specificity	The description names the domain and several concrete actions — "search papers and retrieve paper/author/citation data" — which would fit anchor 4, but the second-person trigger clause "when you need literature discovery" incurs the rubric's third-person penalty (4 → 3), and coverage is incomplete (no distinct mention of author profiles or citation/references traversal direction).	3 / 5
Completeness	Both parts are explicit: the what ("Access the Semantic Scholar Graph API to search papers and retrieve paper/author/citation data") and the when ("when you need literature discovery or citation graph exploration"). Not a 5 because the when-clause covers only two triggers and omits paper-metadata lookup and author-profile use cases.	4 / 5
Trigger Term Quality	Natural phrases users would say are present: "search papers", "citation data", "literature discovery", "citation graph exploration". It falls short of anchor 5 because common variations and synonyms like "find papers", "literature review", or "academic papers" are missing.	4 / 5
Distinctiveness Conflict Risk	"Semantic Scholar Graph API" names a specific external service with distinct triggers ("literature discovery", "citation graph exploration"), giving it a clear niche with minimal conflict risk against generic document- or data-processing skills.	5 / 5
	Total	16 / 20 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
Path: scientific-skills/Evidence Insight/semantic-scholar-database/SKILL.md
Commit: 686e09d

Reviewed: 13 hours 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.