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

83%

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

The canonical home for this skill is grill-with-docs in mattpocock/skills

Quality

Content

92%Scale 1-3

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

This is a well-crafted skill that provides clear, actionable guidance for domain model grilling sessions. It excels at conciseness and actionability — every instruction is specific and purposeful, with concrete examples of what to say and when. The only weakness is the inability to verify the referenced format files (CONTEXT-FORMAT.md, ADR-FORMAT.md), though the references themselves are well-structured.

Dimension	Reasoning	Score
Conciseness	Every section earns its place. No unnecessary explanations of what grilling sessions are or how interviews work. The file structure examples are compact and directly useful for locating documentation. Instructions are terse and assume Claude's competence.	3 / 3
Actionability	Provides highly specific, concrete guidance: exact phrases to use when challenging terminology ('Your glossary defines X but you seem to mean Y'), precise criteria for ADR creation (three conditions), explicit instructions to update CONTEXT.md inline rather than batching, and clear direction to explore the codebase rather than asking answerable questions.	3 / 3
Workflow Clarity	The workflow is clear: interview one question at a time, challenge against glossary, sharpen terms, discuss concrete scenarios, cross-reference code, update CONTEXT.md inline as decisions crystallize, and offer ADRs only when three specific criteria are met. The single-question-at-a-time constraint and inline update rule serve as natural checkpoints.	3 / 3
Progressive Disclosure	References to CONTEXT-FORMAT.md and ADR-FORMAT.md are well-signaled and one level deep, which is good. However, since no bundle files were provided, we cannot verify these references resolve correctly. The file structure examples are inline but appropriately sized. Minor concern: the supporting-info section could arguably be split, but it's not egregiously long.	2 / 3
	Total	11 / 12 Passed

Description

75%Scale 1-3

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 has good completeness with an explicit 'Use when' clause and a distinctive niche combining domain model validation with documentation updates. However, the language is somewhat metaphorical ('grilling session', 'sharpens terminology') rather than listing precise concrete actions, and the trigger terms could cover more natural user phrasings. The use of second person ('your plan') should also be noted as a minor style issue.

Suggestions

Replace metaphorical language with more concrete actions, e.g., 'Validates plan terminology against the existing domain model, identifies inconsistencies, and updates CONTEXT.md and ADRs as decisions are made.'

Add more natural trigger term variations in the 'Use when' clause, e.g., 'Use when user wants to review, validate, or stress-test a plan against their domain model, check naming consistency, or update architecture decision records.'

Dimension	Reasoning	Score
Specificity	Names the domain ('plan', 'domain model', 'terminology') and some actions ('challenges your plan', 'sharpens terminology', 'updates documentation'), but the actions are somewhat abstract—'grilling session' and 'sharpens terminology' are more metaphorical than concrete. It does mention specific artifacts (CONTEXT.md, ADRs) which adds some concreteness.	2 / 3
Completeness	Clearly answers both 'what' (challenges plan against domain model, sharpens terminology, updates CONTEXT.md and ADRs) and 'when' (explicit 'Use when user wants to stress-test a plan against their project's language and documented decisions').	3 / 3
Trigger Term Quality	Includes some relevant terms like 'stress-test', 'plan', 'domain model', 'ADRs', 'CONTEXT.md', and 'terminology', but misses common natural variations a user might say such as 'review my plan', 'domain-driven design', 'architecture review', 'challenge my design', or 'validate decisions'. The trigger terms are somewhat niche.	2 / 3
Distinctiveness Conflict Risk	The combination of plan stress-testing against a domain model, terminology refinement, and inline documentation updates (CONTEXT.md, ADRs) creates a very specific niche that is unlikely to conflict with other skills like general code review or documentation generation.	3 / 3
	Total	10 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: SnowingFox/ai-skills
Path: .cursor/skills/grill-with-docs/SKILL.md
Commit: d6882ad

Reviewed: ~14 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.