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

78%

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

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

Quality

Content

68%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 content is concise and actionable with a clear interview-driven workflow, but it is held back by missing validation checkpoints for inline file writes and two broken references to format files that do not exist in the bundle.

Suggestions

Add an explicit validation checkpoint before writing files: e.g., confirm the resolved term with the user before updating CONTEXT.md, and confirm the three ADR criteria are all satisfied before proposing an ADR.

Create the referenced CONTEXT-FORMAT.md and ADR-FORMAT.md files (or remove the links and inline the minimal formats) so the progressive-disclosure references resolve to real content.

Tighten the workflow with a short ordered checklist (e.g., per-question loop: ask → explore codebase if answerable → challenge glossary → resolve → update CONTEXT.md if a term crystallized) to make the sequence and its checkpoints explicit.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-organized with no padding of concepts Claude already knows; every section (what-to-do, supporting-info, ASCII trees, ADR criteria) earns its place.	5 / 5
Actionability	Provides concrete behavioral guidance and example dialogue ('Your glossary defines cancellation as X, but you seem to mean Y — which is it?') plus a precise three-criteria ADR checklist, though some guidance is illustrative rather than fully prescriptive.	4 / 5
Workflow Clarity	The session sequence is clear (interview → explore → challenge → sharpen → cross-reference → update docs → offer ADRs), but file-writing operations like updating CONTEXT.md and creating ADRs have no validation checkpoint (e.g., confirm the term with the user before writing), which caps this score per the destructive-operation guideline.	3 / 5
Progressive Disclosure	The body references ./CONTEXT-FORMAT.md and ./ADR-FORMAT.md for format details, but neither file exists in the bundle (no references/, scripts/, or assets/ directories), so the navigation links are dead and a reader cannot reach the referenced material.	2 / 5
	Total	14 / 20 Passed

Description

87%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 is specific, complete, and distinctive, clearly stating both what the skill does and when to use it with natural trigger language. Minor keyword synonym coverage is the only weakness.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions — challenges the plan against the domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) — but does not fully enumerate the full range of behaviors, leaving minor coverage gaps.	4 / 5
Completeness	Clearly states what the skill does (grills the plan, sharpens terminology, updates docs) and provides an explicit 'Use when user wants to stress-test a plan...' trigger with concrete phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('stress-test a plan', 'project's language', 'documented decisions') plus concrete artifacts (CONTEXT.md, ADRs), though it lacks common synonyms like 'glossary' or 'ubiquitous language'.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (domain-model stress-testing paired with inline CONTEXT.md/ADR documentation) with distinct triggers and minimal overlap with other skills.	5 / 5
	Total	18 / 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: flutter/agent-plugins
Path: .agents/agents/reidbaker-agent/skills/grill-with-docs/SKILL.md
Commit: 864cf87

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.