food-database-query

Food Database Query

Quality

12%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/food-database-query/SKILL.md

Quality

Content

13%Scale 1-5

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

This skill reads more like a product specification document or API design doc than an actionable skill for Claude. It is severely bloated with pseudocode, raw data structures, roadmap items, and explanatory content that doesn't help Claude perform the task. The core problem is that it describes a system rather than instructing Claude on how to query and use the actual data files.

Suggestions

Reduce to under 100 lines: remove roadmap, quality assurance, team info, version metadata, and concept explanations. Focus only on how Claude should query the JSON files and format responses.

Replace pseudocode with actual executable code or clear instructions referencing the real data files (data/food-database.json, data/food-categories.json) with concrete jq-style queries or Python snippets that work against the actual schema.

Move the full JSON data structure example, RDA reference values, and category hierarchy into separate bundle files (e.g., SCHEMA.md, RDA_REFERENCE.md) and reference them from the main skill.

Add validation steps: what to do when a food isn't found, how to handle ambiguous portion inputs, and how to verify calculation results before presenting to users.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at 500+ lines. Extensively explains concepts Claude already knows (what fuzzy search is, how Levenshtein distance works, what RDA values are, basic Python patterns). Includes roadmap sections, quality assurance boilerplate, team info, and version metadata that waste tokens. The full JSON data structure example alone is ~60 lines of raw data that belongs in the referenced data file, not the skill.	1 / 5
Actionability	The code examples are pseudocode illustrating concepts rather than executable implementations. Functions like `extract_food_name()`, `normalize_food_name()`, `query_database()` are referenced but never defined. The skill describes what a system would do rather than giving Claude concrete instructions on what to actually execute. The /nutrition commands are shown but there's no indication these are real commands or how they're implemented.	2 / 5
Workflow Clarity	While there are numbered steps in some sections (e.g., the breakfast recording example), there are no validation checkpoints, no error handling guidance, and no feedback loops. The 'query flow' steps are vague ('search for matching items', 'return complete nutrition info'). There's no guidance on what to do when a food isn't found, when portion parsing fails, or when data is ambiguous.	2 / 5
Progressive Disclosure	This is a monolithic wall of text with everything inlined. The full JSON data structure, RDA reference tables, all pseudocode examples, roadmap, quality assurance, and technical implementation details are all in one massive file. Content like the complete food data structure, RDA values, and category hierarchies clearly belong in separate referenced files. No bundle files are provided despite references to data/food-database.json and data/food-categories.json.	1 / 5
	Total	6 / 20 Passed

Description

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

This description is essentially just a title rather than a functional skill description. It lacks any concrete actions, trigger phrases, or 'when to use' guidance, making it nearly useless for Claude to distinguish from other skills or know when to select it.

Suggestions

Expand the description to list specific actions, e.g., 'Searches food databases for nutritional information, retrieves calorie counts, macronutrient breakdowns, and ingredient lists.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about food nutrition, calories, macros, ingredients, or dietary information.'

Include synonyms and natural language variations users might say, such as 'nutrition lookup', 'calorie check', 'food facts', 'dietary data'.

Dimension	Reasoning	Score
Specificity	The description 'Food Database Query' names a domain (food database) and a vague action (query), but provides no concrete actions like searching, filtering, retrieving nutritional data, etc. It reads more like a title than a description of capabilities.	1 / 5
Completeness	There is no clear 'what' beyond a vague label, and no 'when' clause at all. It fails to answer either 'what does this do' or 'when should Claude use it' in any meaningful way.	1 / 5
Trigger Term Quality	Contains 'food' and 'database' and 'query' which are somewhat relevant keywords, but misses natural user phrases like 'nutrition', 'calories', 'ingredients', 'recipe lookup', 'food search', or any synonyms users would naturally say.	2 / 5
Distinctiveness Conflict Risk	'Food Database Query' is somewhat specific to food data, but 'database query' is extremely broad and could overlap with any database-related skill. Without specifying what kind of food data or what operations are performed, conflict risk is high.	2 / 5
	Total	6 / 20 Passed

Validation

72%

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 — 8 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (788 lines); consider splitting into references/ and linking	Warning
description_field	'description' is very short (19 chars), consider making it more detailed	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	8 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/food-database-query/SKILL.md
Commit: 57c135b

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