grill-with-docs

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

Quality

58%

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 ./.github/skills/grill-with-docs/SKILL.md

Quality

Content

53%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-organized, lean, and gives genuinely actionable interview guidance with good example phrasings. Its biggest defect is the two missing referenced format files, which breaks progressive disclosure and leaves the documentation-format step non-executable.

Suggestions

Add the missing CONTEXT-FORMAT.md and ADR-FORMAT.md (under ./references/ or alongside SKILL.md) so the 'Use the format in ...' pointers resolve, or inline a minimal format spec and drop the links.

Add a brief validation/consistency check after inline CONTEXT.md updates (e.g. confirm the new term does not collide with an existing glossary entry) to give the workflow an explicit checkpoint.

Tighten the two ASCII file-structure trees into one compact example to lift conciseness toward 5.

Dimension	Reasoning	Score
Conciseness	The body is largely lean and assumes Claude's competence (e.g. the ADR criteria, the inline update guidance), with the ASCII file-structure trees and example quotes earning their place; only minor stretches like the two full tree diagrams could be trimmed.	4 / 5
Actionability	Core guidance is concrete with copy-ready example phrasings ('Your glossary defines cancellation as X, but you seem to mean Y'), but the two format pointers ('Use the format in [CONTEXT-FORMAT.md]', '[ADR-FORMAT.md]') target files that do not exist in the bundle, leaving a real execution gap.	3 / 5
Workflow Clarity	A sequence is present (interview one question at a time, explore codebase when answerable, resolve design-tree branches, update CONTEXT.md inline, offer ADRs by the three criteria) with the per-question feedback loop acting as a checkpoint, but there is no verification that inline CONTEXT.md/ADR updates stay consistent or correct.	3 / 5
Progressive Disclosure	Section structure is reasonable and the two format references are clearly signaled as one-level-deep markdown links, but those referenced files (CONTEXT-FORMAT.md, ADR-FORMAT.md) are absent from the skill directory, so navigation is broken and Claude is stranded at the pointer.	2 / 5
	Total	12 / 20 Passed

Description

62%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 solid description that clearly states both capability and trigger, anchored in a specific domain-modeling niche. Its main weaknesses are the second-person phrasing, modest trigger-term coverage, and a 'when' clause that could name the plan types more concretely.

Suggestions

Rewrite verb phrases in third person (e.g. 'Challenges the user's plan against the existing domain model') to satisfy the voice rule and recover the specificity point.

Broaden trigger terms with natural synonyms a user would say, e.g. 'Use when the user wants to stress-test, pressure-test, or review a design plan against their project's ubiquitous language and documented decisions.'

Make the 'when' clause more specific about plan type (architecture, feature design, domain modeling) to push completeness toward 5.

Dimension	Reasoning	Score
Specificity	Names three concrete actions ('challenges your plan against the existing domain model', 'sharpens terminology', 'updates documentation (CONTEXT.md, ADRs) inline'), but the second-person 'your plan' violates the third-person-voice rule, reducing the score by one from a 4.	3 / 5
Completeness	Both halves are present and explicit: the 'what' (grilling session that challenges/sharpens/updates docs) and the 'when' ('Use when user wants to stress-test a plan against their project's language and documented decisions'), though the 'when' could be more specific about which kinds of plans.	4 / 5
Trigger Term Quality	'stress-test a plan against their project's language and documented decisions' is a reasonably natural phrase, but coverage of synonyms and variations a user would actually say (e.g. 'review my design', 'pressure-test my architecture') is thin, so it sits between the 'some relevant keywords' and 'good coverage' anchors.	3 / 5
Distinctiveness Conflict Risk	The DDD-flavored niche (domain model, CONTEXT.md glossary, ADRs, terminology sharpening) is mostly distinct with clear triggers, with only minor overlap risk against generic plan-review skills.	4 / 5
	Total	14 / 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
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: microsoft/fabric-task-flows
Path: .github/skills/grill-with-docs/SKILL.md
Commit: 3764df9

Reviewed: 1 day 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.